bkwld-paper_trail 2.3.2

data/Rakefile

@@ -0,0 +1,15 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+desc 'Test the paper_trail plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+desc 'Default: run unit tests.'
+task :default => :test

data/lib/generators/paper_trail/USAGE

@@ -0,0 +1,2 @@
+Description:
+  Generates (but does not run) a migration to add a versions table.

data/lib/generators/paper_trail/install_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record/migration'
+
+module PaperTrail
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+    extend ActiveRecord::Generators::Migration
+
+    source_root File.expand_path('../templates', __FILE__)
+    class_option :with_changes, :type => :boolean, :default => false, :desc => "Store changeset (diff) with each version"
+
+    desc 'Generates (but does not run) a migration to add a versions table.'
+
+    def create_migration_file
+      migration_template 'create_versions.rb', 'db/migrate/create_versions.rb'
+      migration_template 'add_object_changes_column_to_versions.rb', 'db/migrate/add_object_changes_column_to_versions.rb' if options.with_changes?
+    end
+  end
+end

data/lib/generators/paper_trail/templates/add_object_changes_column_to_versions.rb

@@ -0,0 +1,9 @@
+class AddObjectChangesColumnToVersions < ActiveRecord::Migration
+  def self.up
+    add_column :versions, :object_changes, :text
+  end
+
+  def self.down
+    remove_column :versions, :object_changes
+  end
+end

data/lib/generators/paper_trail/templates/create_versions.rb

@@ -0,0 +1,19 @@
+class CreateVersions < ActiveRecord::Migration
+  def self.up
+    create_table :versions do |t|
+      t.string   :item_type, :null => false
+      t.integer  :item_id,   :null => false
+      t.string   :event,     :null => false
+      t.string   :whodunnit
+      t.text     :object
+      t.text     :columns
+      t.datetime :created_at
+    end
+    add_index :versions, [:item_type, :item_id]
+  end
+
+  def self.down
+    remove_index :versions, [:item_type, :item_id]
+    drop_table :versions
+  end
+end

data/lib/paper_trail.rb

@@ -0,0 +1,87 @@
+require 'singleton'
+require 'yaml'
+
+require 'paper_trail/config'
+require 'paper_trail/controller'
+require 'paper_trail/has_paper_trail'
+require 'paper_trail/version'
+
+# PaperTrail's module methods can be called in both models and controllers.
+module PaperTrail
+
+  # Switches PaperTrail on or off.
+  def self.enabled=(value)
+    PaperTrail.config.enabled = value
+  end
+
+  # Returns `true` if PaperTrail is on, `false` otherwise.
+  # PaperTrail is enabled by default.
+  def self.enabled?
+    !!PaperTrail.config.enabled
+  end
+
+  # Returns `true` if PaperTrail is enabled for the request, `false` otherwise.
+  #
+  # See `PaperTrail::Controller#paper_trail_enabled_for_controller`.
+  def self.enabled_for_controller?
+    !!paper_trail_store[:request_enabled_for_controller]
+  end
+
+  # Sets whether PaperTrail is enabled or disabled for the current request.
+  def self.enabled_for_controller=(value)
+    paper_trail_store[:request_enabled_for_controller] = value
+  end
+
+  # Returns who is reponsible for any changes that occur.
+  def self.whodunnit
+    paper_trail_store[:whodunnit]
+  end
+
+  # Sets who is responsible for any changes that occur.
+  # You would normally use this in a migration or on the console,
+  # when working with models directly.  In a controller it is set
+  # automatically to the `current_user`.
+  def self.whodunnit=(value)
+    paper_trail_store[:whodunnit] = value
+  end
+
+  # Returns any information from the controller that you want
+  # PaperTrail to store.
+  #
+  # See `PaperTrail::Controller#info_for_paper_trail`.
+  def self.controller_info
+    paper_trail_store[:controller_info]
+  end
+
+  # Sets any information from the controller that you want PaperTrail
+  # to store.  By default this is set automatically by a before filter.
+  def self.controller_info=(value)
+    paper_trail_store[:controller_info] = value
+  end
+
+
+  private
+
+  # Thread-safe hash to hold PaperTrail's data.
+  # Initializing with needed default values.
+  def self.paper_trail_store
+    Thread.current[:paper_trail] ||= {
+      :request_enabled_for_controller => true
+    }
+  end
+
+  # Returns PaperTrail's configuration object.
+  def self.config
+    @@config ||= PaperTrail::Config.instance
+  end
+
+end
+
+
+ActiveSupport.on_load(:active_record) do
+  include PaperTrail::Model
+end
+
+ActiveSupport.on_load(:action_controller) do
+  include PaperTrail::Controller
+end

data/lib/paper_trail/config.rb

@@ -0,0 +1,11 @@
+module PaperTrail
+  class Config
+    include Singleton
+    attr_accessor :enabled
+ 
+    def initialize
+      # Indicates whether PaperTrail is on or off.
+      @enabled = true
+    end
+  end
+end

data/lib/paper_trail/controller.rb

