README.md

PaperTrail

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.

Features

Allows you to specify attributes (by inclusion or exclusion) which must change for a Version to be stored.

Allows you to get at every version, including the original, even once destroyed.

Allows you to get at every version even if the schema has since changed.

Allows you to get at the version as of a particular time.

Option to automatically restore has_one associations as they were at the time.

Automatically records who was responsible via your controller. PaperTrail calls current_user by default, if it exists, but you can have it call any method you like.

Allows you to set who is responsible at model-level (useful for migrations).

Allows you to store arbitrary model-level metadata with each version (useful for filtering versions).

Allows you to store arbitrary controller-level information with each version, e.g. remote IP.

Can be turned off/on per class (useful for migrations).

Can be turned off/on per request (useful for testing with an external service).

Can be turned off/on globally (useful for testing).

No configuration necessary.

Stores everything in a single database table by default (generates migration for you), or can use separate tables for separate models.

Supports custom version classes so different models' versions can have different behaviour.

Thoroughly tested.

Threadsafe.

Rails Version

Works on Rails 3 and Rails 2.3. The Rails 3 code is on the master branch and tagged v2.x. The Rails 2.3 code is on the rails2 branch and tagged v1.x. Please note I'm not adding new features to the Rails 2.3 codebase.

API Summary

When you declare has_paper_trail in your model, you get these methods:

class Widget < ActiveRecord::Base
has_paper_trail # you can pass various options here
end
# Returns this widget's versions.
widget.versions
# Return the version this widget was reified from, or nil if it is live.
widget.version
# Returns true if this widget is the current, live one; or false if it is from a previous version.
widget.live?
# Returns who put the widget into its current state.
widget.originator
# Returns the widget (not a version) as it looked at the given timestamp.
widget.version_at(timestamp)
# Returns the widget (not a version) as it was most recently.
widget.previous_version
# Returns the widget (not a version) as it became next.
widget.next_version
# Turn PaperTrail off for all widgets.
Widget.paper_trail_off
# Turn PaperTrail on for all widgets.
Widget.paper_trail_on

And a Version instance has these methods:

# Returns the item restored from this version.
version.reify(options = {})
# Returns who put the item into the state stored in this version.
version.originator
# Returns who changed the item from the state it had in this version.
version.terminator
version.whodunnit
# Returns the next version.
version.next
# Returns the previous version.
version.previous
# Returns the index of this version in all the versions.
version.index
# Returns the event that caused this version (create|update|destroy).
version.event

In your controllers you can override these methods:

# Returns the user who is responsible for any changes that occur.
# Defaults to current_user.
user_for_paper_trail
# Returns any information about the controller or request that you want
# PaperTrail to store alongside any changes that occur.
info_for_paper_trail

Basic Usage

PaperTrail is simple to use. Just add 15 characters to a model to get a paper trail of every create, update, and destroy.

class Widget < ActiveRecord::Base
has_paper_trail
end

This gives you a versions method which returns the paper trail of changes to your model.

>> v = widget.versions.last
>> v.event # 'update' (or 'create' or 'destroy')
>> v.whodunnit # '153' (if the update was via a controller and
# the controller has a current_user method,
# here returning the id of the current user)
>> v.created_at # when the update occurred
>> widget = v.reify # the widget as it was before the update;
# would be nil for a create event

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.

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.

Here's a helpful table showing what PaperTrail stores:

Event

Model Before

Model After

create

nil

widget

update

widget

widget'

destroy

widget

nil

PaperTrail stores the values in the Model Before column. Most other auditing/versioning plugins store the After column.

Choosing Attributes To Monitor

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:

Finding Out Who Was Responsible For A Change

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:

N.B. A version's whodunnit records who changed the object causing the version to be stored. Because a version stores the object as it looked before the change (see the table above), whodunnit returns who stopped the object looking like this -- not who made it look like this. Hence whodunnit is aliased as terminator.

To find out who made a version's object look that way, use version.originator. And to find out who made a "live" object look like it does, use originator on the object.

