acts_as_audited_customized 1.2.1

data/CHANGELOG

@@ -0,0 +1,26 @@
+ acts_as_audited ChangeLog
+-------------------------------------------------------------------------------
+* 2010-12-21 - Allowed customization of the model used to represent a human. [Pat George]
+* 2009-01-27 - Store old and new values for updates, and store all attributes on destroy.
+               Refactored revisioning methods to work as expected
+* 2008-10-10 - changed to make it work in development mode
+* 2008-04-19 - refactored to make compatible with dirty tracking in edge rails
+               and to stop storing both old and new values in a single audit
+* 2008-04-18 - Fix NoMethodError when trying to access the :previous revision
+               on a model that doesn't have previous revisions [Alex Soto]
+* 2008-03-21 - added #changed_attributes to get access to the changes before a
+               save [Chris Parker]
+* 2007-12-16 - Added #revision_at for retrieving a revision from a specific
+               time [Jacob Atzen]
+* 2007-12-16 - Fix error when getting revision from audit with no changes
+               [Geoffrey Wiseman]
+* 2007-12-16 - Remove dependency on acts_as_list
+* 2007-06-17 - Added support getting previous revisions
+* 2006-11-17 - Replaced use of singleton User.current_user with cache sweeper
+               implementation for auditing the user that made the change
+* 2006-11-17 - added migration generator
+* 2006-08-14 - incorporated changes from Michael Schuerig to write_attribute
+               that saves the new value after every change and not just the
+               first, and performs proper type-casting before doing comparisons
+* 2006-08-14 - The "changes" are now saved as a serialized hash
+* 2006-07-21 - initial version

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright © 2008 Brandon Keepers - Collective Idea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,70 @@
+= acts_as_audited
+
+acts_as_audited is an ActiveRecord extension that logs all changes to your models in an audits table.
+
+The purpose of this fork is to store both the previous values and the changed value, making each audit record selfcontained.
+
+== Installation
+
+* acts_as_audited can be installed as a gem:
+    
+    # config/environment.rb
+    config.gem 'acts_as_audited', :lib => false, :source => 'http://gemcutter.org'
+
+  or a plugin:
+
+    script/plugin install git://github.com/collectiveidea/acts_as_audited.git
+
+* Generate the migration
+    script/generate audited_migration add_audits_table
+    rake db:migrate
+
+== Usage
+
+Declare <tt>acts_as_audited</tt> 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 <tt>current_user</tt> method.
+
+To record a user in the audits outside of a web request, you can use <tt>as_user</tt>:
+
+    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
+
+== Compatability
+
+acts_as_audited works with Rails 2.1 or later.
+
+== Getting Help
+
+Join the mailing list for getting help or offering suggestions:
+  http://groups.google.com/group/acts_as_audited
+
+== Contributing
+
+Contributions are always welcome. Checkout the latest code on GitHub:
+  http://github.com/collectiveidea/acts_as_audited
+
+Please include tests with your patches. There are a few gems required to run the tests:
+  $ gem install multi_rails
+  $ gem install thoughtbot-shoulda jnunemaker-matchy --source http://gems.github.com
+
+Make sure the tests pass against all versions of Rails since 2.1:
+
+  $ rake test:multi_rails:all
+
+Please report bugs or feature suggestions on GitHub:
+  http://github.com/collectiveidea/acts_as_audited/issues

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rake'
+require 'load_multi_rails_rake_tasks'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run tests.'
+task :default => :test
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "acts_as_audited_customized"
+    gem.summary = %Q{ActiveRecord extension that logs all changes to your models in an audits table additionally allowing you to specify which human model to use (if not 'User')}
+    gem.email = "pat.george@gmail.com"
+    gem.homepage = "http://github.com/pcg79/acts_as_audited"
+    gem.authors = ["Brandon Keepers", "Pat George"]
+    gem.add_dependency 'activerecord', '>=2.1'
+    gem.add_development_dependency "thoughtbot-shoulda"
+    gem.add_development_dependency "jnunemaker-matchy"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  # Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+desc 'Test the acts_as_audited plugin'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+task :test => :check_dependencies
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+    test.rcov_opts = %w(--exclude test,/usr/lib/ruby,/Library/Ruby,$HOME/.gem --sort coverage)
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+desc 'Generate documentation for the acts_as_audited plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = 'acts_as_audited'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.2.1