@@ -0,0 +1,76 @@
+module PaperTrail
+  module Controller
+
+    def self.included(base)
+      base.before_filter :set_paper_trail_whodunnit
+      base.before_filter :set_paper_trail_controller_info
+      base.before_filter :set_paper_trail_enabled_for_controller
+    end
+
+    protected
+
+    # Returns the user who is responsible for any changes that occur.
+    # By default this calls `current_user` and returns the result.
+    # 
+    # Override this method in your controller to call a different
+    # method, e.g. `current_person`, or anything you like.
+    def user_for_paper_trail
+      current_user rescue nil
+    end
+
+    # Returns any information about the controller or request that you
+    # want PaperTrail to store alongside any changes that occur.  By
+    # default this returns an empty hash.
+    #
+    # Override this method in your controller to return a hash of any
+    # information you need.  The hash's keys must correspond to columns
+    # in your `versions` table, so don't forget to add any new columns
+    # you need.
+    #
+    # For example:
+    #
+    #     {:ip => request.remote_ip, :user_agent => request.user_agent}
+    #
+    # The columns `ip` and `user_agent` must exist in your `versions` # table.
+    #
+    # Use the `:meta` option to `PaperTrail::Model::ClassMethods.has_paper_trail`
+    # to store any extra model-level data you need.
+    def info_for_paper_trail
+      {}
+    end
+
+    # Returns `true` (default) or `false` depending on whether PaperTrail should
+    # be active for the current request.
+    #
+    # Override this method in your controller to specify when PaperTrail should
+    # be off.
+    def paper_trail_enabled_for_controller
+      true
+    end
+
+    private
+
+    # Tells PaperTrail whether versions should be saved in the current request.
+    def set_paper_trail_enabled_for_controller
+      ::PaperTrail.enabled_for_controller = paper_trail_enabled_for_controller
+    end
+
+    # Tells PaperTrail who is responsible for any changes that occur.
+    def set_paper_trail_whodunnit
+      ::PaperTrail.whodunnit = user_for_paper_trail
+    end
+
+    # DEPRECATED: please use `set_paper_trail_whodunnit` instead.
+    def set_whodunnit
+      logger.warn '[PaperTrail]: the `set_whodunnit` controller method has been deprecated.  Please rename to `set_paper_trail_whodunnit`.'
+      set_paper_trail_whodunnit
+    end
+
+    # Tells PaperTrail any information from the controller you want
+    # to store alongside any changes that occur.
+    def set_paper_trail_controller_info
+      ::PaperTrail.controller_info = info_for_paper_trail
+    end
+
+  end
+end

data/lib/paper_trail/has_paper_trail.rb

