paper_trail 10.3.1 → 12.1.0

data/lib/paper_trail/reifier.rb

@@ -52,26 +52,29 @@ module PaperTrail
       # not the actual subclass. If `type` is present but empty, the class is
       # the base class.
       def init_model(attrs, options, version)
-        if options[:dup] != true && version.item
-          model = version.item
-          if options[:unversioned_attributes] == :nil
-            init_unversioned_attrs(attrs, model)
-          end
-        else
-          klass = version_reification_class(version, attrs)
-          # The `dup` option always returns a new object, otherwise we should
-          # attempt to look for the item outside of default scope(s).
-          find_cond = { klass.primary_key => version.item_id }
-          if options[:dup] || (item_found = klass.unscoped.where(find_cond).first).nil?
-            model = klass.new
-          elsif options[:unversioned_attributes] == :nil
-            model = item_found
-            init_unversioned_attrs(attrs, model)
-          end
+        klass = version_reification_class(version, attrs)
+
+        # The `dup` option and destroyed version always returns a new object,
+        # otherwise we should attempt to load item or to look for the item
+        # outside of default scope(s).
+        model = if options[:dup] == true || version.event == "destroy"
+                  klass.new
+                else
+                  version.item || init_model_by_finding_item_id(klass, version) || klass.new
+                end
+
+        if options[:unversioned_attributes] == :nil && !model.new_record?
+          init_unversioned_attrs(attrs, model)
         end
+
         model
       end
 
+      # @api private
+      def init_model_by_finding_item_id(klass, version)
+        klass.unscoped.where(klass.primary_key => version.item_id).first
+      end
+
       # Look for attributes that exist in `model` and not in this version.
       # These attributes should be set to nil. Modifies `attrs`.
       # @api private
@@ -88,9 +91,7 @@ module PaperTrail
       #
       # @api private
       def reify_attribute(k, v, model, version)
-        enums = model.class.respond_to?(:defined_enums) ? model.class.defined_enums : {}
-        is_enum_without_type_caster = ::ActiveRecord::VERSION::MAJOR < 5 && enums.key?(k)
-        if model.has_attribute?(k) && !is_enum_without_type_caster
+        if model.has_attribute?(k)
           model[k.to_sym] = v
         elsif model.respond_to?("#{k}=")
           model.send("#{k}=", v)
@@ -111,21 +112,35 @@ module PaperTrail
       end
 
       # Given a `version`, return the class to reify. This method supports
-      # Single Table Inheritance (STI) with custom inheritance columns.
+      # Single Table Inheritance (STI) with custom inheritance columns and
+      # custom inheritance column values.
       #
       # For example, imagine a `version` whose `item_type` is "Animal". The
       # `animals` table is an STI table (it has cats and dogs) and it has a
       # custom inheritance column, `species`. If `attrs["species"]` is "Dog",
       # this method returns the constant `Dog`. If `attrs["species"]` is blank,
-      # this method returns the constant `Animal`. You can see this particular
-      # example in action in `spec/models/animal_spec.rb`.
+      # this method returns the constant `Animal`.
+      #
+      # The values contained in the inheritance columns may be non-camelized
+      # strings (e.g. 'dog' instead of 'Dog'). To reify classes in this case
+      # we need to call the parents class `sti_class_for` method to retrieve
+      # the correct record class.
       #
-      # TODO: Duplication: similar `constantize` in VersionConcern#version_limit
+      # You can see these particular examples in action in
+      # `spec/models/animal_spec.rb` and `spec/models/plant_spec.rb`
       def version_reification_class(version, attrs)
-        inheritance_column_name = version.item_type.constantize.inheritance_column
+        clazz = version.item_type.constantize
+        inheritance_column_name = clazz.inheritance_column
         inher_col_value = attrs[inheritance_column_name]
-        class_name = inher_col_value.blank? ? version.item_type : inher_col_value
-        class_name.constantize
+        return clazz if inher_col_value.blank?
+
+        # Rails 6.1 adds a public method for clients to use to customize STI classes. If that
+        # method is not available, fall back to using the private one
+        if clazz.public_methods.include?(:sti_class_for)
+          return clazz.sti_class_for(inher_col_value)
+        end
+
+        clazz.send(:find_sti_class, inher_col_value)
       end
     end
   end

data/lib/paper_trail/request.rb

@@ -12,9 +12,6 @@ module PaperTrail
   #
   # @api private
   module Request
-    class InvalidOption < RuntimeError
-    end
-
     class << self
       # Sets any data from the controller that you want PaperTrail to store.
       # See also `PaperTrail::Rails::Controller#info_for_paper_trail`.

data/lib/paper_trail/serializers/json.rb

@@ -31,16 +31,6 @@ module PaperTrail
           arel_field.matches("%\"#{field}\":#{json_value}%")
         end
       end
