paper_trail 11.0.0 → 12.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8f7237a39b0645932b394ee0332846be680f6a725ed02c7a126aa892d840ccc
-  data.tar.gz: b0356d622a6e6f3ba0938c4d9fe0ff211b347a0c65e2d3a6574bc8bf5fb04df6
+  metadata.gz: d64732632c8d2b579619cb3e4ec4f754a3bd82310f464aa715d79709fc0ba58d
+  data.tar.gz: 245ca1378370715e907ef2c7c9eaad6375a77aef0306729e98c2a046d4cb7c89
 SHA512:
-  metadata.gz: 46ad3d73231d4ab6c3d978925e7b838af2697b2b998b9a7948d078266fbdbec33b6dbdcbfb93751f2aa961be6a3499f499a71d56e3fbc6138174cb752feae41a
-  data.tar.gz: 9ec2fc044229898aa2c5ab70dc41b549b6896c61af42633af0760e6b99aadd375f5f7e39160ad713131ecb439b0f5aff8cb6696f276f4c5225eb40e371f43035
+  metadata.gz: 85ff44a62d2ca043e38805e510ac7bea9b5b2faba00e3e75b79262404b422730a2810e0e95adc0a30e867dd8d20fa21eb63d0b329908934272a591a14df0ce03
+  data.tar.gz: 8454773dd1a683fed0f79f6464a4d2f9944c399b81e4ce3ec205720a27db17ee4daade6793cddf5fe63e8422c3f6564893721ad02bef6abbd42d8e6e8a881b08

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Andy Stewart, AirBlade Software Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/generators/paper_trail/install/install_generator.rb

@@ -40,9 +40,11 @@ module PaperTrail
     # MySQL 5.6 utf8mb4 limit is 191 chars for keys used in indexes.
     # See https://github.com/paper-trail-gem/paper_trail/issues/651
     def item_type_options
-      opt = { null: false }
-      opt[:limit] = 191 if mysql?
-      ", #{opt}"
+      if mysql?
+        ", { null: false, limit: 191 }"
+      else
+        ", { null: false }"
+      end
     end
 
     def mysql?
@@ -66,7 +68,7 @@ module PaperTrail
     #
     def versions_table_options
       if mysql?
-        ', { options: "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci" }'
+        ', options: "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci"'
       else
         ""
       end

data/lib/generators/paper_trail/install/templates/create_versions.rb.erb

@@ -28,7 +28,9 @@ class CreateVersions < ActiveRecord::Migration<%= migration_version %>
       # MySQL users should also upgrade to at least rails 4.2, which is the first
       # version of ActiveRecord with support for fractional seconds in MySQL.
       # (https://github.com/rails/rails/pull/14359)
-      #
+      # 
+      # MySQL users should use the following line for `created_at`
+      # t.datetime :created_at, limit: 6                                        
       t.datetime :created_at
     end
     add_index :versions, %i(item_type item_id)

data/lib/generators/paper_trail/update_item_subtype/update_item_subtype_generator.rb

@@ -7,8 +7,10 @@ module PaperTrail
   class UpdateItemSubtypeGenerator < MigrationGenerator
     source_root File.expand_path("templates", __dir__)
 
-    desc "Generates (but does not run) a migration to update item_subtype for STI entries in an "\
-      "existing versions table."
+    desc(
+      "Generates (but does not run) a migration to update item_subtype for "\
+      "STI entries in an existing versions table."
+    )
 
     def create_migration_file
       add_paper_trail_migration("update_versions_for_item_subtype", sti_type_options: options)

data/lib/paper_trail/attribute_serializers/attribute_serializer_factory.rb

@@ -8,18 +8,32 @@ module PaperTrail
     # not suited for writing JSON to a text column. This factory
     # replaces certain default Active Record serializers
     # with custom PaperTrail ones.
+    #
+    # @api private
     module AttributeSerializerFactory
-      AR_PG_ARRAY_CLASS = "ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array"
+      class << self
+        # @api private
+        def for(klass, attr)
+          active_record_serializer = klass.type_for_attribute(attr)
+          if ar_pg_array?(active_record_serializer)
+            TypeSerializers::PostgresArraySerializer.new(
+              active_record_serializer.subtype,
+              active_record_serializer.delimiter
+            )
+          else
+            active_record_serializer
+          end
+        end
+
+        private
 