@@ -0,0 +1,228 @@
+module PaperTrail
+  module Model
+
+    def self.included(base)
+      base.send :extend, ClassMethods
+    end
+
+
+    module ClassMethods
+      # Declare this in your model to track every create, update, and destroy.  Each version of
+      # the model is available in the `versions` association.
+      #
+      # Options:
+      # :on           the events to track (optional; defaults to all of them).  Set to an array of
+      #               `:create`, `:update`, `:destroy` as desired.
+      # :class_name   the name of a custom Version class.  This class should inherit from Version.
+      # :ignore       an array of attributes for which a new `Version` will not be created if only they change.
+      # :only         inverse of `ignore` - a new `Version` will be created only for these attributes if supplied
+      # :meta         a hash of extra data to store.  You must add a column to the `versions` table for each key.
+      #               Values are objects or procs (which are called with `self`, i.e. the model with the paper
+      #               trail).  See `PaperTrail::Controller.info_for_paper_trail` for how to store data from
+      #               the controller.
+      # :versions     the name to use for the versions association.  Default is `:versions`.
+      def has_paper_trail(options = {})
+        # Lazily include the instance methods so we don't clutter up
+        # any more ActiveRecord models than we have to.
+        send :include, InstanceMethods
+
+        # The version this instance was reified from.
+        attr_accessor :version
+
+        class_attribute :version_class_name
+        self.version_class_name = options[:class_name] || 'Version'
+
+        class_attribute :ignore
+        self.ignore = ([options[:ignore]].flatten.compact || []).map &:to_s
+
+        class_attribute :only
+        self.only = ([options[:only]].flatten.compact || []).map &:to_s
+
+        class_attribute :meta
+        self.meta = options[:meta] || {}
+
+        class_attribute :track_columns
+        self.track_columns = options[:track_columns] || true
+
+        class_attribute :ignored_columns
+        self.ignored_columns = options[:ignored_columns] || ['id', 'updated_at', 'created_at']
+
+        class_attribute :paper_trail_enabled_for_model
+        self.paper_trail_enabled_for_model = true
+
+        class_attribute :versions_association_name
+        self.versions_association_name = options[:versions] || :versions
+
+        has_many self.versions_association_name,
+                 :class_name => version_class_name,
+                 :as         => :item,
+                 :order      => "created_at ASC, #{self.version_class_name.constantize.primary_key} ASC"
+
+        after_create  :record_create  if !options[:on] || options[:on].include?(:create)
+        before_update :record_update  if !options[:on] || options[:on].include?(:update)
+        after_destroy :record_destroy if !options[:on] || options[:on].include?(:destroy)
+      end
+
+      # Switches PaperTrail off for this class.
+      def paper_trail_off
+        self.paper_trail_enabled_for_model = false
+      end
+
+      # Switches PaperTrail on for this class.
+      def paper_trail_on
+        self.paper_trail_enabled_for_model = true
+      end
+    end
+
+    # Wrap the following methods in a module so we can include them only in the
+    # ActiveRecord models that declare `has_paper_trail`.
+    module InstanceMethods
+      # Returns true if this instance is the current, live one;
+      # returns false if this instance came from a previous version.
+      def live?
+        version.nil?
+      end
+
+      # Returns who put the object into its current state.
+      def originator
+        version_class.with_item_keys(self.class.name, id).last.try :whodunnit
+      end
+
+      # Returns the object (not a Version) as it was at the given timestamp.
+      def version_at(timestamp, reify_options={})
+        # Because a version stores how its object looked *before* the change,
+        # we need to look for the first version created *after* the timestamp.
+        version = send(self.class.versions_association_name).after(timestamp).first
+        version ? version.reify(reify_options) : self
+      end
+
+      # Returns the object (not a Version) as it was most recently.
+      def previous_version
+        preceding_version = version ? version.previous : send(self.class.versions_association_name).last
+        preceding_version.try :reify
+      end
+
+      # Returns the object (not a Version) as it became next.
+      def next_version
+        # NOTE: if self (the item) was not reified from a version, i.e. it is the
+        # "live" item, we return nil.  Perhaps we should return self instead?
+        subsequent_version = version ? version.next : nil
+        subsequent_version.reify if subsequent_version
+      end
+
+      # Executes the given method or block without creating a new version.
+      def without_versioning(method = nil)
+        paper_trail_was_enabled = self.paper_trail_enabled_for_model
+        self.class.paper_trail_off
+        method ? method.to_proc.call(self) : yield
+      ensure
+        self.class.paper_trail_on if paper_trail_was_enabled
+      end
+
+      private
+
+      def version_class
+        version_class_name.constantize
+      end
+
+      def record_create
+        if switched_on?
+          send(self.class.versions_association_name).create merge_metadata(:event => 'create', :whodunnit => PaperTrail.whodunnit)
+        end
+      end
+
+      def record_update
+        if switched_on? && changed_notably?
+          data = {
+            :event     => 'update',
+            :object    => object_to_string(item_before_change),
+            :whodunnit => PaperTrail.whodunnit
+          }
+          
+          if version_class.column_names.include? 'object_changes'
+            # The double negative (reject, !include?) preserves the hash structure of self.changes.
+            data[:object_changes] = self.changes.reject do |key, value|
+              !notably_changed.include?(key)
+            end.to_yaml
+          end
+          send(self.class.versions_association_name).build merge_metadata(data)
+        end
+      end
+
+      def record_destroy
+        if switched_on? and not new_record?
+          version_class.create merge_metadata(:item_id   => self.id,
+                                              :item_type => self.class.base_class.name,
+                                              :event     => 'destroy',
+                                              :object    => object_to_string(item_before_change),
+                                              :whodunnit => PaperTrail.whodunnit)
+        end
+        send(self.class.versions_association_name).send :load_target
+      end
+
+      def merge_metadata(data)
+        # First we merge the model-level metadata in `meta`.
+        meta.each do |k,v|
+          data[k] =
+            if v.respond_to?(:call)
+              v.call(self)
+            elsif v.is_a?(Symbol) && respond_to?(v)
+              send(v)
+            else
+              v
+            end
+        end
+        # Second we merge any extra data from the controller (if available).
+        data.merge(PaperTrail.controller_info || {})
+        
+        column_changes = {}
+        change_info = changes.dup
+        change_info.reject! { |column_name, change_values|
+          self.class.ignored_columns.include?(column_name)
+        }
+
+        change_info.each do |column_name, change_values|
+          column_changes[column_name.to_sym] = {
+            :after  => change_values[1],
+            :before => change_values[0]
+          }
+        end
+        
+        data.merge(:columns => column_changes)
+      end
+
+      def item_before_change
+        previous = self.dup
+        # `dup` clears timestamps so we add them back.
+        all_timestamp_attributes.each do |column|
+          previous[column] = send(column) if respond_to?(column) && !send(column).nil?
+        end
+        previous.tap do |prev|
+          prev.id = id
+          changed_attributes.each { |attr, before| prev[attr] = before }
+        end
+      end
+
+      def object_to_string(object)
+        object.attributes.to_yaml
+      end
+
+      def changed_notably?
+        notably_changed.any?
+      end
+
+      def notably_changed
+        self.class.only.empty? ? changed_and_not_ignored : (changed_and_not_ignored & self.class.only)
+      end
+
+      def changed_and_not_ignored
+        changed - self.class.ignore
+      end
+
+      def switched_on?
+        PaperTrail.enabled? && PaperTrail.enabled_for_controller? && self.class.paper_trail_enabled_for_model
+      end
+    end
+
+  end
+end