-
-      def where_object_changes_condition(*)
-        raise <<-STR.squish.freeze
-          where_object_changes no longer supports reading JSON from a text
-          column. The old implementation was inaccurate, returning more records
-          than you wanted. This feature was deprecated in 7.1.0 and removed in
-          8.0.0. The json and jsonb datatypes are still supported. See the
-          discussion at https://github.com/paper-trail-gem/paper_trail/issues/803
-        STR
-      end
     end
   end
 end

data/lib/paper_trail/serializers/yaml.rb

@@ -26,18 +26,6 @@ module PaperTrail
       def where_object_condition(arel_field, field, value)
         arel_field.matches("%\n#{field}: #{value}\n%")
       end
-
-      # Returns a SQL LIKE condition to be used to match the given field and
-      # value in the serialized `object_changes`.
-      def where_object_changes_condition(*)
-        raise <<-STR.squish.freeze
-          where_object_changes no longer supports reading YAML from a text
-          column. The old implementation was inaccurate, returning more records
-          than you wanted. This feature was deprecated in 8.1.0 and removed in
-          9.0.0. The json and jsonb datatypes are still supported. See
-          discussion at https://github.com/paper-trail-gem/paper_trail/pull/997
-        STR
-      end
     end
   end
 end

data/lib/paper_trail/type_serializers/postgres_array_serializer.rb

@@ -11,15 +11,12 @@ module PaperTrail
       end
 
       def serialize(array)
-        return serialize_with_ar(array) if active_record_pre_502?
         array
       end
 
       def deserialize(array)
-        return deserialize_with_ar(array) if active_record_pre_502?
-
         case array
-        # Needed for legacy reasons. If serialized array is a string
+        # Needed for legacy data. If serialized array is a string
         # then it was serialized with Rails < 5.0.2.
         when ::String then deserialize_with_ar(array)
         else array
@@ -28,16 +25,6 @@ module PaperTrail
 
       private
 
-      def active_record_pre_502?
-        ::ActiveRecord.gem_version < Gem::Version.new("5.0.2")
-      end
-
-      def serialize_with_ar(array)
-        ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.
-          new(@subtype, @delimiter).
-          serialize(array)
-      end
-
       def deserialize_with_ar(array)
         ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array.
           new(@subtype, @delimiter).

data/lib/paper_trail/version_concern.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require "paper_trail/attribute_serializers/object_changes_attribute"
+require "paper_trail/queries/versions/where_attribute_changes"
 require "paper_trail/queries/versions/where_object"
 require "paper_trail/queries/versions/where_object_changes"
+require "paper_trail/queries/versions/where_object_changes_from"
+require "paper_trail/queries/versions/where_object_changes_to"
 
 module PaperTrail
   # Originally, PaperTrail did not provide this module, and all of this
@@ -13,22 +16,13 @@ module PaperTrail
     extend ::ActiveSupport::Concern
 
     included do
-      if ::ActiveRecord.gem_version >= Gem::Version.new("5.0")
-        belongs_to :item, polymorphic: true, optional: true
-      else
-        belongs_to :item, polymorphic: true
-      end
-
+      belongs_to :item, polymorphic: true, optional: true
       validates_presence_of :event
       after_create :enforce_version_limit!
     end
 
     # :nodoc:
     module ClassMethods
-      def item_subtype_column_present?
-        column_names.include?("item_subtype")
-      end
-
       def with_item_keys(item_type, item_id)
         where item_type: item_type, item_id: item_id
       end
@@ -46,7 +40,7 @@ module PaperTrail
       end
 
       def not_creates
-        where "event <> ?", "create"
+        where.not(event: "create")
       end
 
       def between(start_time, end_time)
@@ -64,6 +58,18 @@ module PaperTrail
         end
       end
 
+      # Given an attribute like `"name"`, query the `versions.object_changes`
+      # column for any changes that modified the provided attribute.
+      #
+      # @api public
+      def where_attribute_changes(attribute)
+        unless attribute.is_a?(String) || attribute.is_a?(Symbol)
+          raise ArgumentError, "expected to receive a String or Symbol"
+        end
+
+        Queries::Versions::WhereAttributeChanges.new(self, attribute).execute
+      end
+
       # Given a hash of attributes like `name: 'Joan'`, query the
       # `versions.objects` column.
       #