data/generators/audit_model/USAGE

@@ -0,0 +1,9 @@
+Description:
+	The audit model generator creates the Audit model in app/models/ associating it with the correct "human" class ("user" by default).
+
+Example:
+    ./script/generate audit_model Person
+
+    This will create the Audit model in app/models/ associating it to the Person model.
+
+    You must generate the migration using the same "human" class.

data/generators/audit_model/audit_model_generator.rb

@@ -0,0 +1,21 @@
+class AuditModelGenerator < Rails::Generator::NamedBase
+  def initialize(runtime_args, runtime_options = {})
+    runtime_args << 'user' if runtime_args.empty?
+    super
+    @human_model = runtime_args[0] ? runtime_args[0].underscore : 'user'
+  end
+
+  def manifest
+    # puts "*** [AuditModelGenerator.manifest] - File.join(File.dirname(__FILE__), '..', '..', 'lib', 'acts_as_audited') = #{File.join(File.dirname(__FILE__), '..', '..', 'lib', 'acts_as_audited')}"
+    record do |m|
+      m.directory(File.join('app', 'models'))
+      m.template('model.rb', "app/models/audit.rb", :assigns => { :human_model => @human_model })
+    end
+  end
+
+  protected
+
+  def banner
+    "Usage: #{$0} audit_model [human_model_name]"
+  end
+end

data/generators/audit_model/templates/model.rb

@@ -0,0 +1,119 @@
+require 'set'
+
+# Audit saves the changes to ActiveRecord models.  It has the following attributes:
+#
+# * <tt>auditable</tt>: the ActiveRecord model that was changed
+# * <tt><%= human_model %></tt>: the <%= human_model %> that performed the change; a string or an ActiveRecord model
+# * <tt>action</tt>: one of create, update, or delete
+# * <tt>changes</tt>: a serialized hash of all the changes
+# * <tt>created_at</tt>: Time that the change was performed
+#
+class Audit < ActiveRecord::Base
+  belongs_to :auditable, :polymorphic => true
+  belongs_to :<%= human_model %>, :polymorphic => true
+
+  before_create :set_version_number, :set_audit_<%= human_model %>
+
+  serialize :changes
+
+  cattr_accessor :audited_class_names
+  self.audited_class_names = Set.new
+
+  def self.audited_classes
+    self.audited_class_names.map(&:constantize)
+  end
+
+  # All audits made during the block called will be recorded as made
+  # by +<%= human_model %>+. This method is hopefully threadsafe, making it ideal
+  # for background operations that require audit information.
+  def self.as_<%= human_model %>(<%= human_model %>, &block)
+    Thread.current[:acts_as_audited_<%= human_model %>] = <%= human_model %>
+
+    yield
+
+    Thread.current[:acts_as_audited_<%= human_model %>] = nil
+  end
+
+  # Allows <%= human_model %> to be set to either a string or an ActiveRecord object
+  def <%= human_model %>_as_string=(<%= human_model %>) #:nodoc:
+    # reset both either way
+    self.<%= human_model %>_as_model = self.username = nil
+    <%= human_model %>.is_a?(ActiveRecord::Base) ?
+      self.<%= human_model %>_as_model = <%= human_model %> :
+      self.username = <%= human_model %>
+  end
+  alias_method :<%= human_model %>_as_model=, :<%= human_model %>=
+  alias_method :<%= human_model %>=, :<%= human_model %>_as_string=
+
+  def <%= human_model %>_as_string #:nodoc:
+    self.<%= human_model %>_as_model || self.username
+  end
+  alias_method :<%= human_model %>_as_model, :<%= human_model %>
+  alias_method :<%= human_model %>, :<%= human_model %>_as_string
+
+  def revision
+    clazz = auditable_type.constantize
+    returning clazz.find_by_id(auditable_id) || clazz.new do |m|
+      Audit.assign_revision_attributes(m, self.class.reconstruct_attributes(ancestors).merge({:version => version}))
+    end
+  end
+
+  def ancestors
+    self.class.find(:all, :order => 'version',
+      :conditions => ['auditable_id = ? and auditable_type = ? and version <= ?',
+      auditable_id, auditable_type, version])
+  end
+
+  # Returns a hash of the changed attributes with the new values
+  def new_attributes
+    (changes || {}).inject({}.with_indifferent_access) do |attrs,(attr,values)|
+      attrs[attr] = Array(values).last
+      attrs
+    end
+  end
+
+  # Returns a hash of the changed attributes with the old values
+  def old_attributes
+    (changes || {}).inject({}.with_indifferent_access) do |attrs,(attr,values)|
+      attrs[attr] = Array(values).first
+      attrs
+    end
+  end
+
+  def self.reconstruct_attributes(audits)
+    attributes = {}
+    result = audits.collect do |audit|
+      attributes.merge!(audit.new_attributes).merge!(:version => audit.version)
+      yield attributes if block_given?
+    end
+    block_given? ? result : attributes
+  end
+
+  def self.assign_revision_attributes(record, attributes)
+    attributes.each do |attr, val|
+      if record.respond_to?("#{attr}=")
+        record.attributes.has_key?(attr.to_s) ?
+          record[attr] = val :
+          record.send("#{attr}=", val)
+      end
+    end
+    record
+  end
+
+private
+
+  def set_version_number
+    max = self.class.maximum(:version,
+      :conditions => {
+        :auditable_id => auditable_id,
+        :auditable_type => auditable_type
+      }) || 0
+    self.version = max + 1
+  end
+
+  def set_audit_<%= human_model %>
+    self.<%= human_model %> = Thread.current[:acts_as_audited_<%= human_model %>] if Thread.current[:acts_as_audited_<%= human_model %>]
+    nil # prevent stopping callback chains
+  end
+
+end

