acts_as_audited_collection 0.3

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Shaun Mangelsdorf
+
+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.md

@@ -0,0 +1,144 @@
+acts_as_audited_collection
+==========================
+
+acts_as_audited_collection is a Rails plugin, which extends ActiveRecord to allow auditing of associations.
+
+The basic feature set is:
+
+- Tracking addition of child records to an association
+- Tracking removal of child records
+- Tracking a child record being reassociated with a new parent, as a remove followed by an add
+- (Optionally) tracking any children which are modified
+- (Optionally) tracking when a grandchild is modified by cascading through associations
+
+License
+-------
+
+This plugin is released under the MIT license, and was contributed to the Rails community by the good people at [Software Projects](http://sp.com.au/).
+
+Installation
+============
+
+TBD
+
+Generating the migration
+------------------------
+
+    script/generate audited_collection_migration add_collection_audits_table
+    rake db:migrate
+
+Usage
+=====
+
+Declare an association that looks like:
+
+    class Employer < ActiveRecord::Base
+      has_many :people
+      acts_as_audited_collection_parent :for => :people
+    end
+
+    class Person < ActiveRecord::Base
+      belongs_to :employer
+      acts_as_audited_collection :parent => :employer
+    end
+
+When a record is created
+-------------------------
+
+    Person.create :name => 'Fred', :employer => nil   # No audit record
+
+    e = Employer.create :name => 'Foo Inc.'           # No audit record
+    Person.create :name => 'Mary', :employer => e     # Audit record is created
+
+    e.people_audits.last.action                       # 'add'
+    e.people_audits.last.parent_record                # Employer name: 'Foo Inc.'
+    e.people_audits.last.child_record                 # Person name: 'Mary'
+
+Tracking removal
+----------------
+
+    e.people.create :name => 'Bob'                    # Audit record is created
+
+    e.people.last.destroy                             # Audit record is created
+
+    e.people_audits.last.action                       # 'remove'
+    e.people_audits.last.parent_record                # Employer name: 'Foo Inc.'
+    e.people_audits.last.child_record                 # nil   (record was destroyed)
+    e.people_audits.last.child_record_id              # 3    (for example)
+    e.people_audits.last.child_record_type            # 'Person'
+
+Tracking reassociation
+----------------------
+
+    p = Person.first                                  # Person name: 'Fred'
+    p.update_attributes :employer => e                # Audit record is created
+
+    e.people_audits.last.action                       # 'add'
+
+    e2 = Employer.create :name => 'Bar Ltd.'          # No audit record
+    p.update_attributes :employer => e2               # Two audit records!
+
+    e.people_audits.last.action                       # 'remove'
+    e2.people_audits.last.action                      # 'add'
+
+    p.update_attributes :employer => e                # Changing it back for the sake of my own sanity.
+
+Tracking modification of unrelated attributes
+----------------------------------------------
+
+Consider the following alternative "Person" model.
+
+    class Person < ActiveRecord::Base
+      belongs_to :employer
+      acts_as_audited_collection :parent => :employer,
+          :track_modifications => true
+    end
+
+With this, we can now see modifications from the parent (though we make no attempt to ascertain what the modifications were - if you need this, see [acts_as_audited](http://github.com/collectiveidea/acts_as_audited))
+
+    p = Person.first                                  # Person name: 'Fred'
+    p.update_attributes :name => 'Freda'              # Audit record is created
+
+    e.people_audits.last.action                       # 'modify'
+    e.people_audits.last.child_record                 # Person name: 'Freda'
+
+Tracking deep changes to the model hierarchy
+--------------------------------------------
+
+Consider now that a Person might have any number of hobbies.
+
+    class Person < ActiveRecord::Base
+      belongs_to :employer
+      has_many :hobbies
+
+      acts_as_audited_collection :parent => :employer,
+          :track_modifications => true
+
+      acts_as_audited_collection_parent :for => :hobbies
+    end
+
+    class Hobby < ActiveRecord::Base
+      belongs_to :person
+
+      acts_as_audited_collection :parent => :person,
+          :cascade => true  # Cascades audit events to the parent
+    end
+
+The `:cascade => true` option specifies that the audit event in the child record should cascade upward, marking the parent as modified, and therefore generating a `'modify'` audit record in any grandparent for which `:track_modifications => true` has been specified..
+
+    p = Person.first                                  # Person name: 'Freda'
+    p.hobbies.create :name => 'Model Trains'          # Two audit records created.
+
+    p.hobbies_audits.last.action                      # 'add'
+    e.people_audits.last.action                       # 'modify'
+    e.people_audits.last.child_record                 # Person name: 'Freda'
+    e.people_audits.last.parent_record                # Employer name: 'Foo Inc.'
+
+Temporarily disabling auditing
+------------------------------
+
+    Person.without_collection_audit do
+      p.update_attributes :name => 'Fred'             # No audit record
+    end
+
+Keep in mind that this disables collection auditing completely in the current thread, not just for the `Person` model.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rake'
+require 'spec/rake/spectask'
+
+require 'rubygems'
+require 'rake/gempackagetask'
+
+PKG_FILES = FileList[
+  '[a-zA-Z]*',
+  'generators/**/*',
+  'lib/**/*',
+  'rails/**/*',
+  'spec/**/*'
+]
+
+spec = Gem::Specification.new do |s|
+  s.name = 'acts_as_audited_collection'
+  s.version = '0.3'
+  s.author = 'Shaun Mangelsdorf'
+  s.email = 's.mangelsdorf@gmail.com'
+  s.homepage = 'http://smangelsdorf.github.com'
+  s.platform = Gem::Platform::RUBY
+  s.summary = 'Extends ActiveRecord to allow auditing of associations'
+  s.files = PKG_FILES.to_a
+  s.require_path = 'lib'
+  s.has_rdoc = false
+  s.extra_rdoc_files = ['README.md']
+  s.rubyforge_project = 'auditcollection'
+  s.description = <<EOF
+Adds auditing capabilities to ActiveRecord associations, in a similar fashion to acts_as_audited.
+EOF
+end
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc 'Run the specs'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['--colour --format progress --loadby mtime --reverse']
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+desc 'Turn this plugin into a gem.'
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end

data/generators/audited_collection_migration/USAGE

@@ -0,0 +1,10 @@
+Description:
+    Generates the migration to create a collection_audits table.
+
+Example:
+    ./script/generate audited_collection_migration add_collection_audits_table
+
+    This will create:
+        db/migrate/*_add_collection_audits_table.rb
+
+	Run "rake db:migrate" to update your database.

data/generators/audited_collection_migration/audited_collection_migration_generator.rb

@@ -0,0 +1,9 @@
+# Released under the MIT license. See the LICENSE file for details
+
+class AuditedCollectionMigrationGenerator < Rails::Generator::NamedBase
+  def manifest
+    record do |m|
+      m.migration_template 'migration.rb', "db/migrate"
+    end
+  end
+end

data/generators/audited_collection_migration/templates/migration.rb

@@ -0,0 +1,21 @@
+class <%= class_name %> < ActiveRecord::Migration
+  def self.up
+    create_table :collection_audits, :force => true do |t|
+      t.references :parent_record, :polymorphic => {}
+      t.references :child_record, :polymorphic => {}
+      t.references :user, :polymorphic => {}
+      t.references :child_audit
+      t.string :action
+      t.string :association
+      t.datetime :created_at
+
+      t.index [:parent_record_id, :parent_record_type], :name => 'parent_record_index'
+      t.index [:child_record_id, :child_record_type], :name => 'child_record_index'
+      t.index [:user_id, :user_type], :name => 'user_index'
+    end
+  end
+
+  def self.down
+    drop_table :collection_audits
+  end
+end

data/init.rb

@@ -0,0 +1,3 @@
+# Released under the MIT license. See the LICENSE file for details
+
+require File.join(File.dirname(__FILE__), 'rails', 'init')

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/acts_as_audited_collection.rb

@@ -0,0 +1,230 @@
+# Released under the MIT license. See the LICENSE file for details
+
+require 'acts_as_audited_collection/collection_audit.rb'
+
+module ActiveRecord
+  module Acts
+    module AuditedCollection
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def acts_as_audited_collection(options = {})
+          unless self.included_modules.include?(InstanceMethods)
+            # First time use in this class, we have some extra work to do.
+            send :include, InstanceMethods 
+
+            class_inheritable_reader :audited_collections
+            write_inheritable_attribute :audited_collections, {}
+            attr_accessor :collection_audit_object_is_soft_deleted
+
+            after_create :collection_audit_create
+            before_update :collection_audit_update
+            after_destroy :collection_audit_destroy
+
+            has_many :child_collection_audits, :as => :child_record,
+              :class_name => 'CollectionAudit'
+          end
+
+          options = {
+            :name => self.name.tableize.to_sym,
+            :cascade => false,
+            :track_modifications => false,
+            :only => nil,
+            :except => nil,
+            :soft_delete => nil
+          }.merge(options)
+
+          options[:only] &&= [options[:only]].flatten.collect(&:to_s)
+          options[:except] &&= [options[:except]].flatten.collect(&:to_s)
+
+          unless options.has_key? :parent
+            raise ActiveRecord::ConfigurationError.new "Must specify parent for an acts_as_audited_collection (:parent => :object)"
+          end
+
+          parent_association = reflect_on_association(options[:parent])
+          unless parent_association && parent_association.belongs_to?
+            raise ActiveRecord::ConfigurationError.new "Parent association '#{options[:parent]}' must be a belongs_to relationship"
+          end
+
+          # Try explicit first, then default
+          options[:foreign_key] ||= parent_association.options[:foreign_key]
+          options[:foreign_key] ||= parent_association.primary_key_name
+
+          # TODO Remove this when polymorphic is supported.
+          if parent_association.options[:polymorphic]
+            raise ActiveRecord::ConfigurationError.new "Sorry, acts_as_audited_collection polymorphic associations haven't been added yet."
+          end
+
+          options[:parent_type] ||= parent_association.klass.name
+
+          define_acts_as_audited_collection options do |config|
+            config.merge! options
+          end
+        end
+
+        def acts_as_audited_collection_parent(options = {})
+          unless options.has_key? :for
+            raise ActiveRecord::ConfigurationError.new "Must specify relationship for an acts_as_audited_collection_parent (:for => :objects)"
+          end
+
+          child_association = reflect_on_association(options[:for])
+          if child_association.nil? || child_association.belongs_to?
+            raise ActiveRecord::ConfigurationError.new "Association '#{options[:for]}' must be a valid parent (i.e. not belongs_to) relationship"
+          end
+
+          has_many :"#{options[:for]}_audits", :as => :parent_record,
+              :class_name => 'CollectionAudit',
+              :conditions => ['association = ?', options[:for].to_s]
+        end
+
+        def define_acts_as_audited_collection(options)
+          yield(read_inheritable_attribute(:audited_collections)[options[:name]] ||= {})
+        end
+
+        def without_collection_audit
+          result = nil
+          Thread.current[:collection_audit_enabled] = returning(Thread.current[:collection_audit_enabled]) do
+            Thread.current[:collection_audit_enabled] = false
+            result = yield if block_given?
+          end
+
+          result
+        end
+      end
+
+      module InstanceMethods
+        protected
+        def collection_audit_create
+          collection_audit_write :action => 'add', :attributes => audited_collection_attributes
+        end
+
+        def collection_audit_update
+          audited_collections.each do |name, opts|
+            attributes = {opts[:foreign_key] => self.send(opts[:foreign_key])}
+            if collection_audit_is_soft_deleted?(opts)
+              collection_audit_write(
+                  :action => 'remove',
+                  :attributes => attributes
+              ) unless collection_audit_was_soft_deleted?(opts)
+            elsif collection_audit_was_soft_deleted?(opts)
+              collection_audit_write :action => 'add', :attributes => attributes
+            end
+          end
+
+          unless (old_values = audited_collection_attribute_changes).empty?
+            new_values = old_values.inject({}) { |map, (k, v)| map[k] = self[k]; map }
+
+            collection_audit_write :action => 'remove', :attributes => old_values
+            collection_audit_write :action => 'add', :attributes => new_values
+          end
+
+          collection_audit_write_as_modified unless audited_collection_excluded_attribute_changes.empty?
+        end
+
+        def collection_audit_destroy
+          collection_audit_write :action => 'remove', :attributes => audited_collection_attributes
+        end
+
+        def collection_audit_write_as_modified(child_audit=nil)
+          each_modification_tracking_audited_collection do |col|
+            collection_audit_write(:action => 'modify',
+                  :attributes => attributes.slice(col[:foreign_key]),
+                  :child_audit => child_audit
+            ) if audited_collection_should_care?(col)
+          end
+        end
+
+        def collection_audit_cascade(child, child_audit)
+          collection_audit_write_as_modified(child_audit) if respond_to? :audited_collections
+        end
+
+        private
+        def collection_audit_is_soft_deleted?(opts)
+          if opts[:soft_delete]
+            opts[:soft_delete].all?{|k,v| self.send(k) == v}
+          else
+            false
+          end
+        end
+
+        def collection_audit_was_soft_deleted?(opts)
+          if opts[:soft_delete]
+            opts[:soft_delete].all?{|k,v| self.send(:"#{k}_was") == v}
+          else
+            false
+          end
+        end
+
+        def collection_audit_write(opts)
+          # Only care about explicit false here, not the falseness of nil
+          return if Thread.current[:collection_audit_enabled] == false
+
+          mappings = audited_relation_attribute_mappings
+          opts[:attributes].reject{|k,v| v.nil?}.each do |fk, fk_val|
+            object_being_deleted = collection_audit_is_soft_deleted?(mappings[fk]) &&
+                !collection_audit_was_soft_deleted?(mappings[fk])
+            object_being_restored = collection_audit_was_soft_deleted?(mappings[fk]) &&
+                !collection_audit_is_soft_deleted?(mappings[fk])
+            object_is_deleted = collection_audit_is_soft_deleted?(mappings[fk]) &&
+                collection_audit_was_soft_deleted?(mappings[fk])
+
+            unless (object_being_deleted and opts[:action] != 'remove') or
+                (object_being_restored and opts[:action] != 'add') or
+                object_is_deleted
+
+              audit = child_collection_audits.create :parent_record_id => fk_val,
+                :parent_record_type => mappings[fk][:parent_type],
+                :action => opts[:action],
+                :association => mappings[fk][:name].to_s,
+                :child_audit => opts[:child_audit]
+
+              if mappings[fk][:cascade]
+                parent = mappings[fk][:parent_type].constantize.send :find, fk_val
+                parent.collection_audit_cascade(self, audit)
+              end
+            end
+          end
+        end
+
+        def each_modification_tracking_audited_collection
+          audited_collections.each do |name, options|
+            if options[:track_modifications]
+              yield options
+            end
+          end
+        end
+
+        def audited_collection_attributes
+          attributes.slice *audited_relation_attribute_mappings.keys
+        end
+
+        def audited_collection_excluded_attribute_changes
+          changed_attributes.except *audited_relation_attribute_mappings.keys
+        end
+
+        def audited_collection_attribute_changes
+          changed_attributes.slice *audited_relation_attribute_mappings.keys
+        end
+
+        def audited_collection_should_care?(collection)
+          if collection[:only]
+            !audited_collection_excluded_attribute_changes.slice(*collection[:only]).empty?
+          elsif collection[:except]
+            !audited_collection_excluded_attribute_changes.except(*collection[:except]).empty?
+          else
+            true
+          end
+        end
+
+        def audited_relation_attribute_mappings
+          audited_collections.inject({}) do |map, (name, options)|
+            map[options[:foreign_key]] = options
+            map
+          end
+        end
+      end
+    end
+  end
+end