paper_trail 11.1.0 → 12.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c312ab701b8ab7b26df37957b03b9f01b6ce6cbe0e5e25d4c478258f5bec1d6f
-  data.tar.gz: 62e94f6c2fa657d4c24f0fe6ecdf5abf3c8ae785e7b25f88611fc18e6d4324a7
+  metadata.gz: e0f6ef6591b15081a76d93a70d959527f8cdc53cc3a6343ab6f1b7c40ef6695e
+  data.tar.gz: 202ee3126567ab99b39f8c76039fb7e20a4eb5e10e0e0880e867f19f228ace63
 SHA512:
-  metadata.gz: b59d91302dde736a2476240eadb9306938db2521594cf55de792c9678324762c4a1ffedfa5a53c3fc0fd9e37a87bc1b6ea4e74e68535b80fe70342d48a221532
-  data.tar.gz: b4aba2c107556fd6fbf758d9373f147c9b9bb0d1e6059bb3e2ad28b77906e980c559bd3c888fe9734665182cbe294bf470e77527a5536e202b8f32a5b7993516
+  metadata.gz: c144126a2d8cec5537ef218b6637ee2ff6e6863de2e935facf6ad020dba6c2fb46bc5c13ed2ab674e9230c264d6e87905415ebc3c1e4bee5fbe50b1e73285663
+  data.tar.gz: 96530aebe8af35a95d47b6a5deadd3797b2d9255b28156f24a9f1be67fe629b254747d39ccad4d8f5d348d9fd74300b4b865ff9b32125c0951b14cf5d13ed60f

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

@@ -20,6 +20,12 @@ module PaperTrail
       default: false,
       desc: "Store changeset (diff) with each version"
     )
+    class_option(
+      :uuid,
+      type: :boolean,
+      default: false,
+      desc: "Use uuid instead of bigint for item_id type (use only if tables use UUIDs)"
+    )
 
     desc "Generates (but does not run) a migration to add a versions table." \
          "  See section 5.c. Generators in README.md for more information."
@@ -28,7 +34,8 @@ module PaperTrail
       add_paper_trail_migration(
         "create_versions",
         item_type_options: item_type_options,
-        versions_table_options: versions_table_options
+        versions_table_options: versions_table_options,
+        item_id_type_options: item_id_type_options
       )
       if options.with_changes?
         add_paper_trail_migration("add_object_changes_to_versions")
@@ -37,12 +44,19 @@ module PaperTrail
 
     private
 
+    # To use uuid instead of integer for primary key
+    def item_id_type_options
+      options.uuid? ? "string" : "bigint"
+    end
+
     # 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 +80,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

@@ -11,7 +11,7 @@ class CreateVersions < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :versions<%= versions_table_options %> do |t|
       t.string   :item_type<%= item_type_options %>
-      t.bigint   :item_id,   null: false
+      t.<%= item_id_type_options %>   :item_id,   null: false
       t.string   :event,     null: false
       t.string   :whodunnit
       t.text     :object, limit: TEXT_BYTES
@@ -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.2" # 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,35 @@ 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
 
+      # If it is a touch event, and changed are empty, it is assumed to be
+      # implicit `touch` mutation, and will a version is created.
+      #
+      # See https://github.com/rails/rails/commit/dcb825902d79d0f6baba956f7c6ec5767611353e
+      #
+      # @api private
+      def changed_notably?
+        if @is_touch && changes_in_latest_version.empty?
+          true
+        else
+          super
+        end
+      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"