data/generators/audited_migration/USAGE

@@ -0,0 +1,7 @@
+Description:
+	The audited migration generator creates a migration to add the audits table.
+
+Example:
+    ./script/generate audited_migration add_audits_table
+
+    This will create a migration in db/migrate/.  Run "rake db:migrate" to update your database.

data/generators/audited_migration/audited_migration_generator.rb

@@ -0,0 +1,19 @@
+class AuditedMigrationGenerator < Rails::Generator::NamedBase
+  def initialize(runtime_args, runtime_options = {})
+    super
+    @human_model = runtime_args[1] ? runtime_args[1].underscore : 'user'
+  end
+
+  def manifest
+    record do |m|
+      m.directory(File.join('db', 'migrate'))
+      m.migration_template 'migration.rb', 'db/migrate', :assigns => { :human_model => @human_model }
+    end
+  end
+
+  protected
+
+  def banner
+    "Usage: #{$0} audited_migration add_audits_table [human_model_name]"
+  end
+end

data/generators/audited_migration/templates/migration.rb

@@ -0,0 +1,23 @@
+class <%= class_name %> < ActiveRecord::Migration
+  def self.up
+    create_table :audits, :force => true do |t|
+      t.column :auditable_id, :integer
+      t.column :auditable_type, :string
+      t.column :<%= human_model %>_id, :integer
+      t.column :<%= human_model %>_type, :string
+      t.column :username, :string
+      t.column :action, :string
+      t.column :changes, :text
+      t.column :version, :integer, :default => 0
+      t.column :created_at, :datetime
+    end
+
+    add_index :audits, [:auditable_id, :auditable_type], :name => 'auditable_index'
+    add_index :audits, [:<%= human_model %>_id, :<%= human_model %>_type], :name => '<%= human_model %>_index'
+    add_index :audits, :created_at
+  end
+
+  def self.down
+    drop_table :audits
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), 'rails', 'init')