@@ -120,6 +126,36 @@ module PaperTrail
         Queries::Versions::WhereObjectChanges.new(self, args).execute
       end
 
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects_changes` column for changes where the version changed
+      # from the hash of attributes to other values.
+      #
+      # This is useful for finding versions where the attribute started with a
+      # known value and changed to something else. This is in comparison to
+      # `where_object_changes` which will find both the changes before and
+      # after.
+      #
+      # @api public
+      def where_object_changes_from(args = {})
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
+        Queries::Versions::WhereObjectChangesFrom.new(self, args).execute
+      end
+
+      # Given a hash of attributes like `name: 'Joan'`, query the
+      # `versions.objects_changes` column for changes where the version changed
+      # to the hash of attributes from other values.
+      #
+      # This is useful for finding versions where the attribute started with an
+      # unknown value and changed to a known value. This is in comparison to
+      # `where_object_changes` which will find both the changes before and
+      # after.
+      #
+      # @api public
+      def where_object_changes_to(args = {})
+        raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
+        Queries::Versions::WhereObjectChangesTo.new(self, args).execute
+      end
+
       def primary_key_is_int?
         @primary_key_is_int ||= columns_hash[primary_key].type == :integer
       rescue StandardError # TODO: Rescue something more specific
@@ -145,6 +181,7 @@ module PaperTrail
       #   Default: false.
       # @return `ActiveRecord::Relation`
       # @api public
+      # rubocop:disable Style/OptionalBooleanParameter
       def preceding(obj, timestamp_arg = false)
         if timestamp_arg != true && primary_key_is_int?
           preceding_by_id(obj)
@@ -152,6 +189,7 @@ module PaperTrail
           preceding_by_timestamp(obj)
         end
       end
+      # rubocop:enable Style/OptionalBooleanParameter
 
       # Returns versions after `obj`.
       #
@@ -160,6 +198,7 @@ module PaperTrail
       #   Default: false.
       # @return `ActiveRecord::Relation`
       # @api public
+      # rubocop:disable Style/OptionalBooleanParameter
       def subsequent(obj, timestamp_arg = false)
         if timestamp_arg != true && primary_key_is_int?
           subsequent_by_id(obj)
@@ -167,6 +206,7 @@ module PaperTrail
           subsequent_by_timestamp(obj)
         end
       end
+      # rubocop:enable Style/OptionalBooleanParameter
 
       private
 
@@ -205,18 +245,8 @@ module PaperTrail
 
     # Restore the item from this version.
     #
-    # Optionally this can also restore all :has_one and :has_many (including
-    # has_many :through) associations as they were "at the time", if they are
-    # also being versioned by PaperTrail.
-    #
     # Options:
     #
-    # - :has_one
-    #   - `true` - Also reify has_one associations.
-    #   - `false - Default.
-    # - :has_many
-    #   - `true` - Also reify has_many and has_many :through associations.
-    #   - `false` - Default.
     # - :mark_for_destruction
     #   - `true` - Mark the has_one/has_many associations that did not exist in
     #     the reified version for destruction, instead of removing them.
@@ -232,7 +262,7 @@ module PaperTrail
     #
     def reify(options = {})
       unless self.class.column_names.include? "object"
-        raise "reify can't be called without an object column"
+        raise Error, "reify requires an object column"
       end
       return nil if object.nil?
       ::PaperTrail::Reifier.reify(self, options)
@@ -258,13 +288,6 @@ module PaperTrail
     end
     alias version_author terminator
 
-    def sibling_versions(reload = false)
-      if reload || !defined?(@sibling_versions) || @sibling_versions.nil?
-        @sibling_versions = self.class.with_item_keys(item_type, item_id)
-      end
-      @sibling_versions
-    end
-
     def next
       @next ||= sibling_versions.subsequent(self).first
     end
@@ -274,8 +297,9 @@ module PaperTrail
     end
 
     # Returns an integer representing the chronological position of the
-    # version among its siblings (see `sibling_versions`). The "create" event,
-    # for example, has an index of 0.
+    # version among its siblings. The "create" event, for example, has an index
+    # of 0.
+    #
     # @api public
     def index
       @index ||= RecordHistory.new(sibling_versions, self.class).index(self)
@@ -285,7 +309,7 @@ module PaperTrail
 
     # @api private
     def load_changeset
-      if PaperTrail.config.object_changes_adapter&.respond_to?(:load_changeset)
+      if PaperTrail.config.object_changes_adapter.respond_to?(:load_changeset)
         return PaperTrail.config.object_changes_adapter.load_changeset(self)
       end
 
@@ -342,20 +366,31 @@ module PaperTrail
       excess_versions.map(&:destroy)
     end
 
+    # @api private
+    def sibling_versions
+      @sibling_versions ||= self.class.with_item_keys(item_type, item_id)
+    end
+
     # See docs section 2.e. Limiting the Number of Versions Created.
     # The version limit can be global or per-model.
     #
     # @api private
-    #
-    # TODO: Duplication: similar `constantize` in Reifier#version_reification_class
     def version_limit
-      if self.class.item_subtype_column_present?
-        klass = (item_subtype || item_type).constantize
-        if klass&.paper_trail_options&.key?(:limit)
-          return klass.paper_trail_options[:limit]
-        end
+      if limit_option?(item.class)
+        item.class.paper_trail_options[:limit]
+      elsif base_class_limit_option?(item.class)
+        item.class.base_class.paper_trail_options[:limit]
+      else
+        PaperTrail.config.version_limit
       end
