Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 215 lines (151 sloc) 6.32 kB
1b63fb3 @laserlemon Start writing new README
laserlemon authored
1 Audited [![Build Status](https://secure.travis-ci.org/collectiveidea/audited.png)](http://travis-ci.org/collectiveidea/audited) [![Dependency Status](https://gemnasium.com/collectiveidea/audited.png)](https://gemnasium.com/collectiveidea/audited)
2 =======
3
4 **Audited** (previously acts_as_audited) is an ORM extension that logs all changes to your models. Audited also allows you to record who made those changes, save comments and associate models related to the changes. Audited works with Rails 3.
5
6 ## Supported Rubies
7
8 Audited supports and is [tested against](http://travis-ci.org/collectiveidea/audited) the following Ruby versions:
9
10 * 1.8.7
11 * 1.9.2
12 * 1.9.3
13 * Head
14
15 Audited may work just fine with a Ruby version not listed above, but we can't guarantee that it will. If you'd like to maintain a Ruby that isn't listed, please let us know with a [pull request](https://github.com/collectiveidea/audited/pulls).
16
17 ## Supported ORMs
18
19 In a previous life, Audited was ActiveRecord-only. Audited will now audit models for the following backends:
20
21 * ActiveRecord
22 * MongoMapper
23
24 ## Installation
25
26 The installation process depends on what ORM your app is using.
27
28 ### ActiveRecord
29
30 Add the appropriate gem to your Gemfile:
31
32 ```ruby
33 gem "audited-activerecord", "~> 3.0"
34 ```
35
36 Then, from your Rails app directory, create the `audits` table:
37
38 ```bash
39 $ rails generate audited:install
40 $ rake db:migrate
41 ```
42
26dfd71 @laserlemon Finish writing the README
laserlemon authored
43 #### Upgrading
44
45 If you're already using Audited (or acts_as_audited), your `audits` table may require additional columns. After every upgrade, please run:
46
47 ```bash
48 $ rails generate audited:upgrade
49 $ rake db:migrate
50 ```
51
52 Upgrading will only make changes if changes are needed.
53
1b63fb3 @laserlemon Start writing new README
laserlemon authored
54 ### MongoMapper
55
56 ```ruby
57 gem "audited-mongo_mapper", "~> 3.0"
58 ```
59
26dfd71 @laserlemon Finish writing the README
laserlemon authored
60 ## Usage
1b63fb3 @laserlemon Start writing new README
laserlemon authored
61
26dfd71 @laserlemon Finish writing the README
laserlemon authored
62 Simply call `audited` on your models:
1b63fb3 @laserlemon Start writing new README
laserlemon authored
63
26dfd71 @laserlemon Finish writing the README
laserlemon authored
64 ```ruby
65 class User < ActiveRecord::Base
66 audited
67 end
1b63fb3 @laserlemon Start writing new README
laserlemon authored
68 ```
69
26dfd71 @laserlemon Finish writing the README
laserlemon authored
70 By default, whenever a user is created, updated or destroyed, a new audit is created.
1b63fb3 @laserlemon Start writing new README
laserlemon authored
71
26dfd71 @laserlemon Finish writing the README
laserlemon authored
72 ```ruby
73 user = User.create!(:name => "Steve")
74 user.audits.count # => 1
75 user.update_attributes!(:name => "Ryan")
76 user.audits.count # => 2
77 user.destroy
78 user.audits.count # => 3
79 ```
1b63fb3 @laserlemon Start writing new README
laserlemon authored
80
26dfd71 @laserlemon Finish writing the README
laserlemon authored
81 Audits contain information regarding what action was taken on the model and what changes were made.
82
83 ```ruby
84 user.update_attributes!(:name => "Ryan")
85 audit = user.audits.last
86 audit.action # => "update"
87 audit.audited_changes # => {"name"=>["Steve", "Ryan"]}
88 ```
89
90 ### Comments
91
92 You can attach comments to each audit using an `audit_comment` attribute on your model.
93
94 ```ruby
95 user.update_attributes!(:name => "Ryan", :audit_comment => "Changing name, just because")
96 user.audits.last.comment # => "Changing name, just because"
97 ```
98
99 You can optionally add the `:comment_required` option to your `audited` call to require comments for all audits.
1b63fb3 @laserlemon Start writing new README
laserlemon authored
100
101 ```ruby
102 class User < ActiveRecord::Base
26dfd71 @laserlemon Finish writing the README
laserlemon authored
103 audited :comment_required => true
104 end
105 ```
106
107 ### Current User Tracking
108
109 If you're using Audited in a Rails application, all audited changes made within a request will automatically be attributed to the current user. By default, Audited uses the `current_user` method in your controller.
110
111 ```
112 class PostsController < ApplicationController
113 def create
114 current_user # => #<User name: "Steve">
115 @post = Post.create(params[:post])
116 @post.audits.last.user # => #<User name: "Steve">
117 end
118 end
119 ```
120
121 To use a method other than `current_user`, put the following in an intializer:
122
123 ```ruby
124 Audited.current_user_method = :authenticated_user
125 ```
126
127 Outside of a request, Audited can still record the user with the `as_user` method:
128
129 ```ruby
130 Audit.as_user(User.find(1)) do
131 post.update_attribute!(:title => "Hello, world!")
132 end
133 post.audits.last.user # => #<User id: 1>
134 ```
135
136 ### Associated Audits
137
138 Sometimes it's useful to associate an audit with a model other than the one being changed. For instance, given the following models:
139
140 ```ruby
141 class User < ActiveRecord::Base
142 belongs_to :company
1b63fb3 @laserlemon Start writing new README
laserlemon authored
143 audited
144 end
26dfd71 @laserlemon Finish writing the README
laserlemon authored
145
146 class Company < ActiveRecord::Base
147 has_many :users
148 end
1b63fb3 @laserlemon Start writing new README
laserlemon authored
149 ```
150
26dfd71 @laserlemon Finish writing the README
laserlemon authored
151 Every change to a user is audited, but what if you want to grab all of the audits of users belonging to a particular company? You can add the `:associated_with` option to your `audited` call:
152
153 ```ruby
154 class User < ActiveRecord::Base
155 belongs_to :company
156 audited :associated_with => :company
157 end
158
159 class Company < ActiveRecord::Base
160 has_many :users
161 has_associated_audits
162 end
163 ```
164
165 Now, when a audit is created for a user, that user's company is also saved alongside the audit. This makes it much easier (and faster) to access audits indirectly related to a company.
166
167 ```ruby
168 company = Company.create!(:name => "Collective Idea")
169 user = company.users.create!(:name => "Steve")
170 user.update_attribute!(:name => "Steve Richert")
171 user.audits.last.associated # => #<Company name: "Collective Idea">
172 company.associated_audits.last.auditable # => #<User name: "Steve Richert">
173 ```
174
175 ## Gotchas
176
ec4732f @ersatzryan Default to using attr_accessible
ersatzryan authored
177 ### Accessible Attributes
26dfd71 @laserlemon Finish writing the README
laserlemon authored
178
ec4732f @ersatzryan Default to using attr_accessible
ersatzryan authored
179 Audited assumes you are using `attr_accessible`, however, if you are using `attr_protected` or just going at it unprotected you will have to set the `:allow_mass_assignment => true` option.
180
181 If using `attr_protected` be sure to add `audit_ids` to the list of protected attributes to prevent data loss.
182
183 ```ruby
184 class User < ActiveRecord::Base
185 audited :allow_mass_assignment => true
186 end
187 ```
26dfd71 @laserlemon Finish writing the README
laserlemon authored
188
189 ```ruby
190 class User < ActiveRecord::Base
ec4732f @ersatzryan Default to using attr_accessible
ersatzryan authored
191 audited :allow_mass_assignment => true
192 attr_protected :logins, :audit_ids
26dfd71 @laserlemon Finish writing the README
laserlemon authored
193 end
194 ```
195
196 ### MongoMapper Embedded Documents
197
198 Currently, Audited does not track changes on embedded documents. Audited works by tracking a model's [dirty changes](http://api.rubyonrails.org/classes/ActiveModel/Dirty.html) but changes to embedded documents don't appear in dirty tracking.
199
200 ## Support
201
202 You can find documentation at: http://rdoc.info/github/collectiveidea/audited
203
204 Or join the [mailing list](http://groups.google.com/group/audited) to get help or offer suggestions.
1b63fb3 @laserlemon Start writing new README
laserlemon authored
205
26dfd71 @laserlemon Finish writing the README
laserlemon authored
206 ## Contributing
1b63fb3 @laserlemon Start writing new README
laserlemon authored
207
26dfd71 @laserlemon Finish writing the README
laserlemon authored
208 In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), **everyone** is encouraged to help improve this project. Here are a few ways _you_ can pitch in:
1b63fb3 @laserlemon Start writing new README
laserlemon authored
209
26dfd71 @laserlemon Finish writing the README
laserlemon authored
210 * Use prerelease versions of Audited.
211 * [Report bugs](https://github.com/collectiveidea/audited/issues).
212 * Fix bugs and submit [pull requests](http://github.com/collectiveidea/audited/pulls).
213 * Write, clarify or fix documentation.
214 * Refactor code.
Something went wrong with that request. Please try again.