paper_trail 1.4.0 → 17.0.0

data/lib/paper_trail/frameworks/rails/controller.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Rails
+    # Extensions to rails controllers. Provides convenient ways to pass certain
+    # information to the model layer, with `controller_info` and `whodunnit`.
+    # Also includes a convenient on/off switch,
+    # `paper_trail_enabled_for_controller`.
+    module Controller
+      def self.included(controller)
+        controller.before_action(
+          :set_paper_trail_enabled_for_controller,
+          :set_paper_trail_controller_info
+        )
+      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.
+      #
+      # @api public
+      def user_for_paper_trail
+        return unless defined?(current_user)
+        current_user.try(:id) || current_user
+      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.
+      #
+      # @api public
+      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
+      #   # Don't omit `super` without a good reason.
+      #   super && request.user_agent != 'Disable User-Agent'
+      # end
+      # ```
+      #
+      # @api public
+      def paper_trail_enabled_for_controller
+        ::PaperTrail.enabled?
+      end
+
+      private
+
+      # Tells PaperTrail whether versions should be saved in the current
+      # request.
+      #
+      # @api public
+      def set_paper_trail_enabled_for_controller
+        ::PaperTrail.request.enabled = paper_trail_enabled_for_controller
+      end
+
+      # Tells PaperTrail who is responsible for any changes that occur.
+      #
+      # @api public
+      def set_paper_trail_whodunnit
+        if ::PaperTrail.request.enabled?
+          ::PaperTrail.request.whodunnit = user_for_paper_trail
+        end
+      end
+
+      # Tells PaperTrail any information from the controller you want to store
+      # alongside any changes that occur.
+      #
+      # @api public
+      def set_paper_trail_controller_info
+        if ::PaperTrail.request.enabled?
+          ::PaperTrail.request.controller_info = info_for_paper_trail
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/frameworks/rails/railtie.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  # Represents code to load within Rails framework. See documentation in
+  # `railties/lib/rails/railtie.rb`.
+  # @api private
+  class Railtie < ::Rails::Railtie
+    # PaperTrail only has one initializer.
+    #
+    # We specify `before: "load_config_initializers"` to ensure that the PT
+    # initializer happens before "app initializers" (those defined in
+    # the app's `config/initalizers`).
+    initializer "paper_trail", before: "load_config_initializers" do |app|
+      # `on_load` is a "lazy load hook". It "declares a block that will be
+      # executed when a Rails component is fully loaded". (See
+      # `active_support/lazy_load_hooks.rb`)
+      ActiveSupport.on_load(:action_controller) do
+        require "paper_trail/frameworks/rails/controller"
+
+        # Mix our extensions into `ActionController::Base`, which is `self`
+        # because of the `class_eval` in `lazy_load_hooks.rb`.
+        include PaperTrail::Rails::Controller
+      end
+
+      ActiveSupport.on_load(:active_record) do
+        require "paper_trail/frameworks/active_record"
+      end
+
+      if Gem::Version.new(::Rails::VERSION::STRING) >= Gem::Version.new("7.1")
+        app.deprecators[:paper_trail] = PaperTrail.deprecator
+      end
+    end
+  end
+end

data/lib/paper_trail/frameworks/rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "paper_trail/frameworks/rails/railtie"

data/lib/paper_trail/frameworks/rspec/helpers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module RSpec
+    module Helpers
+      # Included in the RSpec configuration in `frameworks/rspec.rb`
+      module InstanceMethods
+        # enable versioning for specific blocks (at instance-level)
+        def with_versioning
+          was_enabled = ::PaperTrail.enabled?
+          ::PaperTrail.enabled = true
+          yield
+        ensure
+          ::PaperTrail.enabled = was_enabled
+        end
+      end
+
+      # Extended by the RSpec configuration in `frameworks/rspec.rb`
+      module ClassMethods
+        # enable versioning for specific blocks (at class-level)
+        def with_versioning(&block)
+          context "with versioning", versioning: true do
+            class_exec(&block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/frameworks/rspec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require "rspec/matchers"
+require "paper_trail/frameworks/rspec/helpers"
+
+RSpec.configure do |config|
+  config.include PaperTrail::RSpec::Helpers::InstanceMethods
+  config.extend PaperTrail::RSpec::Helpers::ClassMethods
+
+  config.before(:each) do
+    PaperTrail.enabled = false
+    PaperTrail.request.enabled = true
+    PaperTrail.request.whodunnit = nil
+    PaperTrail.request.controller_info = {} if defined?(Rails) && defined?(RSpec::Rails)
+  end
+
+  config.before(:each, versioning: true) do
+    PaperTrail.enabled = true
+  end
+end
+
+RSpec::Matchers.define :be_versioned do
+  # check to see if the model has `has_paper_trail` declared on it
+  match { |actual| actual.is_a?(PaperTrail::Model::InstanceMethods) }
+end
+
+RSpec::Matchers.define :have_a_version_with do |attributes|
+  # check if the model has a version with the specified attributes
+  match do |actual|
+    versions_association = actual.class.versions_association_name
+    actual.send(versions_association).where_object(attributes).any?
+  end
+end
+
+RSpec::Matchers.define :have_a_version_with_changes do |attributes|
+  # check if the model has a version changes with the specified attributes
+  match do |actual|
+    versions_association = actual.class.versions_association_name
+    actual.send(versions_association).where_object_changes(attributes).any?
+  end
+end

data/lib/paper_trail/has_paper_trail.rb

@@ -1,95 +1,92 @@
-module PaperTrail
-
-  def self.included(base)
-    base.send :extend, ClassMethods
-  end
-
-
-  module ClassMethods
-    # Options:
-    # :ignore    an array of attributes for which a new +Version+ will not be created if only they change.
-    # :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).
-    def has_paper_trail(options = {})
-      send :include, InstanceMethods
-
-      cattr_accessor :ignore
-      self.ignore = (options[:ignore] || []).map &:to_s
-
-      cattr_accessor :meta
-      self.meta = options[:meta] || {}
-      
-      cattr_accessor :paper_trail_active
-      self.paper_trail_active = true
-
-      has_many :versions, :as => :item, :order => 'created_at ASC, id ASC'
-
-      after_create  :record_create
-      before_update :record_update
-      after_destroy :record_destroy
-    end
-
-    def paper_trail_off
-      self.paper_trail_active = false
-    end
-
-    def paper_trail_on
-      self.paper_trail_active = true
-    end
-  end
-
+# frozen_string_literal: true
 
-  module InstanceMethods
-    def record_create
-      if self.class.paper_trail_active
-        versions.create merge_metadata(:event => 'create', :whodunnit => PaperTrail.whodunnit)
-      end
-    end
+require "paper_trail/attribute_serializers/object_attribute"
+require "paper_trail/attribute_serializers/object_changes_attribute"
+require "paper_trail/model_config"
+require "paper_trail/record_trail"
 
-    def record_update
-      if changed_and_we_care? and self.class.paper_trail_active
-        versions.build merge_metadata(:event     => 'update',
-                                      :object    => object_to_string(previous_version),
-                                      :whodunnit => PaperTrail.whodunnit)
-      end
+module PaperTrail
+  # Extensions to `ActiveRecord::Base`.  See `frameworks/active_record.rb`.
+  # It is our goal to have the smallest possible footprint here, because
+  # `ActiveRecord::Base` is a very crowded namespace! That is why we introduced
+  # `.paper_trail` and `#paper_trail`.
+  module Model
+    def self.included(base)
+      base.extend ClassMethods
     end
 
-    def record_destroy
-      if self.class.paper_trail_active
-        versions.create merge_metadata(:event     => 'destroy',
-                                       :object    => object_to_string(previous_version),
-                                       :whodunnit => PaperTrail.whodunnit)
+    # :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` and `:touch` as desired.
+      # - :class_name (deprecated) - The name of a custom Version class that
+      #   includes `PaperTrail::VersionConcern`.
+      # - :ignore - An array of attributes for which a new `Version` will not be
+      #   created if only they change. It can also accept 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 accept 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 - Either,
+      #   - A String (deprecated) - The name to use for the versions
+      #     association.  Default is `:versions`.
+      #   - A Hash - options passed to `has_many`, plus `name:` and `scope:`.
+      # - :version - The name to use for the method which returns the version
+      #   the instance was reified from. Default is `:version`.
+      # - :synchronize_version_creation_timestamp - By default, paper trail
+      #   sets the `created_at` field for a new Version equal to the `updated_at`
+      #   column of the model being updated. If you instead want `created_at` to
+      #   populate with the current timestamp, set this option to `false`.
+      #
+      # Plugins like the experimental `paper_trail-association_tracking` gem
+      # may accept additional options.
+      #
+      # You can define a default set of options via the configurable
+      # `PaperTrail.config.has_paper_trail_defaults` hash in your applications
+      # initializer. The hash can contain any of the following options and will
+      # provide an overridable default for all models.
+      #
+      # @api public
+      def has_paper_trail(options = {})
+        raise Error, "has_paper_trail must be called only once" if self < InstanceMethods
+
+        defaults = PaperTrail.config.has_paper_trail_defaults
+        paper_trail.setup(defaults.merge(options))
       end
-    end
 
-    private
-
-    def merge_metadata(data)
-      meta.each do |k,v|
-        data[k] = v.respond_to?(:call) ? v.call(self) : v
+      # @api public
+      def paper_trail
+        ::PaperTrail::ModelConfig.new(self)
       end
-      data
     end
 
-    def previous_version
-      previous = self.clone
-      previous.id = id
-      changes.each do |attr, ary|
-        previous.send "#{attr}=", ary.first
+    # Wrap the following methods in a module so we can include them only in the
+    # ActiveRecord models that declare `has_paper_trail`.
+    module InstanceMethods
+      # @api public
+      def paper_trail
+        ::PaperTrail::RecordTrail.new(self)
       end
-      previous
-    end
-
-    def object_to_string(object)
-      object.attributes.to_yaml
-    end
-
-    def changed_and_we_care?
-      changed? and !(changed - self.class.ignore).empty?
     end
   end
-
 end
-
-ActiveRecord::Base.send :include, PaperTrail

data/lib/paper_trail/model_config.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  # Configures an ActiveRecord model, mostly at application boot time, but also
+  # sometimes mid-request, with methods like enable/disable.
+  class ModelConfig
+    E_CANNOT_RECORD_AFTER_DESTROY = <<~STR
+      paper_trail.on_destroy(:after) is incompatible with ActiveRecord's
+      belongs_to_required_by_default. Use on_destroy(:before)
+      or disable belongs_to_required_by_default.
+    STR
+    E_HPT_ABSTRACT_CLASS = <<~STR.squish.freeze
+      An application model (%s) has been configured to use PaperTrail (via
+      `has_paper_trail`), but the version model it has been told to use (%s) is
+      an `abstract_class`. This could happen when an advanced feature called
+      Custom Version Classes (http://bit.ly/2G4ch0G) is misconfigured. When all
+      version classes are custom, PaperTrail::Version is configured to be an
+      `abstract_class`. This is fine, but all application models must be
+      configured to use concrete (not abstract) version models.
+    STR
+    DPR_PASSING_ASSOC_NAME_DIRECTLY_TO_VERSIONS_OPTION = <<~STR.squish
+      Passing versions association name as `has_paper_trail versions: %{versions_name}`
+      is deprecated. Use `has_paper_trail versions: {name: %{versions_name}}` instead.
+      The hash you pass to `versions:` is now passed directly to `has_many`.
+    STR
+    DPR_CLASS_NAME_OPTION = <<~STR.squish
+      Passing Version class name as `has_paper_trail class_name: %{class_name}`
+      is deprecated. Use `has_paper_trail versions: {class_name: %{class_name}}`
+      instead. The hash you pass to `versions:` is now passed directly to `has_many`.
+    STR
+
+    def initialize(model_class)
+      @model_class = model_class
+    end
+
+    # Adds a callback that records a version after a "create" event.
+    #
+    # @api public
+    def on_create
+      @model_class.after_create { |r|
+        r.paper_trail.record_create if r.paper_trail.save_version?
+      }
+      append_option_uniquely(:on, :create)
+    end
+
+    # Adds a callback that records a version before or after a "destroy" event.
+    #
+    # @api public
+    def on_destroy(recording_order = "before")
+      assert_valid_recording_order_for_on_destroy(recording_order)
+      @model_class.send(
+        :"#{recording_order}_destroy",
+        lambda do |r|
+          return unless r.paper_trail.save_version?
+          r.paper_trail.record_destroy(recording_order)
+        end
+      )
+      append_option_uniquely(:on, :destroy)
+    end
+
+    # Adds a callback that records a version after an "update" event.
+    #
+    # @api public
+    def on_update
+      @model_class.before_save { |r|
+        r.paper_trail.reset_timestamp_attrs_for_update_if_needed
+      }
+      @model_class.after_update { |r|
+        if r.paper_trail.save_version?
+          r.paper_trail.record_update(
+            force: false,
+            in_after_callback: true,
+            is_touch: false
+          )
+        end
+      }
+      @model_class.after_update { |r|
+        r.paper_trail.clear_version_instance
+      }
+      append_option_uniquely(:on, :update)
+    end
+
+    # Adds a callback that records a version after a "touch" event.
+    #
+    # Rails < 6.0 (no longer supported by PT) had a bug where dirty-tracking
+    # did not occur during a `touch`.
+    # (https://github.com/rails/rails/issues/33429) See also:
+    # https://github.com/paper-trail-gem/paper_trail/issues/1121
+    # https://github.com/paper-trail-gem/paper_trail/issues/1161
+    # https://github.com/paper-trail-gem/paper_trail/pull/1285
+    #
+    # @api public
+    def on_touch
+      @model_class.after_touch { |r|
+        if r.paper_trail.save_version?
+          r.paper_trail.record_update(
+            force: false,
+            in_after_callback: true,
+            is_touch: true
+          )
+        end
+      }
+    end
+
+    # Set up `@model_class` for PaperTrail. Installs callbacks, associations,
+    # "class attributes", instance methods, and more.
+    # @api private
+    def setup(options = {})
+      options[:on] ||= %i[create update destroy touch]
+      options[:on] = Array(options[:on]) # Support single symbol
+      @model_class.send :include, ::PaperTrail::Model::InstanceMethods
+      setup_options(options)
+      setup_associations(options)
+      @model_class.after_rollback { paper_trail.clear_rolled_back_versions }
+      setup_callbacks_from_options options[:on]
+    end
+
+    # @api private
+    def version_class
+      @version_class ||= @model_class.version_class_name.constantize
+    end
+
+    private
+
+    # @api private
+    def append_option_uniquely(option, value)
+      collection = @model_class.paper_trail_options.fetch(option)
+      return if collection.include?(value)
+      collection << value
+    end
+
+    # Raises an error if the provided class is an `abstract_class`.
+    # @api private
+    def assert_concrete_activerecord_class(class_name)
+      if class_name.constantize.abstract_class?
+        raise Error, format(E_HPT_ABSTRACT_CLASS, @model_class, class_name)
+      end
+    end
+
+    # @api private
+    def assert_valid_recording_order_for_on_destroy(recording_order)
+      unless %w[after before].include?(recording_order.to_s)
+        raise ArgumentError, 'recording order can only be "after" or "before"'
+      end
+
+      if recording_order.to_s == "after" && cannot_record_after_destroy?
+        raise Error, E_CANNOT_RECORD_AFTER_DESTROY
+      end
+    end
+
+    def cannot_record_after_destroy?
+      ::ActiveRecord::Base.belongs_to_required_by_default
+    end
+
+    def check_version_class_name(options)
+      # @api private - `version_class_name`
+      @model_class.class_attribute :version_class_name
+      if options[:class_name]
+        PaperTrail.deprecator.warn(
+          format(
+            DPR_CLASS_NAME_OPTION,
+            class_name: options[:class_name].inspect
+          ),
+          caller(1)
+        )
+        options[:versions][:class_name] = options[:class_name]
+      end
+      @model_class.version_class_name = options[:versions][:class_name] || "PaperTrail::Version"
+      assert_concrete_activerecord_class(@model_class.version_class_name)
+    end
+
+    def check_versions_association_name(options)
+      # @api private - versions_association_name
+      @model_class.class_attribute :versions_association_name
+      @model_class.versions_association_name = options[:versions][:name] || :versions
+    end
+
+    def define_has_many_versions(options)
+      options = ensure_versions_option_is_hash(options)
+      check_version_class_name(options)
+      check_versions_association_name(options)
+      scope = get_versions_scope(options)
+      @model_class.has_many(
+        @model_class.versions_association_name,
+        scope,
+        class_name: @model_class.version_class_name,
+        as: :item,
+        **options[:versions].except(:name, :scope)
+      )
+    end
+
+    def ensure_versions_option_is_hash(options)
+      unless options[:versions].is_a?(Hash)
+        if options[:versions]
+          PaperTrail.deprecator.warn(
+            format(
+              DPR_PASSING_ASSOC_NAME_DIRECTLY_TO_VERSIONS_OPTION,
+              versions_name: options[:versions].inspect
+            ),
+            caller(1)
+          )
+        end
+        options[:versions] = {
+          name: options[:versions]
+        }
+      end
+      options
+    end
+
+    # Process an `ignore`, `skip`, or `only` option.
+    def event_attribute_option(option_name)
+      [@model_class.paper_trail_options[option_name]].
+        flatten.
+        compact.
+        map { |attr| attr.is_a?(Hash) ? attr.stringify_keys : attr.to_s }
+    end
+
+    def get_versions_scope(options)
+      options[:versions][:scope] || -> { order(model.timestamp_sort_order) }
+    end
+
+    def setup_associations(options)
+      # @api private - version_association_name
+      @model_class.class_attribute :version_association_name
+      @model_class.version_association_name = options[:version] || :version
+
+      # The version this instance was reified from.
+      # @api public
+      @model_class.send :attr_accessor, @model_class.version_association_name
+
+      # @api public - paper_trail_event
+      @model_class.send :attr_accessor, :paper_trail_event
+
+      define_has_many_versions(options)
+    end
+
+    def setup_callbacks_from_options(options_on = [])
+      options_on.each do |event|
+        public_send(:"on_#{event}")
+      end
+    end
+
+    def setup_options(options)
+      # @api public - paper_trail_options - Let's encourage plugins to use eg.
+      # `paper_trail_options[:versions][:class_name]` rather than
+      # `version_class_name` because the former is documented and the latter is
+      # not.
+      @model_class.class_attribute :paper_trail_options
+      @model_class.paper_trail_options = options.dup
+
+      %i[ignore skip only].each do |k|
+        @model_class.paper_trail_options[k] = event_attribute_option(k)
+      end
+      @model_class.paper_trail_options[:meta] ||= {}
+    end
+  end
+end