-      def self.for(klass, attr)
-        active_record_serializer = klass.type_for_attribute(attr)
-        if active_record_serializer.class.name == AR_PG_ARRAY_CLASS
-          TypeSerializers::PostgresArraySerializer.new(
-            active_record_serializer.subtype,
-            active_record_serializer.delimiter
-          )
-        else
-          active_record_serializer
+        # @api private
+        def ar_pg_array?(obj)
+          if defined?(::ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array)
+            obj.instance_of?(::ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array)
+          else
+            false
+          end
         end
       end
     end

data/lib/paper_trail/attribute_serializers/cast_attribute_serializer.rb

@@ -8,9 +8,6 @@ module PaperTrail
     # The `CastAttributeSerializer` (de)serializes model attribute values. For
     # example, the string "1.99" serializes into the integer `1` when assigned
     # to an attribute of type `ActiveRecord::Type::Integer`.
-    #
-    # This implementation depends on the `type_for_attribute` method, which was
-    # introduced in rails 4.2. As of PT 8, we no longer support rails < 4.2.
     class CastAttributeSerializer
       def initialize(klass)
         @klass = klass
@@ -30,22 +27,25 @@ module PaperTrail
       def defined_enums
         @defined_enums ||= (@klass.respond_to?(:defined_enums) ? @klass.defined_enums : {})
       end
-    end
-
-    # Uses AR 5's `serialize` and `deserialize`.
-    class CastAttributeSerializer
-      def serialize(attr, val)
-        AttributeSerializerFactory.for(@klass, attr).serialize(val)
-      end
 
       def deserialize(attr, val)
         if defined_enums[attr] && val.is_a?(::String)
           # Because PT 4 used to save the string version of enums to `object_changes`
           val
+        elsif PaperTrail::RAILS_GTE_7_0 && val.is_a?(ActiveRecord::Type::Time::Value)
+          # Because Rails 7 time attribute throws a delegation error when you deserialize
+          # it with the factory.
+          # See ActiveRecord::Type::Time::Value crashes when loaded from YAML on rails 7.0
+          # https://github.com/rails/rails/issues/43966
+          val.instance_variable_get(:@time)
         else
           AttributeSerializerFactory.for(@klass, attr).deserialize(val)
         end
       end
+
+      def serialize(attr, val)
+        AttributeSerializerFactory.for(@klass, attr).serialize(val)
+      end
     end
   end
 end

data/lib/paper_trail/compatibility.rb

@@ -8,7 +8,7 @@ module PaperTrail
   #
   # It is not safe to assume that a new version of rails will be compatible with
   # PaperTrail. PT is only compatible with the versions of rails that it is
-  # tested against. See `.travis.yml`.
+  # tested against. See `.github/workflows/test.yml`.
   #
   # However, as of
   # [#1213](https://github.com/paper-trail-gem/paper_trail/pull/1213) our
@@ -18,7 +18,7 @@ module PaperTrail
   # versions.
   module Compatibility
     ACTIVERECORD_GTE = ">= 5.2" # enforced in gemspec
-    ACTIVERECORD_LT = "< 6.1" # not enforced in gemspec
+    ACTIVERECORD_LT = "< 7.1" # not enforced in gemspec
 
     E_INCOMPATIBLE_AR = <<-EOS
       PaperTrail %s is not compatible with ActiveRecord %s. We allow PT

data/lib/paper_trail/errors.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PaperTrail
+  # Generic PaperTrail exception.
+  # @api public
+  class Error < StandardError
+  end
+
+  # An unexpected option, perhaps a typo, was passed to a public API method.
+  # @api public
+  class InvalidOption < Error
+  end
+
+  # The application's database schema is not supported.
+  # @api public
+  class UnsupportedSchema < Error
+  end
+
+  # The application's database column type is not supported.
+  # @api public
+  class UnsupportedColumnType < UnsupportedSchema
+    def initialize(method:, expected:, actual:)
+      super(
+        format(
+          "%s expected %s column, got %s",
+          method,
+          expected,
+          actual
+        )
+      )
+    end
+  end
+end

data/lib/paper_trail/events/base.rb