The implementation is complicated by the edge case where the parent and child are updated in one go, e.g. in one web request or database transaction. PaperTrail doesn't know about different models being updated "together", so you can't ask it definitively to get the child as it was before the joint parent-and-child update.

The correct solution is to make PaperTrail aware of requests or transactions (c.f. Efficiency's transaction ID middleware). In the meantime we work around the problem by finding the child as it was a few seconds before the parent was updated. By default we go 3 seconds before but you can change this by passing the desired number of seconds to the :has_one option:

If you are shuddering, take solace from knowing PaperTrail opts out of these shenanigans by default. This means your :has_one associated objects will be the live ones, not the ones the user saw at the time. Since PaperTrail doesn't auto-restore :has_many associations (I can't get it to work) or :belongs_to (I ran out of time looking at :has_many), this at least makes your associations wrong consistently ;)

Has-Many-Through Associations

PaperTrail can track most changes to the join table. Specifically it can track all additions but it can only track removals which fire the after_destroy callback on the join table. Here are some examples:

Having said that, you can apparently get all these working (I haven't tested it myself) with this monkey patch:

# In config/initializers/core_extensions.rb or lib/core_extensions.rb
ActiveRecord::Associations::HasManyThroughAssociation.class_eval do
def delete_records(records)
klass = @reflection.through_reflection.klass
records.each do |associate|
klass.destroy_all(construct_join_attributes(associate))
end
end
end

The difference is the call to destroy_all instead of delete_all in the original.

There may be a way to store authorship versions, probably using association callbacks, no matter how the collection is manipulated but I haven't found it yet. Let me know if you do.

Storing metadata

You can store arbitrary model-level metadata alongside each version like this:

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.)

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:

Version.all(:conditions => ['author_id = ?', author_id])

Note you can pass a symbol as a value in the meta hash to signal a method to call.

You can also store any information you like from your controller. Just override the info_for_paper_trail method in your controller to return a hash whose keys correspond to columns in your versions table. E.g.:

Diffing Versions

There are two scenarios: diffing adjacent versions and diffing non-adjacent versions.

The best way to diff adjacent versions is to get PaperTrail to do it for you. If you add an object_changes text column to your versions table, either at installation time with the --with-changes option or manually, PaperTrail will store the changes diff in each update version. You can use the version.changeset method to retrieve it. For example:

Note PaperTrail only stores the changes for updates; there's no point storing them for created or destroyed objects.

Please be aware that PaperTrail doesn't use diffs internally. When I designed PaperTrail I wanted simplicity and robustness so I decided to make each version of an object self-contained. A version stores all of its object's data, not a diff from the previous version. This means you can delete any version without affecting any other.

To diff non-adjacent versions you'll have to write your own code. These libraries may help:

For diffing two strings:

htmldiff: expects but doesn't require HTML input and produces HTML output. Works very well but slows down significantly on large (e.g. 5,000 word) inputs.

differ: expects plain text input and produces plain text/coloured/HTML/any output. Can do character-wise, word-wise, line-wise, or arbitrary-boundary-string-wise diffs. Works very well on non-HTML input.

activerecord-diff: rather like ActiveRecord::Dirty but also allows you to specify which columns to compare.

Turning PaperTrail Off/On

Sometimes you don't want to store changes. Perhaps you are only interested in changes made by your users and don't need to store changes you make yourself in, say, a migration -- or when testing your application.

You can turn PaperTrail on or off in three ways: globally, per request, or per class.

Globally

On a global level you can turn PaperTrail off like this:

>> PaperTrail.enabled = false

For example, you might want to disable PaperTrail in your Rails application's test environment to speed up your tests. This will do it:

# in config/environments/test.rb
config.after_initialize do
PaperTrail.enabled = false
end

If you disable PaperTrail in your test environment but want to enable it for specific tests, you can add a helper like this to your test helper:

Per class

If you are about change some widgets and you don't want a paper trail of your changes, you can turn PaperTrail off like this:

>> Widget.paper_trail_off

And on again like this:

>> Widget.paper_trail_on

Deleting Old Versions

Over time your versions table will grow to an unwieldy size. Because each version is self-contained (see the Diffing section above for more) you can simply delete any records you don't want any more. For example: