mongo_trails 10.3.1

data/lib/mongo_trails/events/create.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "mongo_trails/events/base"
+
+module PaperTrail
+  module Events
+    # See docs in `Base`.
+    #
+    # @api private
+    class Create < Base
+      # Return attributes of nascent `Version` record.
+      #
+      # @api private
+      def data
+        data = {
+          item: @record,
+          event: @record.paper_trail_event || "create",
+          whodunnit: PaperTrail.request.whodunnit
+        }
+        if @record.respond_to?(:updated_at)
+          data[:created_at] = @record.updated_at
+        end
+        if record_object_changes? && changed_notably?
+          changes = notable_changes
+          data[:object_changes] = prepare_object_changes(changes)
+        end
+        merge_item_subtype_into(data)
+        merge_metadata_into(data)
+      end
+    end
+  end
+end

data/lib/mongo_trails/events/destroy.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "mongo_trails/events/base"
+
+module PaperTrail
+  module Events
+    # See docs in `Base`.
+    #
+    # @api private
+    class Destroy < Base
+      # Return attributes of nascent `Version` record.
+      #
+      # @api private
+      def data
+        data = {
+          item_id: @record.id,
+          item_type: @record.class.base_class.name,
+          event: @record.paper_trail_event || "destroy",
+          whodunnit: PaperTrail.request.whodunnit
+        }
+        if record_object?
+          data[:object] = recordable_object(false)
+        end
+        if record_object_changes?
+          data[:object_changes] = prepare_object_changes(notable_changes)
+        end
+        merge_item_subtype_into(data)
+        merge_metadata_into(data)
+      end
+
+      private
+
+      # Rails' implementation (eg. `@record.saved_changes`) returns nothing on
+      # destroy, so we have to build the hash we want.
+      #
+      # @override
+      def changes_in_latest_version
+        @record.attributes.map { |attr, value| [attr, [value, nil]] }.to_h
+      end
+    end
+  end
+end

data/lib/mongo_trails/events/update.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "mongo_trails/events/base"
+
+module PaperTrail
+  module Events
+    # See docs in `Base`.
+    #
+    # @api private
+    class Update < Base
+      # - is_touch - [boolean] - Used in the two situations that are touch-like:
+      #   - `after_touch` we call `RecordTrail#record_update`
+      # - force_changes - [Hash] - Only used by `RecordTrail#update_columns`,
+      #   because there dirty-tracking is off, so it has to track its own changes.
+      #
+      # @api private
+      def initialize(record, in_after_callback, is_touch, force_changes)
+        super(record, in_after_callback)
+        @is_touch = is_touch
+        @force_changes = force_changes
+      end
+
+      # Return attributes of nascent `Version` record.
+      #
+      # @api private
+      def data
+        data = {
+          item: @record,
+          event: @record.paper_trail_event || "update",
+          whodunnit: PaperTrail.request.whodunnit
+        }
+        if @record.respond_to?(:updated_at)
+          data[:created_at] = @record.updated_at
+        end
+        if record_object?
+          data[:object] = recordable_object(@is_touch)
+        end
+        if record_object_changes?
+          changes = @force_changes.nil? ? notable_changes : @force_changes
+          data[:object_changes] = prepare_object_changes(changes)
+        end
+        merge_item_subtype_into(data)
+        merge_metadata_into(data)
+      end
+
+      private
+
+      # `touch` cannot record `object_changes` because rails' `touch` does not
+      # perform dirty-tracking. Specifically, methods from `Dirty`, like
+      # `saved_changes`, return the same values before and after `touch`.
+      #
+      # See https://github.com/rails/rails/issues/33429
+      #
+      # @api private
+      def record_object_changes?
+        !@is_touch && super
+      end
+    end
+  end
+end

data/lib/mongo_trails/frameworks/cucumber.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# before hook for Cucumber
+Before do
+  PaperTrail.enabled = false
+  PaperTrail.request.enabled = true
+  PaperTrail.request.whodunnit = nil
+  PaperTrail.request.controller_info = {} if defined?(::Rails)
+end
+
+module PaperTrail
+  module Cucumber
+    # Helper method for enabling PT in Cucumber features.
+    module Extensions
+      # :call-seq:
+      # with_versioning
+      #
+      # enable versioning for specific blocks
+
+      def with_versioning
+        was_enabled = ::PaperTrail.enabled?
+        ::PaperTrail.enabled = true
+        begin
+          yield
+        ensure
+          ::PaperTrail.enabled = was_enabled
+        end
+      end
+    end
+  end
+end
+
+World PaperTrail::Cucumber::Extensions

data/lib/mongo_trails/frameworks/rails.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "mongo_trails/frameworks/rails/controller"
+require "mongo_trails/frameworks/rails/engine"

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

@@ -0,0 +1,109 @@
+# 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
+
+if defined?(::ActionController)
+  ::ActiveSupport.on_load(:action_controller) do
+    include ::PaperTrail::Rails::Controller
+  end
+end

data/lib/mongo_trails/frameworks/rails/engine.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  module Rails
+    # See http://guides.rubyonrails.org/engines.html
+    class Engine < ::Rails::Engine
+      DPR_CONFIG_ENABLED = <<~EOS.squish.freeze
+        The rails configuration option config.paper_trail.enabled is deprecated.
+        Please use PaperTrail.enabled= instead. People were getting confused
+        that PT has both, specifically regarding *when* each was happening. If
+        you'd like to keep config.paper_trail, join the discussion at
+        https://github.com/paper-trail-gem/mongo_trails/pull/1176
+      EOS
+      private_constant :DPR_CONFIG_ENABLED
+      DPR_RUDELY_ENABLING = <<~EOS.squish.freeze
+        At some point early in the rails boot process, you have set
+        PaperTrail.enabled = false. PT's rails engine is now overriding your
+        setting, and setting it to true. We're not sure why, but this is how PT
+        has worked since 5.0, when the config.paper_trail.enabled option was
+        introduced. This is now deprecated. In the future, PT will not override
+        your setting. See
+        https://github.com/paper-trail-gem/mongo_trails/pull/1176 for discussion.
+      EOS
+      private_constant :DPR_RUDELY_ENABLING
+
+      # --- Begin deprecated section ---
+      config.paper_trail = ActiveSupport::OrderedOptions.new
+      initializer "paper_trail.initialisation" do |app|
+        enable = app.config.paper_trail[:enabled]
+        if enable.nil?
+          unless PaperTrail.enabled?
+            ::ActiveSupport::Deprecation.warn(DPR_RUDELY_ENABLING)
+            PaperTrail.enabled = true
+          end
+        else
+          ::ActiveSupport::Deprecation.warn(DPR_CONFIG_ENABLED)
+          PaperTrail.enabled = enable
+        end
+      end
+      # --- End deprecated section ---
+    end
+  end
+end

data/lib/mongo_trails/frameworks/rspec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+require "rspec/matchers"
+require "mongo_trails/frameworks/rspec/helpers"
+
+RSpec.configure do |config|
+  config.include ::PaperTrail::RSpec::Helpers::InstanceMethods
+  config.extend ::PaperTrail::RSpec::Helpers::ClassMethods
+
+  config.before(:each) do
+    ::Mongoid.purge!
+    ::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/mongo_trails/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/mongo_trails/has_paper_trail.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "mongo_trails/attribute_serializers/object_attribute"
+require "mongo_trails/attribute_serializers/object_changes_attribute"
+require "mongo_trails/model_config"
+require "mongo_trails/record_trail"
+
+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.send :extend, ClassMethods
+    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` 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`.
+      #
+      # 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 = {})
+        defaults = PaperTrail.config.has_paper_trail_defaults
+        paper_trail.setup(defaults.merge(options))
+      end
+
+      # @api public
+      def paper_trail
+        ::PaperTrail::ModelConfig.new(self)
+      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
+      # @api public
+      def paper_trail
+        ::PaperTrail::RecordTrail.new(self)
+      end
+    end
+  end
+end