@@ -22,8 +22,6 @@ module PaperTrail
     #
     # @api private
     class Base
-      RAILS_GTE_5_1 = ::ActiveRecord.gem_version >= ::Gem::Version.new("5.1.0.beta1")
-
       # @api private
       def initialize(record, in_after_callback)
         @record = record
@@ -51,7 +49,7 @@ module PaperTrail
       #
       # @api private
       def attribute_changed_in_latest_version?(attr_name)
-        if @in_after_callback && RAILS_GTE_5_1
+        if @in_after_callback
           @record.saved_change_to_attribute?(attr_name.to_s)
         else
           @record.attribute_changed?(attr_name.to_s)
@@ -60,30 +58,14 @@ module PaperTrail
 
       # @api private
       def nonskipped_attributes_before_change(is_touch)
-        cache_changed_attributes do
-          record_attributes = @record.attributes.except(*@record.paper_trail_options[:skip])
-
-          record_attributes.each_key do |k|
-            if @record.class.column_names.include?(k)
-              record_attributes[k] = attribute_in_previous_version(k, is_touch)
-            end
+        record_attributes = @record.attributes.except(*@record.paper_trail_options[:skip])
+        record_attributes.each_key do |k|
+          if @record.class.column_names.include?(k)
+            record_attributes[k] = attribute_in_previous_version(k, is_touch)
           end
         end
       end
 
-      # Rails 5.1 changed the API of `ActiveRecord::Dirty`.
-      # @api private
-      def cache_changed_attributes(&block)
-        if RAILS_GTE_5_1
-          # Everything works fine as it is
-          yield
-        else
-          # Any particular call to `changed_attributes` produces the huge memory allocation.
-          # Lets use the generic AR workaround for that.
-          @record.send(:cache_changed_attributes, &block)
-        end
-      end
-
       # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
       # https://github.com/paper-trail-gem/paper_trail/pull/899
       #
@@ -91,18 +73,14 @@ module PaperTrail
       #
       # @api private
       def attribute_in_previous_version(attr_name, is_touch)
-        if RAILS_GTE_5_1
-          if @in_after_callback && !is_touch
-            # For most events, we want the original value of the attribute, before
-            # the last save.
-            @record.attribute_before_last_save(attr_name.to_s)
-          else
-            # We are either performing a `record_destroy` or a
-            # `record_update(is_touch: true)`.
-            @record.attribute_in_database(attr_name.to_s)
-          end
+        if @in_after_callback && !is_touch
+          # For most events, we want the original value of the attribute, before
+          # the last save.
+          @record.attribute_before_last_save(attr_name.to_s)
         else
-          @record.attribute_was(attr_name.to_s)
+          # We are either performing a `record_destroy` or a
+          # `record_update(is_touch: true)`.
+          @record.attribute_in_database(attr_name.to_s)
         end
       end
 
@@ -131,19 +109,25 @@ module PaperTrail
         @changed_in_latest_version ||= changes_in_latest_version.keys
       end
 
-      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
-      # https://github.com/paper-trail-gem/paper_trail/pull/899
+      # Memoized to reduce memory usage
       #
       # @api private
       def changes_in_latest_version
-        # Memoized to reduce memory usage
-        @changes_in_latest_version ||= begin
-          if @in_after_callback && RAILS_GTE_5_1
-            @record.saved_changes
-          else
-            @record.changes
-          end
+        @changes_in_latest_version ||= load_changes_in_latest_version
+      end
+
+      # @api private
+      def evaluate_only
+        only = @record.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(@record)
+            }
         end
+        only
       end
 
       # An attributed is "ignored" if it is listed in the `:ignore` option
@@ -156,6 +140,18 @@ module PaperTrail
         ignored.any? && (changed_in_latest_version & ignored).any?
       end
 
+      # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+      # https://github.com/paper-trail-gem/paper_trail/pull/899
+      #
+      # @api private
+      def load_changes_in_latest_version
+        if @in_after_callback
+          @record.saved_changes
+        else
+          @record.changes
+        end
+      end
+
       # PT 10 has a new optional column, `item_subtype`
       #
       # @api private
@@ -200,20 +196,28 @@ module PaperTrail
         if value.respond_to?(:call)
           value.call(@record)
         elsif value.is_a?(Symbol) && @record.respond_to?(value, true)
-          # If it is an attribute that is changing in an existing object,
-          # be sure to grab the current version.
-          if event != "create" &&
-              @record.has_attribute?(value) &&
-              attribute_changed_in_latest_version?(value)
-            attribute_in_previous_version(value, false)
-          else
-            @record.send(value)
-          end
+          metadatum_from_model_method(event, value)
         else
           value
         end
       end
 
+      # The model method can either be an attribute or a non-attribute method.
+      #
+      # If it is an attribute that is changing in an existing object,
+      # be sure to grab the correct version.
+      #
+      # @api private
+      def metadatum_from_model_method(event, method)
+        if event != "create" &&
+            @record.has_attribute?(method) &&
+            attribute_changed_in_latest_version?(method)
+          attribute_in_previous_version(method, false)
+        else
+          @record.send(method)
+        end
+      end
+
       # @api private
       def notable_changes
         changes_in_latest_version.delete_if { |k, _v|
@@ -225,16 +229,9 @@ module PaperTrail
       def notably_changed
         # Memoized to reduce memory usage
         @notably_changed ||= begin
-          only = @record.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(@record)
-              }
-          end
-          only.empty? ? changed_and_not_ignored : (changed_and_not_ignored & only)
+          only = evaluate_only
+          cani = changed_and_not_ignored
+          only.empty? ? cani : (cani & only)
         end
       end
 
@@ -263,7 +260,7 @@ module PaperTrail
       # @api private
       # @param changes HashWithIndifferentAccess
       def recordable_object_changes(changes)
-        if PaperTrail.config.object_changes_adapter&.respond_to?(:diff)
+        if PaperTrail.config.object_changes_adapter.respond_to?(:diff)
           # We'd like to avoid the `to_hash` here, because it increases memory
           # usage, but that would be a breaking change because
           # `object_changes_adapter` expects a plain `Hash`, not a

data/lib/paper_trail/events/destroy.rb

@@ -35,7 +35,7 @@ module PaperTrail
       #
       # @override
       def changes_in_latest_version
-        @record.attributes.map { |attr, value| [attr, [value, nil]] }.to_h
+        @record.attributes.transform_values { |value| [value, nil] }
       end
     end
   end

data/lib/paper_trail/events/update.rb

@@ -35,16 +35,21 @@ module PaperTrail
         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_object_changes_into(data)
         merge_item_subtype_into(data)
         merge_metadata_into(data)
       end
 
       private
 
+      # @api private
+      def merge_object_changes_into(data)
+        if record_object_changes?
+          changes = @force_changes.nil? ? notable_changes : @force_changes
+          data[:object_changes] = prepare_object_changes(changes)
+        end
+      end
+
       # `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`.

data/lib/paper_trail/frameworks/active_record.rb

@@ -1,5 +1,12 @@
 # frozen_string_literal: true
 
-# This file only needs to be loaded if the gem is being used outside of Rails,
-# since otherwise the model(s) will get loaded in via the `Rails::Engine`.
+# Either ActiveRecord has already been loaded by the Lazy Load Hook in our
+# Railtie, or else we load it now.
+require "active_record"
+::PaperTrail::Compatibility.check_activerecord(::ActiveRecord.gem_version)
+
+# Now we can load the parts of PT that depend on AR.
+require "paper_trail/has_paper_trail"
+require "paper_trail/reifier"
 require "paper_trail/frameworks/active_record/models/paper_trail/version"
+ActiveRecord::Base.include PaperTrail::Model

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

@@ -101,9 +101,3 @@ module PaperTrail
     end
   end
 end
-
-if defined?(::ActionController)
-  ::ActiveSupport.on_load(:action_controller) do
-    include ::PaperTrail::Rails::Controller
-  end
-end

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

@@ -0,0 +1,30 @@
+# 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
+      # `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
+    end
+  end
+end

data/lib/paper_trail/frameworks/rails.rb

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

data/lib/paper_trail/has_paper_trail.rb

@@ -12,7 +12,7 @@ module PaperTrail
   # `.paper_trail` and `#paper_trail`.
   module Model
     def self.included(base)
-      base.send :extend, ClassMethods
+      base.extend ClassMethods
     end
 
     # :nodoc: