paper-trail-gem--paper_trail/lib/paper_trail/has_paper_trail.rb

require "active_support/core_ext/object" # provides the `try` method
require "paper_trail/attributes_serialization"

module PaperTrail
  # Extensions to `ActiveRecord::Base`.  See `frameworks/active_record.rb`.
  module Model
    def self.included(base)
      base.send :extend, ClassMethods
      base.send :attr_accessor, :paper_trail_habtm
    end

    # :nodoc:
    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 `PaperTrail::Version`.
      # - :ignore - An array of attributes for which a new `Version` will not be
      #   created if only they change. It can also aceept a Hash as an
      #   argument where the key is the attribute to ignore (a `String` or
      #   `Symbol`), which will only be ignored if the value is a `Proc` which
      #   returns truthily.
      # - :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 it can also aceept a Hash as an
      #   argument where the key is the attribute to track (a `String` or
      #   `Symbol`), which will only be counted if the value is a `Proc` which
      #   returns truthily.
      # - :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`.
      # - :save_changes - Whether or not to save changes to the object_changes
      #   column if it exists. Default is true
      # - :join_tables - If the model has a has_and_belongs_to_many relation
      #   with an unpapertrailed model, passing the name of the association to
      #   the join_tables option will paper trail the join table but not save
      #   the other model, allowing reification of the association but with the
      #   other models latest state (if the other model is paper trailed, this
      #   option does nothing)
      #
      def has_paper_trail(options = {})
        options[:on] ||= [:create, :update, :destroy]

        # Wrap the :on option in an array if necessary. This allows a single
        # symbol to be passed in.
        options[:on] = Array(options[:on])

        setup_model_for_paper_trail(options)

        setup_callbacks_from_options options[:on]

        setup_callbacks_for_habtm options[:join_tables]
      end

      def update_for_callback(name, callback, model, assoc)
        model.paper_trail_habtm ||= {}
        model.paper_trail_habtm.reverse_merge!(name => { removed: [], added: [] })
        case callback
        when :before_add
          model.paper_trail_habtm[name][:added] |= [assoc.id]
          model.paper_trail_habtm[name][:removed] -= [assoc.id]
        when :before_remove
          model.paper_trail_habtm[name][:removed] |= [assoc.id]
          model.paper_trail_habtm[name][:added] -= [assoc.id]
        end
      end

      attr_reader :paper_trail_save_join_tables

      def setup_callbacks_for_habtm(join_tables)
        @paper_trail_save_join_tables = Array.wrap(join_tables)
        # Adds callbacks to record changes to habtm associations such that on
        # save the previous version of the association (if changed) can be
        # interpreted
        reflect_on_all_associations(:has_and_belongs_to_many).
          reject { |a| paper_trail_options[:skip].include?(a.name.to_s) }.
          each do |a|
            added_callback = lambda do |*args|
              update_for_callback(a.name, :before_add, args[-2], args.last)
            end
            removed_callback = lambda do |*args|
              update_for_callback(a.name, :before_remove, args[-2], args.last)
            end
            send(:"before_add_for_#{a.name}").send(:<<, added_callback)
            send(:"before_remove_for_#{a.name}").send(:<<, removed_callback)
          end
      end

      def setup_model_for_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
        send :extend, AttributesSerialization

        class_attribute :version_association_name
        self.version_association_name = options[:version] || :version

        # The version this instance was reified from.
        attr_accessor 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 { |attr|
            attr.is_a?(Hash) ? attr.stringify_keys : attr.to_s
          }
        end

        paper_trail_options[:meta] ||= {}
        paper_trail_options[:save_changes] = true if paper_trail_options[:save_changes].nil?

        class_attribute :versions_association_name
        self.versions_association_name = options[:versions] || :versions

        attr_accessor :paper_trail_event

        # `has_many` syntax for specifying order uses a lambda in Rails 4
        if ::ActiveRecord::VERSION::MAJOR >= 4
          has_many versions_association_name,
            -> { order(model.timestamp_sort_order) },
            class_name: version_class_name, as: :item
        else
          has_many versions_association_name,
            class_name: version_class_name,
            as: :item,
            order: paper_trail_version_class.timestamp_sort_order
        end

        # Reset the transaction id when the transaction is closed.
        after_commit :reset_transaction_id
        after_rollback :reset_transaction_id
        after_rollback :clear_rolled_back_versions
      end

      def setup_callbacks_from_options(options_on = [])
        options_on.each do |option|
          send "paper_trail_on_#{option}"
        end
      end

      # Record version before or after "destroy" event
      def paper_trail_on_destroy(recording_order = "before")
        unless %w(after before).include?(recording_order.to_s)
          raise ArgumentError, 'recording order can only be "after" or "before"'
        end

        if recording_order == "after" &&
            Gem::Version.new(ActiveRecord::VERSION::STRING) >= Gem::Version.new("5")
          if ::ActiveRecord::Base.belongs_to_required_by_default
            ::ActiveSupport::Deprecation.warn(
              "paper_trail_on_destroy(:after) is incompatible with ActiveRecord " +
                "belongs_to_required_by_default and has no effect. Please use :before " +
                "or disable belongs_to_required_by_default."
            )
          end
        end

        send "#{recording_order}_destroy", :record_destroy, if: :save_version?

        return if paper_trail_options[:on].include?(:destroy)
        paper_trail_options[:on] << :destroy
      end

      # Record version after "update" event
      def paper_trail_on_update
        before_save :reset_timestamp_attrs_for_update_if_needed!, on: :update
        after_update :record_update, if: :save_version?
        after_update :clear_version_instance!

        return if paper_trail_options[:on].include?(:update)
        paper_trail_options[:on] << :update
      end

      # Record version after "create" event
      def paper_trail_on_create
        after_create :record_create, if: :save_version?

        return if paper_trail_options[:on].include?(:create)
        paper_trail_options[:on] << :create
      end

      # Switches PaperTrail off for this class.
      def paper_trail_off!
        PaperTrail.enabled_for_model(self, false)
      end

      # Switches PaperTrail on for this class.
      def paper_trail_on!
        PaperTrail.enabled_for_model(self, true)
      end

      def paper_trail_enabled_for_model?
        return false unless include?(PaperTrail::Model::InstanceMethods)
        PaperTrail.enabled_for_model?(self)
      end

      def paper_trail_version_class
        @paper_trail_version_class ||= version_class_name.constantize
      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 paper_trail_originator
        (source_version || send(self.class.versions_association_name).last).try(:whodunnit)
      end

      def originator
        ::ActiveSupport::Deprecation.warn "Use paper_trail_originator instead of originator."
        paper_trail_originator
      end

      # Invoked after rollbacks to ensure versions records are not created
      # for changes that never actually took place.
      # Optimization: Use lazy `reset` instead of eager `reload` because, in
      # many use cases, the association will not be used.
      def clear_rolled_back_versions
        send(self.class.versions_association_name).reset
      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).subsequent(timestamp, true).first
        return v.reify(reify_options) if v
        self unless destroyed?
      end

      # Returns the objects (not Versions) as they were between the given times.
      # TODO: Either add support for the third argument, `_reify_options`, or
      # add a deprecation warning if someone tries to use it.
      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
        previous =
          if source_version
            source_version.previous
          else
            send(self.class.versions_association_name).last
          end
        previous.try(:reify)
      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(id)
      rescue
        nil
      end

      def paper_trail_enabled_for_model?
        self.class.paper_trail_enabled_for_model?
      end

      # Executes the given method or block without creating a new version.
      def without_versioning(method = nil)
        paper_trail_was_enabled = paper_trail_enabled_for_model?
        self.class.paper_trail_off!
        method ? method.to_proc.call(self) : yield(self)
      ensure
        self.class.paper_trail_on! if paper_trail_was_enabled
      end

      # Utility method for reifying. Anything executed inside the block will
      # appear like a new record.
      # rubocop: disable Style/Alias
      def appear_as_new_record
        instance_eval {
          alias :old_new_record? :new_record?
          alias :new_record? :present?
        }
        yield
        instance_eval { alias :new_record? :old_new_record? }
      end
      # rubocop: enable Style/Alias

      # Temporarily overwrites the value of whodunnit and then executes the
      # provided block.
      def whodunnit(value)
        raise ArgumentError, "expected to receive a block" unless block_given?
        current_whodunnit = PaperTrail.whodunnit
        PaperTrail.whodunnit = value
        yield self
      ensure
        PaperTrail.whodunnit = current_whodunnit
      end

      # Mimics the `touch` method from `ActiveRecord::Persistence`, but also
      # creates a version. A version is created regardless of options such as
      # `:on`, `:if`, or `:unless`.
      #
      # TODO: look into leveraging the `after_touch` callback from
      # `ActiveRecord` to allow the regular `touch` method to generate a version
      # as normal. May make sense to switch the `record_update` method to
      # leverage an `after_update` callback anyways (likely for v4.0.0)
      def touch_with_version(name = nil)
        raise ActiveRecordError, "can not touch on a new record object" unless persisted?

        attributes = timestamp_attributes_for_update_in_model
        attributes << name if name
        current_time = current_time_from_proper_timezone

        attributes.each { |column| write_attribute(column, current_time) }

        record_update(true) unless will_record_after_update?
        save!(validate: false)
      end

      private

      # Returns true if `save` will cause `record_update`
      # to be called via the `after_update` callback.
      def will_record_after_update?
        on = paper_trail_options[:on]
        on.nil? || on.include?(:update)
      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 respond_to?(:updated_at)
            data[PaperTrail.timestamp_field] = updated_at
          end
          if pt_record_object_changes? && changed_notably?
            data[:object_changes] = pt_recordable_object_changes
          end
          if self.class.paper_trail_version_class.column_names.include?("transaction_id")
            data[:transaction_id] = PaperTrail.transaction_id
          end
          version = send(self.class.versions_association_name).create! merge_metadata(data)
          update_transaction_id(version)
          save_associations(version)
        end
      end

      def record_update(force = nil)
        if paper_trail_switched_on? && (force || changed_notably?)
          data = {
            event: paper_trail_event || "update",
            object: pt_recordable_object,
            whodunnit: PaperTrail.whodunnit
          }
          if respond_to?(:updated_at)
            data[PaperTrail.timestamp_field] = updated_at
          end
          if pt_record_object_changes?
            data[:object_changes] = pt_recordable_object_changes
          end
          if self.class.paper_trail_version_class.column_names.include?("transaction_id")
            data[:transaction_id] = PaperTrail.transaction_id
          end
          version = send(self.class.versions_association_name).create merge_metadata(data)
          update_transaction_id(version)
          save_associations(version)
        end
      end

      # Returns a boolean indicating whether to store serialized version diffs
      # in the `object_changes` column of the version record.
      # @api private
      def pt_record_object_changes?
        paper_trail_options[:save_changes] &&
          self.class.paper_trail_version_class.column_names.include?("object_changes")
      end

      # Returns an object which can be assigned to the `object` attribute of a
      # nascent version record. If the `object` column is a postgres `json`
      # column, then a hash can be used in the assignment, otherwise the column
      # is a `text` column, and we must perform the serialization here, using
      # `PaperTrail.serializer`.
      # @api private
      def pt_recordable_object
        if self.class.paper_trail_version_class.object_col_is_json?
          object_attrs_for_paper_trail
        else
          PaperTrail.serializer.dump(object_attrs_for_paper_trail)
        end
      end

      # Returns an object which can be assigned to the `object_changes`
      # attribute of a nascent version record. If the `object_changes` column is
      # a postgres `json` column, then a hash can be used in the assignment,
      # otherwise the column is a `text` column, and we must perform the
      # serialization here, using `PaperTrail.serializer`.
      # @api private
      def pt_recordable_object_changes
        if self.class.paper_trail_version_class.object_changes_col_is_json?
          changes_for_paper_trail
        else
          PaperTrail.serializer.dump(changes_for_paper_trail)
        end
      end

      def changes_for_paper_trail
        notable_changes = changes.delete_if { |k, _v| !notably_changed.include?(k) }
        self.class.serialize_attribute_changes_for_paper_trail!(notable_changes)
        notable_changes.to_hash
      end

      # Invoked via`after_update` callback for when a previous version is
      # reified and then saved.
      def clear_version_instance!
        send("#{self.class.version_association_name}=", nil)
      end

      # Invoked via callback when a user attempts to persist a reified
      # `Version`.
      def reset_timestamp_attrs_for_update_if_needed!
        return if live?
        timestamp_attributes_for_update_in_model.each do |column|
          # ActiveRecord 4.2 deprecated `reset_column!` in favor of
          # `restore_column!`.
          if respond_to?("restore_#{column}!")
            send("restore_#{column}!")
          else
            send("reset_#{column}!")
          end
        end
      end

      def record_destroy
        if paper_trail_switched_on? && !new_record?
          data = {
            item_id: id,
            item_type: self.class.base_class.name,
            event: paper_trail_event || "destroy",
            object: pt_recordable_object,
            whodunnit: PaperTrail.whodunnit
          }
          if self.class.paper_trail_version_class.column_names.include?("transaction_id")
            data[:transaction_id] = PaperTrail.transaction_id
          end
          version = self.class.paper_trail_version_class.create(merge_metadata(data))
          send("#{self.class.version_association_name}=", version)
          send(self.class.versions_association_name).send :load_target
          update_transaction_id(version)
          save_associations(version)
        end
      end

      # Saves associations if the join table for `VersionAssociation` exists.
      def save_associations(version)
        return unless PaperTrail.config.track_associations?
        save_associations_belongs_to(version)
        save_associations_has_and_belongs_to_many(version)
      end

      def save_associations_belongs_to(version)
        self.class.reflect_on_all_associations(:belongs_to).each do |assoc|
          assoc_version_args = {
            version_id: version.id,
            foreign_key_name: assoc.foreign_key
          }

          if assoc.options[:polymorphic]
            associated_record = send(assoc.name) if send(assoc.foreign_type)
            if associated_record && associated_record.class.paper_trail_enabled_for_model?
              assoc_version_args[:foreign_key_id] = associated_record.id
            end
          elsif assoc.klass.paper_trail_enabled_for_model?
            assoc_version_args[:foreign_key_id] = send(assoc.foreign_key)
          end

          if assoc_version_args.key?(:foreign_key_id)
            PaperTrail::VersionAssociation.create(assoc_version_args)
          end
        end
      end

      def save_associations_has_and_belongs_to_many(version)
        # Use the :added and :removed keys to extrapolate the HABTM associations
        # to before any changes were made
        self.class.reflect_on_all_associations(:has_and_belongs_to_many).each do |a|
          next unless
            self.class.paper_trail_save_join_tables.include?(a.name) ||
                a.klass.paper_trail_enabled_for_model?
          assoc_version_args = {
            version_id: version.id,
            foreign_key_name: a.name
          }
          assoc_ids =
            send(a.name).to_a.map(&:id) +
            (@paper_trail_habtm.try(:[], a.name).try(:[], :removed) || []) -
            (@paper_trail_habtm.try(:[], a.name).try(:[], :added) || [])
          assoc_ids.each do |id|
            PaperTrail::VersionAssociation.create(assoc_version_args.merge(foreign_key_id: id))
          end
        end
      end

      def reset_transaction_id
        PaperTrail.transaction_id = nil
      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, true)
              # If it is an attribute that is changing in an existing object,
              # be sure to grab the current version.
              if has_attribute?(v) && send("#{v}_changed?".to_sym) && data[:event] != "create"
                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 attributes_before_change
        changed = changed_attributes.select { |k, _v| self.class.column_names.include?(k) }
        attributes.merge(changed)
      end

      # Returns hash of attributes (with appropriate attributes serialized),
      # ommitting attributes to be skipped.
      def object_attrs_for_paper_trail
        attrs = attributes_before_change.except(*paper_trail_options[:skip])
        self.class.serialize_attributes_for_paper_trail!(attrs)
        attrs
      end

      # Determines whether it is appropriate to generate a new version
      # instance. A timestamp-only update (e.g. only `updated_at` changed) is
      # considered notable unless an ignored attribute was also changed.
      def changed_notably?
        if ignored_attr_has_changed?
          timestamps = timestamp_attributes_for_update_in_model.map(&:to_s)
          (notably_changed - timestamps).any?
        else
          notably_changed.any?
        end
      end

      # An attributed is "ignored" if it is listed in the `:ignore` option
      # and/or the `:skip` option.  Returns true if an ignored attribute has
      # changed.
      def ignored_attr_has_changed?
        ignored = paper_trail_options[:ignore] + paper_trail_options[:skip]
        ignored.any? && (changed & ignored).any?
      end

      def notably_changed
        only = paper_trail_options[:only].dup
        # Remove Hash arguments and then evaluate whether the attributes (the
        # keys of the hash) should also get pushed into the collection.
        only.delete_if do |obj|
          obj.is_a?(Hash) &&
            obj.each { |attr, condition|
              only << attr if condition.respond_to?(:call) && condition.call(self)
            }
        end
        only.empty? ? changed_and_not_ignored : (changed_and_not_ignored & only)
      end

      def changed_and_not_ignored
        ignore = paper_trail_options[:ignore].dup
        # Remove Hash arguments and then evaluate whether the attributes (the
        # keys of the hash) should also get pushed into the collection.
        ignore.delete_if do |obj|
          obj.is_a?(Hash) &&
            obj.each { |attr, condition|
              ignore << attr if condition.respond_to?(:call) && condition.call(self)
            }
        end
        skip = paper_trail_options[:skip]
        changed - ignore - skip
      end

      def paper_trail_switched_on?
        PaperTrail.enabled? &&
          PaperTrail.enabled_for_controller? &&
          paper_trail_enabled_for_model?
      end

      def save_version?
        if_condition = paper_trail_options[:if]
        unless_condition = paper_trail_options[:unless]
        (if_condition.blank? || if_condition.call(self)) && !unless_condition.try(:call, self)
      end

      # @api private
      def update_transaction_id(version)
        return unless self.class.paper_trail_version_class.column_names.include?("transaction_id")
        if PaperTrail.transaction? && PaperTrail.transaction_id.nil?
          PaperTrail.transaction_id = version.id
          version.transaction_id = version.id
          version.save
        end
      end
    end
  end
end