paper_trail_without_deprecated 3.0.0.beta1

data/lib/paper_trail/has_paper_trail.rb

@@ -0,0 +1,308 @@
+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.
+      # :if, :unless  Procs that allow to specify conditions when to save versions for an object
+      # :only         inverse of `ignore` - a new `Version` will be created only for these attributes if supplied
+      # :skip         fields to ignore completely.  As with `ignore`, updates to these fields will not create
+      #               a new `Version`.  In addition, these fields will not be included in the serialized versions
+      #               of the object whenever a new `Version` is created.
+      # :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`.
+      # :version      the name to use for the method which returns the version the instance was reified from.
+      #               Default is `:version`.
+      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
+
+        class_attribute :version_association_name
+        self.version_association_name = options[:version] || :version
+
+        # The version this instance was reified from.
+        attr_accessor self.version_association_name
+
+        class_attribute :version_class_name
+        self.version_class_name = options[:class_name] || 'PaperTrail::Version'
+
+        class_attribute :paper_trail_options
+        self.paper_trail_options = options.dup
+
+        [:ignore, :skip, :only].each do |k|
+          paper_trail_options[k] =
+            ([paper_trail_options[k]].flatten.compact || []).map &:to_s
+        end
+
+        paper_trail_options[:meta] ||= {}
+
+        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
+
+        attr_accessor :paper_trail_event
+
+        if ActiveRecord::VERSION::STRING.to_f >= 4.0 # `has_many` syntax for specifying order uses a lambda in Rails 4
+          has_many self.versions_association_name,
+            lambda { order("#{PaperTrail.timestamp_field} ASC") },
+            :class_name => self.version_class_name, :as => :item
+        else
+          has_many self.versions_association_name,
+            :class_name => version_class_name,
+            :as         => :item,
+            :order      => "#{PaperTrail.timestamp_field} ASC"
+        end
+
+        options_on = Array(options[:on]) # so that a single symbol can be passed in without wrapping it in an `Array`
+        after_create  :record_create, :if => :save_version? if options_on.empty? || options_on.include?(:create)
+        before_update :record_update, :if => :save_version? if options_on.empty? || options_on.include?(:update)
+        after_destroy :record_destroy, :if => :save_version? if options_on.empty? || 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
+
+      # Used for Version#object attribute
+      def serialize_attributes_for_paper_trail(attributes)
+        serialized_attributes.each do |key, coder|
+          if attributes.key?(key)
+            coder = PaperTrail::Serializers::Yaml unless coder.respond_to?(:dump) # Fall back to YAML if `coder` has no `dump` method
+            attributes[key] = coder.dump(attributes[key])
+          end
+        end
+      end
+
+      def unserialize_attributes_for_paper_trail(attributes)
+        serialized_attributes.each do |key, coder|
+          if attributes.key?(key)
+            coder = PaperTrail::Serializers::Yaml unless coder.respond_to?(:dump)
+            attributes[key] = coder.load(attributes[key])
+          end
+        end
+      end
+
+      # Used for Version#object_changes attribute
+      def serialize_attribute_changes(changes)
+        serialized_attributes.each do |key, coder|
+          if changes.key?(key)
+            coder = PaperTrail::Serializers::Yaml unless coder.respond_to?(:dump) # Fall back to YAML if `coder` has no `dump` method
+            old_value, new_value = changes[key]
+            changes[key] = [coder.dump(old_value),
+                            coder.dump(new_value)]
+          end
+        end
+      end
+
+      def unserialize_attribute_changes(changes)
+        serialized_attributes.each do |key, coder|
+          if changes.key?(key)
+            coder = PaperTrail::Serializers::Yaml unless coder.respond_to?(:dump)
+            old_value, new_value = changes[key]
+            changes[key] = [coder.load(old_value),
+                            coder.load(new_value)]
+          end
+        end
+      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?
+        source_version.nil?
+      end
+
+      # Returns who put the object into its current state.
+      def originator
+        version_class.with_item_keys(self.class.base_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.
+        v = send(self.class.versions_association_name).following(timestamp).first
+        v ? v.reify(reify_options) : self
+      end
+
+      # Returns the objects (not Versions) as they were between the given times.
+      def versions_between(start_time, end_time, reify_options={})
+        versions = send(self.class.versions_association_name).between(start_time, end_time)
+        versions.collect { |version| version_at(version.send PaperTrail.timestamp_field) }
+      end
+
+      # Returns the object (not a Version) as it was most recently.
+      def previous_version
+        preceding_version = source_version ? source_version.previous : send(self.class.versions_association_name).last
+        preceding_version.reify if preceding_version
+      end
+
+      # Returns the object (not a Version) as it became next.
+      # 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?
+      def next_version
+        subsequent_version = source_version.next
+        subsequent_version ? subsequent_version.reify : self.class.find(self.id)
+      rescue
+        nil
+      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 source_version
+        send self.class.version_association_name
+      end
+
+      def record_create
+        if paper_trail_switched_on?
+          data = {
+            :event     => paper_trail_event || 'create',
+            :whodunnit => PaperTrail.whodunnit
+          }
+
+          if changed_notably? and version_class.column_names.include?('object_changes')
+            data[:object_changes] = PaperTrail.serializer.dump(changes_for_paper_trail)
+          end
+          send(self.class.versions_association_name).create! merge_metadata(data)
+        end
+      end
+
+      def record_update
+        if paper_trail_switched_on? && changed_notably?
+          data = {
+            :event     => paper_trail_event || 'update',
+            :object    => object_to_string(item_before_change),
+            :whodunnit => PaperTrail.whodunnit
+          }
+          if version_class.column_names.include? 'object_changes'
+            data[:object_changes] = PaperTrail.serializer.dump(changes_for_paper_trail)
+          end
+          send(self.class.versions_association_name).build merge_metadata(data)
+        end
+      end
+
+      def changes_for_paper_trail
+        self.changes.delete_if do |key, value|
+          !notably_changed.include?(key)
+        end.tap do |changes|
+          self.class.serialize_attribute_changes(changes) # Use serialized value for attributes when necessary
+        end
+      end
+
+      def record_destroy
+        if paper_trail_switched_on? and not new_record?
+          version_class.create merge_metadata(:item_id   => self.id,
+                                              :item_type => self.class.base_class.name,
+                                              :event     => paper_trail_event || 'destroy',
+                                              :object    => object_to_string(item_before_change),
+                                              :whodunnit => PaperTrail.whodunnit)
+          send(self.class.versions_association_name).send :load_target
+        end
+      end
+
+      def merge_metadata(data)
+        # First we merge the model-level metadata in `meta`.
+        paper_trail_options[:meta].each do |k,v|
+          data[k] =
+            if v.respond_to?(:call)
+              v.call(self)
+            elsif v.is_a?(Symbol) && respond_to?(v)
+              # if it is an attribute that is changing, be sure to grab the current version
+              if has_attribute?(v) && send("#{v}_changed?".to_sym)
+                send("#{v}_was".to_sym)
+              else
+                send(v)
+              end
+            else
+              v
+            end
+        end
+        # Second we merge any extra data from the controller (if available).
+        data.merge(PaperTrail.controller_info || {})
+      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.select { |k,v| self.class.column_names.include?(k) }.each { |attr, before| prev[attr] = before }
+        end
+      end
+
+      def object_to_string(object)
+        _attrs = object.attributes.except(*self.class.paper_trail_options[:skip]).tap do |attributes|
+          self.class.serialize_attributes_for_paper_trail attributes
+        end
+        PaperTrail.serializer.dump(_attrs)
+      end
+
+      def changed_notably?
+        notably_changed.any?
+      end
+
+      def notably_changed
+        only = self.class.paper_trail_options[:only]
+        only.empty? ? changed_and_not_ignored : (changed_and_not_ignored & only)
+      end
+
+      def changed_and_not_ignored
+        ignore = self.class.paper_trail_options[:ignore]
+        skip   = self.class.paper_trail_options[:skip]
+        changed - ignore - skip
+      end
+
+      def paper_trail_switched_on?
+        PaperTrail.enabled? && PaperTrail.enabled_for_controller? && self.class.paper_trail_enabled_for_model
+      end
+
+      def save_version?
+        if_condition     = self.class.paper_trail_options[:if]
+        unless_condition = self.class.paper_trail_options[:unless]
+        (if_condition.blank? || if_condition.call(self)) && !unless_condition.try(:call, self)
+      end
+    end
+  end
+end

data/lib/paper_trail/serializers/json.rb

@@ -0,0 +1,17 @@
+require 'active_support/json'
+
+module PaperTrail
+  module Serializers
+    module Json
+      extend self # makes all instance methods become module methods as well
+
+      def load(string)
+        ActiveSupport::JSON.decode string
+      end
+
+      def dump(object)
+        ActiveSupport::JSON.encode object
+      end
+    end
+  end
+end

data/lib/paper_trail/serializers/yaml.rb

@@ -0,0 +1,17 @@
+require 'yaml'
+
+module PaperTrail
+  module Serializers
+    module Yaml
+      extend self # makes all instance methods become module methods as well
+
+      def load(string)
+        YAML.load string
+      end
+
+      def dump(object)
+        YAML.dump object
+      end
+    end
+  end
+end

data/lib/paper_trail/version.rb

@@ -0,0 +1,200 @@
+module PaperTrail
+  class Version < ActiveRecord::Base
+    belongs_to :item, :polymorphic => true
+    validates_presence_of :event
+    attr_accessible :item_type, :item_id, :event, :whodunnit, :object, :object_changes if PaperTrail.active_record_protected_attributes?
+
+    after_create :enforce_version_limit!
+
+    def self.with_item_keys(item_type, item_id)
+      where :item_type => item_type, :item_id => item_id
+    end
+
+    def self.creates
+      where :event => 'create'
+    end
+
+    def self.updates
+      where :event => 'update'
+    end
+
+    def self.destroys
+      where :event => 'destroy'
+    end
+
+    def self.not_creates
+      where 'event <> ?', 'create'
+    end
+
+    scope :subsequent, lambda { |version|
+      where("#{self.primary_key} > ?", version).order("#{self.primary_key} ASC")
+    }
+
+    scope :preceding, lambda { |version|
+      where("#{self.primary_key} < ?", version).order("#{self.primary_key} DESC")
+    }
+
+    scope :following, lambda { |timestamp|
+      # TODO: is this :order necessary, considering its presence on the has_many :versions association?
+      where("#{PaperTrail.timestamp_field} > ?", timestamp).
+        order("#{PaperTrail.timestamp_field} ASC, #{self.primary_key} ASC")
+    }
+
+    scope :between, lambda { |start_time, end_time|
+      where("#{PaperTrail.timestamp_field} > ? AND #{PaperTrail.timestamp_field} < ?", start_time, end_time).
+        order("#{PaperTrail.timestamp_field} ASC, #{self.primary_key} ASC")
+    }
+
+    # Restore the item from this version.
+    #
+    # This will automatically restore all :has_one associations as they were "at the time",
+    # if they are also being versioned by PaperTrail.  NOTE: this isn't always guaranteed
+    # to work so you can either change the lookback period (from the default 3 seconds) or
+    # opt out.
+    #
+    # Options:
+    # +:has_one+   set to `false` to opt out of has_one reification.
+    #              set to a float to change the lookback time (check whether your db supports
+    #              sub-second datetimes if you want them).
+    def reify(options = {})
+      without_identity_map do
+        options[:has_one] = 3 if options[:has_one] == true
+        options.reverse_merge! :has_one => false
+
+        unless object.nil?
+          attrs = PaperTrail.serializer.load object
+
+          # Normally a polymorphic belongs_to relationship allows us
+          # to get the object we belong to by calling, in this case,
+          # +item+.  However this returns nil if +item+ has been
+          # destroyed, and we need to be able to retrieve destroyed
+          # objects.
+          #
+          # In this situation we constantize the +item_type+ to get hold of
+          # the class...except when the stored object's attributes
+          # include a +type+ key.  If this is the case, the object
+          # we belong to is using single table inheritance and the
+          # +item_type+ will be the base class, not the actual subclass.
+          # If +type+ is present but empty, the class is the base class.
+
+          if item
+            model = item
+            # Look for attributes that exist in the model and not in this version. These attributes should be set to nil.
+            (model.attribute_names - attrs.keys).each { |k| attrs[k] = nil }
+          else
+            inheritance_column_name = item_type.constantize.inheritance_column
+            class_name = attrs[inheritance_column_name].blank? ? item_type : attrs[inheritance_column_name]
+            klass = class_name.constantize
+            model = klass.new
+          end
+
+          model.class.unserialize_attributes_for_paper_trail attrs
+
+          # Set all the attributes in this version on the model
+          attrs.each do |k, v|
+            if model.respond_to?("#{k}=")
+              model[k.to_sym] = v
+            else
+              logger.warn "Attribute #{k} does not exist on #{item_type} (Version id: #{id})."
+            end
+          end
+
+          model.send "#{model.class.version_association_name}=", self
+
+          unless options[:has_one] == false
+            reify_has_ones model, options[:has_one]
+          end
+
+          model
+        end
+      end
+    end
+
+    # Returns what changed in this version of the item.  Cf. `ActiveModel::Dirty#changes`.
+    # Returns nil if your `versions` table does not have an `object_changes` text column.
+    def changeset
+      return nil unless self.class.column_names.include? 'object_changes'
+
+      HashWithIndifferentAccess.new(PaperTrail.serializer.load(object_changes)).tap do |changes|
+        item_type.constantize.unserialize_attribute_changes(changes)
+      end
+    rescue
+      {}
+    end
+
+    # Returns who put the item into the state stored in this version.
+    def originator
+      previous.try :whodunnit
+    end
+
+    # Returns who changed the item from the state it had in this version.
+    # This is an alias for `whodunnit`.
+    def terminator
+      whodunnit
+    end
+
+    def sibling_versions
+      self.class.with_item_keys(item_type, item_id)
+    end
+
+    def next
+      sibling_versions.subsequent(self).first
+    end
+
+    def previous
+      sibling_versions.preceding(self).first
+    end
+
+    def index
+      id_column = self.class.primary_key.to_sym
+      sibling_versions.select(id_column).order("#{id_column} ASC").map(&id_column).index(self.send(id_column))
+    end
+
+    private
+
+    # In Rails 3.1+, calling reify on a previous version confuses the
+    # IdentityMap, if enabled. This prevents insertion into the map.
+    def without_identity_map(&block)
+      if defined?(ActiveRecord::IdentityMap) && ActiveRecord::IdentityMap.respond_to?(:without)
+        ActiveRecord::IdentityMap.without(&block)
+      else
+        block.call
+      end
+    end
+
+    # Restore the `model`'s has_one associations as they were when this version was
+    # superseded by the next (because that's what the user was looking at when they
+    # made the change).
+    #
+    # The `lookback` sets how many seconds before the model's change we go.
+    def reify_has_ones(model, lookback)
+      model.class.reflect_on_all_associations(:has_one).each do |assoc|
+        child = model.send assoc.name
+        if child.respond_to? :version_at
+          # N.B. we use version of the child as it was `lookback` seconds before the parent was updated.
+          # Ideally we want the version of the child as it was just before the parent was updated...
+          # but until PaperTrail knows which updates are "together" (e.g. parent and child being
+          # updated on the same form), it's impossible to tell when the overall update started;
+          # and therefore impossible to know when "just before" was.
+          if (child_as_it_was = child.version_at(send(PaperTrail.timestamp_field) - lookback.seconds))
+            child_as_it_was.attributes.each do |k,v|
+              model.send(assoc.name).send :write_attribute, k.to_sym, v rescue nil
+            end
+          else
+            model.send "#{assoc.name}=", nil
+          end
+        end
+      end
+    end
+
+    # checks to see if a value has been set for the `version_limit` config option, and if so enforces it
+    def enforce_version_limit!
+      return unless PaperTrail.config.version_limit.is_a? Numeric
+      previous_versions = sibling_versions.not_creates
+      return unless previous_versions.size > PaperTrail.config.version_limit
+      excess_previous_versions = previous_versions - previous_versions.last(PaperTrail.config.version_limit)
+      excess_previous_versions.map(&:destroy)
+    end
+
+  end
+end