kewinwang / acts_as_audited

acts_as_audited is an ActiveRecord extension that logs all changes to your models in an audits table.

acts_as_audited¶ ↑

acts_as_audited is an ActiveRecord extension that logs all changes to your models in an audits table, with optional revision comments. acts_as_audited has been updated to work with Rails 3, to use it with older version of Rails, please see the 1.1-stable branch.

Installation¶ ↑

In Gemfile:

gem "acts_as_audited", "2.0.0.rc7"

In your application root, run:

$ bundle install

Generate the migration:

• If installing without a previous version of acts_as_audited or you do not mind overwriting your audits table:

  $ rails g acts_as_audited:install

• If upgrading from a previous version of acts_as_audited you might need some alterations to the audits table:

  $ rails g acts_as_audited:upgrade

• After running one of the generators:

  $ rake db:migrate

Rails deprecation warning¶ ↑

Currently the gem causes the following deprecation warning to be emitted:

DEPRECATION WARNING: reorder is deprecated. Please use except(:order).order(...) instead. (called from <class:Audit> at /Users/kenneth/Code/FOSS/acts_as_audited/lib/acts_as_audited/audit.rb:26)

I’m well aware of the fact, and working towards a solution. The issue has also been brought up on the Rails lighthouse as #6011. I’m keeping an eye on the issue and working towards another possible solution.

Upgrading¶ ↑

Upgrading to Rails 3, or even between point releases of acts_as_audited, might require alterations to the audits table. After every upgrade please run the following generator:

$ rails g acts_as_audited:upgrade

The upgrade generator will only generate migrations that are missing, or no migrations at all if you are up to date.

Usage¶ ↑

Declare acts_as_audited on your models:

class User < ActiveRecord::Base
  acts_as_audited :except => [:password, :mistress]
end

Within a web request, will automatically record the user that made the change if your controller has a current_user method. Comments can be added to an audit by setting model.audit_comments before create/update/destroy. If the :comment_required option is given to acts_as_audited, the save/update/destroy action will fail with add an error on model.audit_comment and triggering a transaction rollback if model.audit_comment is nil.

To record an audit for an associated model, use the :associated_with option.

class User < ActiveRecord::Base
  acts_as_audited :associated_with => :company
end

If desired, the associated model can access its audits using has_associated_audits.

class Company < ActiveRecord::Base
  has_many :users
  has_associated_audits
end

To record a user in the audits outside of a web request, you can use as_user:

Audit.as_user(user) do
  # Perform changes on audited models
end

Caveats¶ ↑

If your model declares attr_accessible after acts_as_audited, you need to set :protect to false. acts_as_audited uses attr_protected internally to prevent malicious users from unassociating your audits, and Rails does not allow both attr_protected and attr_accessible. It will default to false if attr_accessible is called before acts_as_audited, but needs to be explicitly set if it is called after.

class User < ActiveRecord::Base
  acts_as_audited :protect => false
  attr_accessible :name
end

Another caveat is documented in issue 26, where an audit created on the first request to the server does not have a user. Please review the Github issue for more details on how to fix this. It does not appear to affect Rails 3.

Compatability¶ ↑

acts_as_audited works with Rails 3.0.3. For older versions of Rails, please see the 1.1-stable branch.

Getting Help¶ ↑

Review the documentation at rdoc.info/github/collectiveidea/acts_as_audited

Join the mailing list for getting help or offering suggestions - groups.google.com/group/acts_as_audited

Branches¶ ↑

The master branch is considered stable, and you should be able to use it at any time. The development branch will contain all active development and might be a moving target from time to time.

Contributing¶ ↑

Contributions are always welcome. Checkout the latest code on GitHub - github.com/collectiveidea/acts_as_audited

When contributing a bug-fix, please use a topic branch created off our master branch. When developing a new feature, please create a topic branch of our development branch (and rebase before submiting a pull request).

Please include tests with your patches. There are a few gems required to run the tests:

$ bundle install

Make sure the tests pass against the version of Rails specified in the Gemfile

$ rake spec test

Please report bugs or feature suggestions on GitHub - github.com/collectiveidea/acts_as_audited/issues