Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 226 lines (142 sloc) 8.344 kb
e9a8648 @airblade First commit.
airblade authored
1 # PaperTrail
2
9327083 @airblade Added info on reverting and undeleting.
airblade authored
3 PaperTrail lets you track changes to your models' data. It's good for auditing or versioning. You can see how a model looked at any stage in its lifecycle, revert it to any version, and even undelete it after it's been destroyed.
e9a8648 @airblade First commit.
airblade authored
4
5
6 ## Features
7
8 * Stores every create, update and destroy.
55185cd @airblade Store user-defined metadata.
airblade authored
9 * Does not store updates which don't change anything.
10 * Does not store updates which only change attributes you are ignoring.
e9a8648 @airblade First commit.
airblade authored
11 * Allows you to get at every version, including the original, even once destroyed.
12 * Allows you to get at every version even if the schema has since changed.
13 * Automatically records who was responsible if your controller has a `current_user` method.
14 * Allows you to set who is responsible at model-level (useful for migrations).
55185cd @airblade Store user-defined metadata.
airblade authored
15 * Allows you to store arbitrary metadata with each version (useful for filtering versions).
e9a8648 @airblade First commit.
airblade authored
16 * Can be turned off/on (useful for migrations).
17 * No configuration necessary.
18 * Stores everything in a single database table (generates migration for you).
19 * Thoroughly tested.
20
21
22 ## Rails Version
23
24 Known to work on Rails 2.3. Probably works on Rails 2.2 and 2.1.
25
26
27 ## Basic Usage
28
4da196a @airblade Expanded README.
airblade authored
29 PaperTrail is simple to use. Just add 15 characters to a model to get a paper trail of every `create`, `update`, and `destroy`.
e9a8648 @airblade First commit.
airblade authored
30
31 class Widget < ActiveRecord::Base
32 has_paper_trail
33 end
34
35 This gives you a `versions` method which returns the paper trail of changes to your model.
36
37 >> widget = Widget.find 42
38 >> widget.versions # [<Version>, <Version>, ...]
39
40 Once you have a version, you can find out what happened:
41
42 >> v = widget.versions.last
43 >> v.event # 'update' (or 'create' or 'destroy')
44 >> v.whodunnit # '153' (if the update was via a controller and
45 # the controller has a current_user method,
46 # here returning the id of the current user)
47 >> v.created_at # when the update occurred
48 >> widget = v.reify # the widget as it was before the update;
49 # would be nil for a create event
50
4da196a @airblade Expanded README.
airblade authored
51 PaperTrail stores the pre-change version of the model, unlike some other auditing/versioning plugins, so you can retrieve the original version. This is useful when you start keeping a paper trail for models that already have records in the database.
e9a8648 @airblade First commit.
airblade authored
52
53 >> widget = Widget.find 153
54 >> widget.name # 'Doobly'
4da196a @airblade Expanded README.
airblade authored
55
56 # Add has_paper_trail to Widget model.
57
e9a8648 @airblade First commit.
airblade authored
58 >> widget.versions # []
59 >> widget.update_attributes :name => 'Wotsit'
60 >> widget.versions.first.reify.name # 'Doobly'
61 >> widget.versions.first.event # 'update'
62
4da196a @airblade Expanded README.
airblade authored
63 This also means that PaperTrail does not waste space storing a version of the object as it currently stands. The `versions` method gives you previous versions; to get the current one just call a finder on your `Widget` model as usual.
e9a8648 @airblade First commit.
airblade authored
64
65 Here's a helpful table showing what PaperTrail stores:
66
67 <table>
68 <tr>
69 <th>Event</th>
70 <th>Model Before</th>
71 <th>Model After</th>
72 </tr>
73 <tr>
74 <td>create</td>
75 <td>nil</td>
76 <td>widget</td>
77 </tr>
78 <tr>
79 <td>update</td>
80 <td>widget</td>
81 <td>widget'</td>
82 <tr>
83 <td>destroy</td>
84 <td>widget</td>
85 <td>nil</td>
86 </tr>
87 </table>
88
4da196a @airblade Expanded README.
airblade authored
89 PaperTrail stores the values in the Model Before column. Most other auditing/versioning plugins store the After column.
90
91
52981bf @airblade Optionally ignore attributes.
airblade authored
92 ## Ignoring changes to certain attributes
93
94 You can ignore changes to certain attributes like this:
95
96 class Article < ActiveRecord::Base
97 has_paper_trail :ignore => [:title, :rating]
98 end
99
100 This means that changes to just the `title` or `rating` will not store another version of the article. It does not mean that the `title` and `rating` attributes will be ignored if some other change causes a new `Version` to be crated. For example:
101
102 >> a = Article.create
103 >> a.versions.length # 1
104 >> a.update_attributes :title => 'My Title', :rating => 3
105 >> a.versions.length # 1
106 >> a.update_attributes :content => 'Hello'
107 >> a.versions.length # 2
108 >> a.versions.last.reify.title # 'My Title'
109
110
9327083 @airblade Added info on reverting and undeleting.
airblade authored
111 ## Reverting And Undeleting A Model
4da196a @airblade Expanded README.
airblade authored
112
9327083 @airblade Added info on reverting and undeleting.
airblade authored
113 PaperTrail makes reverting to a previous version easy:
4da196a @airblade Expanded README.
airblade authored
114
115 >> widget = Widget.find 42
9327083 @airblade Added info on reverting and undeleting.
airblade authored
116 >> widget.update_attributes :name => 'Blah blah'
4da196a @airblade Expanded README.
airblade authored
117 # Time passes....
9327083 @airblade Added info on reverting and undeleting.
airblade authored
118 >> widget = widget.versions.last.reify # the widget as it was before the update
119 >> widget.save # reverted
120
121 Undeleting is just as simple:
4da196a @airblade Expanded README.
airblade authored
122
9327083 @airblade Added info on reverting and undeleting.
airblade authored
123 >> widget = Widget.find 42
124 >> widget.destroy
125 # Time passes....
4da196a @airblade Expanded README.
airblade authored
126 >> widget = Version.find(153).reify # the widget as it was before it was destroyed
127 >> widget.save # the widget lives!
128
129 In fact you could use PaperTrail to implement an undo system, though I haven't had the opportunity yet to do it myself.
e9a8648 @airblade First commit.
airblade authored
130
131
132 ## Finding Out Who Was Responsible For A Change
133
4da196a @airblade Expanded README.
airblade authored
134 If your `ApplicationController` has a `current_user` method, PaperTrail will store the value it returns in the `version`'s `whodunnit` column. Note that this column is a string so you will have to convert it to an integer if it's an id and you want to look up the user later on:
e9a8648 @airblade First commit.
airblade authored
135
136 >> last_change = Widget.versions.last
137 >> user_who_made_the_change = User.find last_change.whodunnit.to_i
138
139 In a migration or in `script/console` you can set who is responsible like this:
140
141 >> PaperTrail.whodunnit = 'Andy Stewart'
142 >> widget.update_attributes :name => 'Wibble'
143 >> widget.versions.last.whodunnit # Andy Stewart
144
145
55185cd @airblade Store user-defined metadata.
airblade authored
146 ## Storing metadata
147
148 You can store arbitrary metadata alongside each version like this:
149
150 class Article < ActiveRecord::Base
151 belongs_to :author
152 has_paper_trail :meta => { :author_id => Proc.new { |article| article.author_id },
153 :answer => 42 }
154 end
155
156 PaperTrail will call your proc with the current article and store the result in the `author_id` column of the `versions` table. (Remember to add your metadata columns to the table.)
157
158 Why would you do this? In this example, `author_id` is an attribute of `Article` and PaperTrail will store it anyway in serialized (YAML) form in the `object` column of the `version` record. But let's say you wanted to pull out all versions for a particular author; without the metadata you would have to deserialize (reify) each `version` object to see if belonged to the author in question. Clearly this is inefficient. Using the metadata you can find just those versions you want:
159
160 Version.all(:conditions => ['author_id = ?', author_id])
161
162
e9a8648 @airblade First commit.
airblade authored
163 ## Turning PaperTrail Off/On
164
165 Sometimes you don't want to store changes. Perhaps you are only interested in changes made
166 by your users and don't need to store changes you make yourself in, say, a migration.
167
168 If you are about change some widgets and you don't want a paper trail of your changes, you can
169 turn PaperTrail off like this:
170
171 >> Widget.paper_trail_off
172
173 And on again like this:
174
175 >> Widget.paper_trail_on
176
177
178 ## Installation
179
e71252c @airblade Updated installation instructions (use Gemcutter).
airblade authored
180 1. Install PaperTrail either as a gem (from Gemcutter; the ones on GitHub are obsolete) or as a plugin:
e9a8648 @airblade First commit.
airblade authored
181
e71252c @airblade Updated installation instructions (use Gemcutter).
airblade authored
182 `config.gem 'paper_trail', :source => 'http://gemcutter.org'`
e9a8648 @airblade First commit.
airblade authored
183
edf40cd @airblade Fixed typo.
airblade authored
184 or:
185
0ec7261 @airblade Mark down code in numbered list.
airblade authored
186 `script/plugin install git://github.com/airblade/paper_trail.git`
e9a8648 @airblade First commit.
airblade authored
187
edf40cd @airblade Fixed typo.
airblade authored
188 2. Generate a migration which will add a `versions` table to your database.
e9a8648 @airblade First commit.
airblade authored
189
0ec7261 @airblade Mark down code in numbered list.
airblade authored
190 `script/generate paper_trail`
e9a8648 @airblade First commit.
airblade authored
191
192 3. Run the migration.
193
0ec7261 @airblade Mark down code in numbered list.
airblade authored
194 `rake db:migrate`
e9a8648 @airblade First commit.
airblade authored
195
196 4. Add `has_paper_trail` to the models you want to track.
197
198
53d1758 @airblade Note about the tests.
airblade authored
199 ## Testing
200
94c28e5 @airblade Updated section on tests and added Contributors to README.
airblade authored
201 PaperTrail has a thorough suite of tests. Thanks to [Zachery Hostens](http://github.com/zacheryph) for making them able to run standalone, i.e. without needing PaperTrail to be sitting in a Rails app.
53d1758 @airblade Note about the tests.
airblade authored
202
203
4da196a @airblade Expanded README.
airblade authored
204 ## Problems
205
206 Please use GitHub's [issue tracker](http://github.com/airblade/paper_trail/issues).
207
208
94c28e5 @airblade Updated section on tests and added Contributors to README.
airblade authored
209 ## Contributors
210
211 Many thanks to:
212
213 * [Zachery Hostens](http://github.com/zacheryph)
214
215
e9a8648 @airblade First commit.
airblade authored
216 ## Inspirations
217
218 * [Simply Versioned](http://github.com/github/simply_versioned)
219 * [Acts As Audited](http://github.com/collectiveidea/acts_as_audited)
220
221
222 ## Intellectual Property
223
224 Copyright (c) 2009 Andy Stewart (boss@airbladesoftware.com).
225 Released under the MIT licence.
Something went wrong with that request. Please try again.