data/lib/acts_as_audited.rb

@@ -0,0 +1,258 @@
+# Copyright (c) 2006 Brandon Keepers
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+module CollectiveIdea #:nodoc:
+  module Acts #:nodoc:
+    # Specify this act if you want changes to your model to be saved in an
+    # audit table.  This assumes there is an audits table ready.
+    #
+    #   class User < ActiveRecord::Base
+    #     acts_as_audited
+    #   end
+    #
+    # See <tt>CollectiveIdea::Acts::Audited::ClassMethods#acts_as_audited</tt>
+    # for configuration options
+    module Audited #:nodoc:
+      CALLBACKS = [:audit_create, :audit_update, :audit_destroy]
+
+      # The name of the model used to represent a human.  Default: :user
+      mattr_accessor :human_model
+      @@human_model = :user
+
+      class << self
+        # Call this method to modify defaults in your initializers.
+        #
+        # @example
+        #   Audited.configure do |config|
+        #     config.human_model = :person
+        #   end
+        def configure
+          yield self
+        end
+
+        def included(base) # :nodoc:
+          base.extend ClassMethods
+        end
+      end
+
+      module ClassMethods
+        # == Configuration options
+        #
+        #
+        # * +only+ - Only audit the given attributes
+        # * +except+ - Excludes fields from being saved in the audit log.
+        #   By default, acts_as_audited will audit all but these fields:
+        #
+        #     [self.primary_key, inheritance_column, 'lock_version', 'created_at', 'updated_at']
+        #   You can add to those by passing one or an array of fields to skip.
+        #
+        #     class User < ActiveRecord::Base
+        #       acts_as_audited :except => :password
+        #     end
+        # * +protect+ - If your model uses +attr_protected+, set this to false to prevent Rails from
+        #   raising an error.  If you declare +attr_accessibe+ before calling +acts_as_audited+, it
+        #   will automatically default to false.  You only need to explicitly set this if you are
+        #   calling +attr_accessible+ after.
+        #
+        #     class User < ActiveRecord::Base
+        #       acts_as_audited :protect => false
+        #       attr_accessible :name
+        #     end
+        #
+        def acts_as_audited(options = {})
+          # don't allow multiple calls
+          return if self.included_modules.include?(CollectiveIdea::Acts::Audited::InstanceMethods)
+
+          options = {:protect => accessible_attributes.nil?}.merge(options)
+
+          class_inheritable_reader :non_audited_columns
+          class_inheritable_reader :auditing_enabled
+
+          if options[:only]
+            except = self.column_names - options[:only].flatten.map(&:to_s)
+          else
+            except = [self.primary_key, inheritance_column, 'lock_version',
+              'created_at', 'updated_at', 'created_on', 'updated_on']
+            except |= Array(options[:except]).collect(&:to_s) if options[:except]
+          end
+          write_inheritable_attribute :non_audited_columns, except
+
+          has_many :audits, :as => :auditable, :order => "#{Audit.quoted_table_name}.version"
+          attr_protected :audit_ids if options[:protect]
+          Audit.audited_class_names << self.to_s
+
+          after_create  :audit_create if !options[:on] || (options[:on] && options[:on].include?(:create))
+          before_update :audit_update if !options[:on] || (options[:on] && options[:on].include?(:update))
+          after_destroy :audit_destroy if !options[:on] || (options[:on] && options[:on].include?(:destroy))
+
+          attr_accessor :version
+
+          extend CollectiveIdea::Acts::Audited::SingletonMethods
+          include CollectiveIdea::Acts::Audited::InstanceMethods
+
+          write_inheritable_attribute :auditing_enabled, true
+        end
+      end
+
+      module InstanceMethods
+
+        # Temporarily turns off auditing while saving.
+        def save_without_auditing
+          without_auditing { save }
+        end
+
+        # Executes the block with the auditing callbacks disabled.
+        #
+        #   @foo.without_auditing do
+        #     @foo.save
+        #   end
+        #
+        def without_auditing(&block)
+          self.class.without_auditing(&block)
+        end
+
+        # Gets an array of the revisions available
+        #
+        #   user.revisions.each do |revision|
+        #     user.name
+        #     user.version
+        #   end
+        #
+        def revisions(from_version = 1)
+          audits = self.audits.find(:all, :conditions => ['version >= ?', from_version])
+          return [] if audits.empty?
+          revision = self.audits.find_by_version(from_version).revision
+          Audit.reconstruct_attributes(audits) {|attrs| revision.revision_with(attrs) }
+        end
+
+        # Get a specific revision specified by the version number, or +:previous+
+        def revision(version)
+          revision_with Audit.reconstruct_attributes(audits_to(version))
+        end
+
+        def revision_at(date_or_time)
+          audits = self.audits.find(:all, :conditions => ["created_at <= ?", date_or_time])
+          revision_with Audit.reconstruct_attributes(audits) unless audits.empty?
+        end
+
+        def audited_attributes
+          attributes.except(*non_audited_columns)
+        end
+
+      protected
+
+        def revision_with(attributes)
+          returning self.dup do |revision|
+            revision.send :instance_variable_set, '@attributes', self.attributes_before_type_cast
+            Audit.assign_revision_attributes(revision, attributes)
+
+            # Remove any association proxies so that they will be recreated
+            # and reference the correct object for this revision. The only way
+            # to determine if an instance variable is a proxy object is to
+            # see if it responds to certain methods, as it forwards almost
+            # everything to its target.
+            for ivar in revision.instance_variables
+              proxy = revision.instance_variable_get ivar
+              if !proxy.nil? and proxy.respond_to? :proxy_respond_to?
+                revision.instance_variable_set ivar, nil
+              end
+            end
+          end
+        end
+
+      private
+
+        def audited_changes
+          changed_attributes.except(*non_audited_columns).inject({}) do |changes,(attr, old_value)|
+            changes[attr] = [old_value, self[attr]]
+            changes
+          end
+        end
+
+        def audits_to(version = nil)
+          if version == :previous
+            version = if self.version
+              self.version - 1
+            else
+              previous = audits.find(:first, :offset => 1,
+                :order => "#{Audit.quoted_table_name}.version DESC")
+              previous ? previous.version : 1
+            end
+          end
+          audits.find(:all, :conditions => ['version <= ?', version])
+        end
+
+        def audit_create
+          write_audit(:action => 'create', :changes => audited_attributes)
+        end
+
+        def audit_update
+          unless (changes = audited_changes).empty?
+            write_audit(:action => 'update', :changes => changes)
+          end
+        end
+
+        def audit_destroy
+          write_audit(:action => 'destroy', :changes => audited_attributes)
+        end
+
+        def write_audit(attrs)
+          self.audits.create attrs if auditing_enabled
+        end
+      end # InstanceMethods
+
+      module SingletonMethods
+        # Returns an array of columns that are audited.  See non_audited_columns
+        def audited_columns
+          self.columns.select { |c| !non_audited_columns.include?(c.name) }
+        end
+
+        # Executes the block with auditing disabled.
+        #
+        #   Foo.without_auditing do
+        #     @foo.save
+        #   end
+        #
+        def without_auditing(&block)
+          auditing_was_enabled = auditing_enabled
+          disable_auditing
+          returning(block.call) { enable_auditing if auditing_was_enabled }
+        end
+
+        def disable_auditing
+          write_inheritable_attribute :auditing_enabled, false
+        end
+
+        def enable_auditing
+          write_inheritable_attribute :auditing_enabled, true
+        end
+
+        # All audit operations during the block are recorded as being
+        # made by +user+. This is not model specific, the method is a
+        # convenience wrapper around #Audit.as_user.
+        def audit_as( user, &block )
+          Audit.as_user( user, &block )
+        end
+
+      end
+    end
+  end
+end