Skip to content

Ruby gem to provide basic, predictable auditing for ActiveRecords

License

Notifications You must be signed in to change notification settings

cavis/blamestamp

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

23 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Blamestamp

Blamestamp is intended as an easy way to record the creating and latest-editing user for an Active Record. It works similarly to the built-in Active Record timestamps module, but in a more configurable and predictable manner. Column names are configurable, as are default values, in case you allow non logged-in users to edit some things. Additionally, it allows configuration of when editing a record will update the blamestamps on a related record.

Requirements

Ruby and Rails

Requires Ruby version >= 1.9.2 and Rails version >= 3.0

Current version limitations

Currently only works with a combination of Devise, ActiveRecord and ActiveController.

Installation

Blamestamp should be installed as a gem in your app.

Include the gem in your Gemfile:

gem "blamestamp"

Or, if you like to live on the bleeding-edge:

gem "blamestamp", :git => "https://github.com/cavis/blamestamp"

Getting Started

In your migrations:

class CreateFoos < ActiveRecord::Migration
  def change
    create_table :foos do |t|
      t.string :bar
      t.blamestamps
    end
  end
end

Or, if modifying an existing model:

class AddBlamestampsToFoos < ActiveRecord::Migration
  def up
    change_table :foos do |t|
      t.blamestamps
    end
  end
  def down
    drop_blamestamps :foos
  end
end

In your model:

class Foo < ActiveRecord::Base
  blameable
end

Usage

By default, blamestamps adds 4 columns to your models:

  • blame_cre_at
  • blame_upd_at
  • blame_cre_by
  • blame_upd_by

When a record is created, blame_cre_at and blame_cre_by will be set. If no remote-user is logged in (via a controller), blame_cre_by will be nil. On initial creation, both blame_upd_at and blame_upd_by will be nil.

When a record is updated for the first time (and every time after), blame_upd_at and blame_upd_by are modified. Again, blame_upd_by will remain nil if there is no remote-user.

Additionally, blameable adds 2 relations to your models:

  • blame_cre_user
  • blame_upd_user

These are standard belongs_to associations, and will be nil unless the _at column is populated.

Overriding Stamps

If you want, you can manually set the blamestamps instead of letting the remote user set them. For example:

user1 = User.new
foo1 = Foo.new
foo1.blame_cre_user = user1
foo1.save!
#whatever the remote user may have been, blame_cre_by is now user1.id

Advanced Options

If that's not enough for you, there are several advanced config options available.

In your migrations:

If you don't like the blame prefix on the columns, you can change it. In this example it will create columns blah_cre_at, blah_upd_at, blah_cre_by, and blah_upd_by.

t.blamestamps :prefix => :blah

In your model:

If you changed the prefix of the columns in your migration, you should let the model know about that too:

blameable :prefix => :blah

Or, if you picked something completely off-the-wall in your migration, you can specify each of the 4 columns individually:

blameable :cre_at => :made_at, :upd_at => :changed_at, :cre_by => :invented_by, :upd_by => :hacked_by

And if you don't like the default association names, you can define those too:

blameable :cre_user => :inventor, :upd_user => :hacker

If you're concerned about data validation, you can make sure errors are raised if a record is ever saved with a blank blame_cre_by:

blameable :required => true

Finally, you can cascade modifications from a blameable model to one of its associations. Whenever a record of the blameable class is inserted, updated, or deleted, the upd_at/upd_by columns on the associated record will be updated. For example:

class Foo < ActiveRecord::Base
  belongs_to :bar
  belongs_to :project
  blameable :cascade => [:project, :bar]
end

Or, just specify a single cascade:

class Foo < ActiveRecord::Base
  belongs_to :bar
  belongs_to :project
  blameable :cascade => :bar
end

Issues and Contributing

Please, let me know about any bugs/feature-requests via the issues tracker. And if you'd like to contribute, send me a note! Thanks.

License

Blamestamp is free software, and may be redistributed under the MIT-LICENSE.

About

Ruby gem to provide basic, predictable auditing for ActiveRecords

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published