-      PaperTrail.config.version_limit
+    end
+
+    def limit_option?(klass)
+      klass.respond_to?(:paper_trail_options) && klass.paper_trail_options.key?(:limit)
+    end
+
+    def base_class_limit_option?(klass)
+      klass.respond_to?(:base_class) && limit_option?(klass.base_class)
     end
   end
 end

data/lib/paper_trail/version_number.rb

@@ -7,9 +7,9 @@ module PaperTrail
   # because of this confusion, but it's not worth the breaking change.
   # People are encouraged to use `PaperTrail.gem_version` instead.
   module VERSION
-    MAJOR = 10
-    MINOR = 3
-    TINY = 1
+    MAJOR = 12
+    MINOR = 1
+    TINY = 0
 
     # Set PRE to nil unless it's a pre-release (beta, rc, etc.)
     PRE = nil

data/lib/paper_trail.rb

@@ -8,34 +8,18 @@
 # can revisit this decision.
 require "active_support/all"
 
-# AR is required for, eg. has_paper_trail.rb, so we could put this `require` in
-# all of those files, but it seems easier to troubleshoot if we just make sure
-# AR is loaded here before loading *any* of PT. See discussion of
-# performance/simplicity tradeoff for activesupport above.
-require "active_record"
-
-require "request_store"
+require "paper_trail/errors"
 require "paper_trail/cleaner"
 require "paper_trail/compatibility"
 require "paper_trail/config"
-require "paper_trail/has_paper_trail"
 require "paper_trail/record_history"
-require "paper_trail/reifier"
 require "paper_trail/request"
-require "paper_trail/version_concern"
 require "paper_trail/version_number"
 require "paper_trail/serializers/json"
-require "paper_trail/serializers/yaml"
 
 # An ActiveRecord extension that tracks changes to your models, for auditing or
 # versioning.
 module PaperTrail
-  E_RAILS_NOT_LOADED = <<-EOS.squish.freeze
-    PaperTrail has been loaded too early, before rails is loaded. This can
-    happen when another gem defines the ::Rails namespace, then PT is loaded,
-    all before rails is loaded. You may want to reorder your Gemfile, or defer
-    the loading of PT by using `require: false` and a manual require elsewhere.
-  EOS
   E_TIMESTAMP_FIELD_CONFIG = <<-EOS.squish.freeze
     PaperTrail.timestamp_field= has been removed, without replacement. It is no
     longer configurable. The timestamp column in the versions table must now be
@@ -85,7 +69,7 @@ module PaperTrail
     #
     # @api public
     def request(options = nil, &block)
-      if options.nil? && !block_given?
+      if options.nil? && !block
         Request
       else
         Request.with(options, &block)
@@ -95,7 +79,7 @@ module PaperTrail
     # Set the field which records when a version was created.
     # @api public
     def timestamp_field=(_field_name)
-      raise(E_TIMESTAMP_FIELD_CONFIG)
+      raise Error, E_TIMESTAMP_FIELD_CONFIG
     end
 
     # Set the PaperTrail serializer. This setting affects all threads.
@@ -126,27 +110,18 @@ module PaperTrail
   end
 end
 
-# We use the `on_load` "hook" instead of `ActiveRecord::Base.include` because we
-# don't want to cause all of AR to be autloaded yet. See
-# https://guides.rubyonrails.org/engines.html#what-are-on-load-hooks-questionmark
-# to learn more about `on_load`.
-ActiveSupport.on_load(:active_record) do
-  include PaperTrail::Model
-end
-
-# Require frameworks
-if defined?(::Rails)
-  # Rails module is sometimes defined by gems like rails-html-sanitizer
-  # so we check for presence of Rails.application.
-  if defined?(::Rails.application)
-    require "paper_trail/frameworks/rails"
-  else
-    ::Kernel.warn(::PaperTrail::E_RAILS_NOT_LOADED)
-  end
+# PT is built on ActiveRecord, but does not require Rails. If Rails is defined,
+# our Railtie makes sure not to load the AR-dependent parts of PT until AR is
+# ready. A typical Rails `application.rb` has:
+#
+# ```
+# require 'rails/all' # Defines `Rails`
+# Bundler.require(*Rails.groups) # require 'paper_trail' (this file)
+# ```
+#
+# Non-rails applications should take similar care to load AR before PT.
+if defined?(Rails)
+  require "paper_trail/frameworks/rails"
 else
   require "paper_trail/frameworks/active_record"
 end
-
-if defined?(::ActiveRecord)
-  ::PaperTrail::Compatibility.check_activerecord(::ActiveRecord.gem_version)
-end