paper_trail 8.0.0 → 9.0.0

data/lib/paper_trail/frameworks/active_record.rb

@@ -1,3 +1,5 @@
+# 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`.
 require "paper_trail/frameworks/active_record/models/paper_trail/version_association"

data/lib/paper_trail/frameworks/active_record/models/paper_trail/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "paper_trail/version_concern"
 
 module PaperTrail

data/lib/paper_trail/frameworks/active_record/models/paper_trail/version_association.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "paper_trail/version_association_concern"
 
 module PaperTrail

data/lib/paper_trail/frameworks/cucumber.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 # before hook for Cucumber
 Before do
   PaperTrail.enabled = false
-  PaperTrail.enabled_for_controller = true
-  PaperTrail.whodunnit = nil
-  PaperTrail.controller_info = {} if defined? Rails
+  PaperTrail.request.enabled = true
+  PaperTrail.request.whodunnit = nil
+  PaperTrail.request.controller_info = {} if defined?(::Rails)
 end
 
 module PaperTrail

data/lib/paper_trail/frameworks/rails.rb

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

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

@@ -1,8 +1,11 @@
+# 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, `enabled_for_controller`.
+    # Also includes a convenient on/off switch,
+    # `paper_trail_enabled_for_controller`.
     module Controller
       def self.included(controller)
         controller.before_action(
@@ -18,6 +21,8 @@ module PaperTrail
       #
       # 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)
         ActiveSupport::VERSION::MAJOR >= 4 ? current_user.try!(:id) : current_user.try(:id)
@@ -43,6 +48,8 @@ module PaperTrail
       # 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
@@ -52,6 +59,15 @@ module PaperTrail
       #
       # 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
@@ -60,30 +76,29 @@ module PaperTrail
 
       # Tells PaperTrail whether versions should be saved in the current
       # request.
+      #
+      # @api public
       def set_paper_trail_enabled_for_controller
-        ::PaperTrail.enabled_for_controller = 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
-        @set_paper_trail_whodunnit_called = true
-        ::PaperTrail.whodunnit = user_for_paper_trail if ::PaperTrail.enabled_for_controller?
+        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
-        ::PaperTrail.controller_info = info_for_paper_trail if ::PaperTrail.enabled_for_controller?
-      end
-
-      # We have removed this warning. We no longer add it as a callback.
-      # However, some people use `skip_after_action :warn_about_not_setting_whodunnit`,
-      # so removing this method would be a breaking change. We can remove it
-      # in the next major version.
-      def warn_about_not_setting_whodunnit
-        ::ActiveSupport::Deprecation.warn(
-          "warn_about_not_setting_whodunnit is a no-op and is deprecated."
-        )
+        if ::PaperTrail.request.enabled?
+          ::PaperTrail.request.controller_info = info_for_paper_trail
+        end
       end
     end
   end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PaperTrail
   module Rails
     # See http://guides.rubyonrails.org/engines.html

data/lib/paper_trail/frameworks/rspec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rspec/core"
 require "rspec/matchers"
 require "paper_trail/frameworks/rspec/helpers"
@@ -8,9 +10,9 @@ RSpec.configure do |config|
 
   config.before(:each) do
     ::PaperTrail.enabled = false
-    ::PaperTrail.enabled_for_controller = true
-    ::PaperTrail.whodunnit = nil
-    ::PaperTrail.controller_info = {} if defined?(::Rails) && defined?(::RSpec::Rails)
+    ::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

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PaperTrail
   module RSpec
     module Helpers

data/lib/paper_trail/has_paper_trail.rb

@@ -1,5 +1,5 @@
-require "active_support/core_ext/object" # provides the `try` method
-require "paper_trail/attribute_serializers/legacy_active_record_shim"
+# frozen_string_literal: true
+
 require "paper_trail/attribute_serializers/object_attribute"
 require "paper_trail/attribute_serializers/object_changes_attribute"
 require "paper_trail/model_config"

data/lib/paper_trail/model_config.rb

@@ -1,35 +1,70 @@
-require "active_support/core_ext"
+# 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
+    DPR_DISABLE = <<-STR.squish.freeze
+      MyModel.paper_trail.disable is deprecated, use
+      PaperTrail.request.disable_model(MyModel). This new API makes it clear
+      that only the current request is affected, not all threads. Also, all
+      other request-variables now go through the same `request` method, so this
+      new API is more consistent.
+    STR
+    DPR_ENABLE = <<-STR.squish.freeze
+      MyModel.paper_trail.enable is deprecated, use
+      PaperTrail.request.enable_model(MyModel). This new API makes it clear
+      that only the current request is affected, not all threads. Also, all
+      other request-variables now go through the same `request` method, so this
+      new API is more consistent.
+    STR
+    DPR_ENABLED = <<-STR.squish.freeze
+      MyModel.paper_trail.enabled? is deprecated, use
+      PaperTrail.request.enabled_for_model?(MyModel). This new API makes it clear
+      that this is a setting specific to the current request, not all threads.
+      Also, all other request-variables now go through the same `request`
+      method, so this new API is more consistent.
+    STR
     E_CANNOT_RECORD_AFTER_DESTROY = <<-STR.strip_heredoc.freeze
       paper_trail.on_destroy(:after) is incompatible with ActiveRecord's
-      belongs_to_required_by_default and has no effect. Please use :before
+      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
 
     def initialize(model_class)
       @model_class = model_class
     end
 
-    # Switches PaperTrail off for this class.
+    # @deprecated
     def disable
-      ::PaperTrail.enabled_for_model(@model_class, false)
+      ::ActiveSupport::Deprecation.warn(DPR_DISABLE, caller(1))
+      ::PaperTrail.request.disable_model(@model_class)
     end
 
-    # Switches PaperTrail on for this class.
+    # @deprecated
     def enable
-      ::PaperTrail.enabled_for_model(@model_class, true)
+      ::ActiveSupport::Deprecation.warn(DPR_ENABLE, caller(1))
+      ::PaperTrail.request.enable_model(@model_class)
     end
 
+    # @deprecated
     def enabled?
-      return false unless @model_class.include?(::PaperTrail::Model::InstanceMethods)
-      ::PaperTrail.enabled_for_model?(@model_class)
+      ::ActiveSupport::Deprecation.warn(DPR_ENABLED, caller(1))
+      ::PaperTrail.request.enabled_for_model?(@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?
@@ -39,18 +74,23 @@ module PaperTrail
     end
 
     # Adds a callback that records a version before or after a "destroy" event.
+    #
+    # @api public
     def on_destroy(recording_order = "before")
       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?
-        ::ActiveSupport::Deprecation.warn(E_CANNOT_RECORD_AFTER_DESTROY)
+        raise E_CANNOT_RECORD_AFTER_DESTROY
       end
 
       @model_class.send(
         "#{recording_order}_destroy",
-        ->(r) { r.paper_trail.record_destroy if r.paper_trail.save_version? }
+        lambda do |r|
+          return unless r.paper_trail.save_version?
+          r.paper_trail.record_destroy(recording_order)
+        end
       )
 
       return if @model_class.paper_trail_options[:on].include?(:destroy)
@@ -58,12 +98,16 @@ module PaperTrail
     end
 
     # Adds a callback that records a version after an "update" event.
+    #
+    # @api public
     def on_update
-      @model_class.before_save(on: :update) { |r|
+      @model_class.before_save { |r|
         r.paper_trail.reset_timestamp_attrs_for_update_if_needed
       }
       @model_class.after_update { |r|
-        r.paper_trail.record_update(nil) if r.paper_trail.save_version?
+        if r.paper_trail.save_version?
+          r.paper_trail.record_update(force: false, in_after_callback: true)
+        end
       }
       @model_class.after_update { |r|
         r.paper_trail.clear_version_instance
@@ -72,20 +116,21 @@ module PaperTrail
       @model_class.paper_trail_options[:on] << :update
     end
 
+    # Adds a callback that records a version after a "touch" event.
+    # @api public
+    def on_touch
+      @model_class.after_touch { |r|
+        r.paper_trail.record_update(force: true, in_after_callback: true)
+      }
+    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]
+      options[:on] ||= %i[create update destroy touch]
       options[:on] = Array(options[:on]) # Support single symbol
       @model_class.send :include, ::PaperTrail::Model::InstanceMethods
-      if ::ActiveRecord::VERSION::STRING < "4.2"
-        ::ActiveSupport::Deprecation.warn(
-          "Your version of ActiveRecord (< 4.2) has reached EOL. PaperTrail " \
-          "will soon drop support. Please upgrade ActiveRecord ASAP."
-        )
-        @model_class.send :extend, AttributeSerializers::LegacyActiveRecordShim
-      end
       setup_options(options)
       setup_associations(options)
       setup_transaction_callbacks
@@ -103,6 +148,14 @@ module PaperTrail
       Gem::Version.new(ActiveRecord::VERSION::STRING)
     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 format(E_HPT_ABSTRACT_CLASS, @model_class, class_name)
+      end
+    end
+
     def cannot_record_after_destroy?
       Gem::Version.new(ActiveRecord::VERSION::STRING).release >= Gem::Version.new("5") &&
         ::ActiveRecord::Base.belongs_to_required_by_default
@@ -128,6 +181,8 @@ module PaperTrail
 
       @model_class.send :attr_accessor, :paper_trail_event
 
+      assert_concrete_activerecord_class(@model_class.version_class_name)
+
       @model_class.has_many(
         @model_class.versions_association_name,
         -> { order(model.timestamp_sort_order) },
@@ -182,8 +237,8 @@ module PaperTrail
 
     # Reset the transaction id when the transaction is closed.
     def setup_transaction_callbacks
-      @model_class.after_commit { PaperTrail.clear_transaction_id }
-      @model_class.after_rollback { PaperTrail.clear_transaction_id }
+      @model_class.after_commit { PaperTrail.request.clear_transaction_id }
+      @model_class.after_rollback { PaperTrail.request.clear_transaction_id }
       @model_class.after_rollback { paper_trail.clear_rolled_back_versions }
     end
 

data/lib/paper_trail/queries/versions/where_object.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PaperTrail
   module Queries
     module Versions

data/lib/paper_trail/queries/versions/where_object_changes.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module PaperTrail
   module Queries
     module Versions
-      # For public API documentation, see `where_object` in
+      # For public API documentation, see `where_object_changes` in
       # `paper_trail/version_concern.rb`.
       # @api private
       class WhereObjectChanges

data/lib/paper_trail/record_history.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PaperTrail
   # Represents the history of a single record.
   # @api private

data/lib/paper_trail/record_trail.rb

@@ -1,6 +1,41 @@
+# frozen_string_literal: true
+
 module PaperTrail
   # Represents the "paper trail" for a single record.
   class RecordTrail
+    DPR_TOUCH_WITH_VERSION = <<-STR.squish.freeze
+      my_model_instance.paper_trail.touch_with_version is deprecated,
+      please use my_model_instance.touch
+    STR
+    DPR_WHODUNNIT = <<-STR.squish.freeze
+      my_model_instance.paper_trail.whodunnit('John') is deprecated,
+      please use PaperTrail.request(whodunnit: 'John')
+    STR
+    DPR_WITHOUT_VERSIONING = <<-STR
+      my_model_instance.paper_trail.without_versioning is deprecated, without
+      an exact replacement. To disable versioning for a particular model,
+
+      ```
+      PaperTrail.request.disable_model(Banana)
+      # changes to Banana model do not create versions,
+      # but eg. changes to Kiwi model do.
+      PaperTrail.request.enable_model(Banana)
+      ```
+
+      Or, you may want to disable all models,
+
+      ```
+      PaperTrail.request.enabled = false
+      # no versions created
+      PaperTrail.request.enabled = true
+
+      # or, with a block,
+      PaperTrail.request(enabled: false) do
+        # no versions created
+      end
+      ```
+    STR
+
     RAILS_GTE_5_1 = ::ActiveRecord.gem_version >= ::Gem::Version.new("5.1.0.beta1")
 
     def initialize(record)
@@ -21,6 +56,7 @@ module PaperTrail
     # > instead, similar to the other branch in reify_has_one.
     # > -Sean Griffin (https://github.com/airblade/paper_trail/pull/899)
     #
+    # @api private
     def appear_as_new_record
       @record.instance_eval {
         alias :old_new_record? :new_record?
@@ -96,12 +132,24 @@ module PaperTrail
       notable_changes.to_hash
     end
 
+    # Is PT enabled for this particular record?
+    # @api private
     def enabled?
-      PaperTrail.enabled? && PaperTrail.enabled_for_controller? && enabled_for_model?
+      PaperTrail.enabled? &&
+        PaperTrail.request.enabled? &&
+        PaperTrail.request.enabled_for_model?(@record.class)
     end
 
+    # Not sure why, but this method was mentioned in the README in the past,
+    # so we need to deprecate it properly.
+    # @deprecated
     def enabled_for_model?
-      @record.class.paper_trail.enabled?
+      ::ActiveSupport::Deprecation.warn(
+        "MyModel#paper_trail.enabled_for_model? is deprecated, use " \
+        "PaperTrail.request.enabled_for_model?(MyModel) instead.",
+        caller(1)
+      )
+      PaperTrail.request.enabled_for_model?(@record.class)
     end
 
     # An attributed is "ignored" if it is listed in the `:ignore` option
@@ -119,6 +167,8 @@ module PaperTrail
     end
 
     # Updates `data` from the model's `meta` option and from `controller_info`.
+    # Metadata is always recorded; that means all three events (create, update,
+    # destroy) and `update_columns`.
     # @api private
     def merge_metadata_into(data)
       merge_metadata_from_model_into(data)
@@ -128,7 +178,7 @@ module PaperTrail
     # Updates `data` from `controller_info`.
     # @api private
     def merge_metadata_from_controller_into(data)
-      data.merge(PaperTrail.controller_info || {})
+      data.merge(PaperTrail.request.controller_info || {})
     end
 
     # Updates `data` from the model's `meta` option.
@@ -186,6 +236,8 @@ module PaperTrail
 
     # Returns hash of attributes (with appropriate attributes serialized),
     # omitting attributes to be skipped.
+    #
+    # @api private
     def object_attrs_for_paper_trail
       attrs = attributes_before_change.except(*@record.paper_trail_options[:skip])
       AttributeSerializers::ObjectAttribute.new(@record.class).serialize(attrs)
@@ -193,11 +245,15 @@ module PaperTrail
     end
 
     # Returns who put `@record` into its current state.
+    #
+    # @api public
     def originator
       (source_version || versions.last).try(:whodunnit)
     end
 
     # Returns the object (not a Version) as it was most recently.
+    #
+    # @api public
     def previous_version
       (source_version ? source_version.previous : versions.last).try(:reify)
     end
@@ -218,19 +274,23 @@ module PaperTrail
     def data_for_create
       data = {
         event: @record.paper_trail_event || "create",
-        whodunnit: PaperTrail.whodunnit
+        whodunnit: PaperTrail.request.whodunnit
       }
       if @record.respond_to?(:updated_at)
         data[:created_at] = @record.updated_at
       end
       if record_object_changes? && changed_notably?
-        data[:object_changes] = recordable_object_changes
+        data[:object_changes] = recordable_object_changes(changes)
       end
       add_transaction_id_to(data)
       merge_metadata_into(data)
     end
 
-    def record_destroy
+    # `recording_order` is "after" or "before". See ModelConfig#on_destroy.
+    #
+    # @api private
+    def record_destroy(recording_order)
+      @in_after_callback = recording_order == "after"
       if enabled? && !@record.new_record?
         version = @record.class.paper_trail.version_class.create(data_for_destroy)
         if version.errors.any?
@@ -242,6 +302,8 @@ module PaperTrail
           save_associations(version)
         end
       end
+    ensure
+      @in_after_callback = false
     end
 
     # Returns data for record destroy
@@ -252,7 +314,7 @@ module PaperTrail
         item_type: @record.class.base_class.name,
         event: @record.paper_trail_event || "destroy",
         object: recordable_object,
-        whodunnit: PaperTrail.whodunnit
+        whodunnit: PaperTrail.request.whodunnit
       }
       add_transaction_id_to(data)
       merge_metadata_into(data)
@@ -266,8 +328,8 @@ module PaperTrail
         @record.class.paper_trail.version_class.column_names.include?("object_changes")
     end
 
-    def record_update(force)
-      @in_after_callback = true
+    def record_update(force:, in_after_callback:)
+      @in_after_callback = in_after_callback
       if enabled? && (force || changed_notably?)
         versions_assoc = @record.send(@record.class.versions_association_name)
         version = versions_assoc.create(data_for_update)
@@ -282,19 +344,49 @@ module PaperTrail
       @in_after_callback = false
     end
 
-    # Returns data for record update
+    # Used during `record_update`, returns a hash of data suitable for an AR
+    # `create`. That is, all the attributes of the nascent `Version` record.
+    #
     # @api private
     def data_for_update
       data = {
         event: @record.paper_trail_event || "update",
         object: recordable_object,
-        whodunnit: PaperTrail.whodunnit
+        whodunnit: PaperTrail.request.whodunnit
       }
       if @record.respond_to?(:updated_at)
         data[:created_at] = @record.updated_at
       end
       if record_object_changes?
-        data[:object_changes] = recordable_object_changes
+        data[:object_changes] = recordable_object_changes(changes)
+      end
+      add_transaction_id_to(data)
+      merge_metadata_into(data)
+    end
+
+    # @api private
+    def record_update_columns(changes)
+      return unless enabled?
+      versions_assoc = @record.send(@record.class.versions_association_name)
+      version = versions_assoc.create(data_for_update_columns(changes))
+      if version.errors.any?
+        log_version_errors(version, :update)
+      else
+        update_transaction_id(version)
+        save_associations(version)
+      end
+    end
+
+    # Returns data for record_update_columns
+    # @api private
+    def data_for_update_columns(changes)
+      data = {
+        event: @record.paper_trail_event || "update",
+        object: recordable_object,
+        whodunnit: PaperTrail.request.whodunnit
+      }
+      if record_object_changes?
+        data[:object_changes] = recordable_object_changes(changes)
       end
       add_transaction_id_to(data)
       merge_metadata_into(data)
@@ -305,6 +397,7 @@ module PaperTrail
     # column, then a hash can be used in the assignment, otherwise the column
     # is a `text` column, and we must perform the serialization here, using
     # `PaperTrail.serializer`.
+    #
     # @api private
     def recordable_object
       if @record.class.paper_trail.version_class.object_col_is_json?
@@ -319,8 +412,9 @@ module PaperTrail
     # a postgres `json` column, then a hash can be used in the assignment,
     # otherwise the column is a `text` column, and we must perform the
     # serialization here, using `PaperTrail.serializer`.
+    #
     # @api private
-    def recordable_object_changes
+    def recordable_object_changes(changes)
       if @record.class.paper_trail.version_class.object_changes_col_is_json?
         changes
       else
@@ -333,13 +427,7 @@ module PaperTrail
     def reset_timestamp_attrs_for_update_if_needed
       return if live?
       @record.send(:timestamp_attributes_for_update_in_model).each do |column|
-        # ActiveRecord 4.2 deprecated `reset_column!` in favor of
-        # `restore_column!`.
-        if @record.respond_to?("restore_#{column}!")
-          @record.send("restore_#{column}!")
-        else
-          @record.send("reset_#{column}!")
-        end
+        @record.send("restore_#{column}!")
       end
     end
 
@@ -388,15 +476,23 @@ module PaperTrail
       version
     end
 
-    # Mimics the `touch` method from `ActiveRecord::Persistence`, but also
-    # creates a version. A version is created regardless of options such as
-    # `:on`, `:if`, or `:unless`.
+    # Mimics the `touch` method from `ActiveRecord::Persistence` (without
+    # actually calling `touch`), but also creates a version.
+    #
+    # A version is created regardless of options such as `:on`, `:if`, or
+    # `:unless`.
+    #
+    # This is an "update" event. That is, we record the same data we would in
+    # the case of a normal AR `update`.
     #
-    # TODO: look into leveraging the `after_touch` callback from
-    # `ActiveRecord` to allow the regular `touch` method to generate a version
-    # as normal. May make sense to switch the `record_update` method to
-    # leverage an `after_update` callback anyways (likely for v4.0.0)
+    # Some advanced PT users disable all callbacks (eg. `has_paper_trail(on:
+    # [])`) and use only this method, giving them complete control over when
+    # version records are inserted. It's unclear under which specific
+    # circumstances this technique should be adopted.
+    #
+    # @deprecated
     def touch_with_version(name = nil)
+      ::ActiveSupport::Deprecation.warn(DPR_TOUCH_WITH_VERSION, caller(1))
       unless @record.persisted?
         raise ::ActiveRecord::ActiveRecordError, "can not touch on a new record object"
       end
@@ -406,8 +502,32 @@ module PaperTrail
       attributes.each { |column|
         @record.send(:write_attribute, column, current_time)
       }
-      record_update(true) unless will_record_after_update?
-      @record.save!(validate: false)
+      ::PaperTrail.request(enabled: false) do
+        @record.save!(validate: false)
+      end
+      record_update(force: true, in_after_callback: false)
+    end
+
+    # Like the `update_column` method from `ActiveRecord::Persistence`, but also
+    # creates a version to record those changes.
+    # @api public
+    def update_column(name, value)
+      update_columns(name => value)
+    end
+
+    # Like the `update_columns` method from `ActiveRecord::Persistence`, but also
+    # creates a version to record those changes.
+    # @api public
+    def update_columns(attributes)
+      # `@record.update_columns` skips dirty tracking, so we can't just use `@record.changes` or
+      # @record.saved_changes` from `ActiveModel::Dirty`. We need to build our own hash with the
+      # changes that will be made directly to the database.
+      changes = {}
+      attributes.each do |k, v|
+        changes[k] = [@record[k], v]
+      end
+      @record.update_columns(attributes)
+      record_update_columns(changes)
     end
 
     # Returns the object (not a Version) as it was at the given timestamp.
@@ -426,9 +546,11 @@ module PaperTrail
     end
 
     # Executes the given method or block without creating a new version.
+    # @deprecated
     def without_versioning(method = nil)
-      paper_trail_was_enabled = enabled_for_model?
-      @record.class.paper_trail.disable
+      ::ActiveSupport::Deprecation.warn(DPR_WITHOUT_VERSIONING, caller(1))
+      paper_trail_was_enabled = PaperTrail.request.enabled_for_model?(@record.class)
+      PaperTrail.request.disable_model(@record.class)
       if method
         if respond_to?(method)
           public_send(method)
@@ -439,27 +561,28 @@ module PaperTrail
         yield @record
       end
     ensure
-      @record.class.paper_trail.enable if paper_trail_was_enabled
+      PaperTrail.request.enable_model(@record.class) if paper_trail_was_enabled
     end
 
-    # Temporarily overwrites the value of whodunnit and then executes the
-    # provided block.
+    # @deprecated
     def whodunnit(value)
       raise ArgumentError, "expected to receive a block" unless block_given?
-      current_whodunnit = PaperTrail.whodunnit
-      PaperTrail.whodunnit = value
-      yield @record
-    ensure
-      PaperTrail.whodunnit = current_whodunnit
+      ::ActiveSupport::Deprecation.warn(DPR_WHODUNNIT, caller(1))
+      ::PaperTrail.request(whodunnit: value) do
+        yield @record
+      end
     end
 
     private
 
     def add_transaction_id_to(data)
       return unless @record.class.paper_trail.version_class.column_names.include?("transaction_id")
-      data[:transaction_id] = PaperTrail.transaction_id
+      data[:transaction_id] = PaperTrail.request.transaction_id
     end
 
+    # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+    # https://github.com/airblade/paper_trail/pull/899
+    #
     # @api private
     def attribute_changed_in_latest_version?(attr_name)
       if @in_after_callback && RAILS_GTE_5_1
@@ -469,15 +592,29 @@ module PaperTrail
       end
     end
 
+    # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+    # https://github.com/airblade/paper_trail/pull/899
+    #
+    # Event can be any of the three (create, update, destroy).
+    #
     # @api private
     def attribute_in_previous_version(attr_name)
-      if @in_after_callback && RAILS_GTE_5_1
-        @record.attribute_before_last_save(attr_name.to_s)
+      if RAILS_GTE_5_1
+        if @in_after_callback
+          @record.attribute_before_last_save(attr_name.to_s)
+        else
+          # We are performing a `record_destroy`. Other events,
+          # like `record_create`, can only be done in an after-callback.
+          @record.attribute_in_database(attr_name.to_s)
+        end
       else
         @record.attribute_was(attr_name.to_s)
       end
     end
 
+    # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+    # https://github.com/airblade/paper_trail/pull/899
+    #
     # @api private
     def changed_in_latest_version
       if @in_after_callback && RAILS_GTE_5_1
@@ -487,6 +624,9 @@ module PaperTrail
       end
     end
 
+    # Rails 5.1 changed the API of `ActiveRecord::Dirty`. See
+    # https://github.com/airblade/paper_trail/pull/899
+    #
     # @api private
     def changes_in_latest_version
       if @in_after_callback && RAILS_GTE_5_1
@@ -497,6 +637,7 @@ module PaperTrail
     end
 
     # Given a HABTM association, returns an array of ids.
+    #
     # @api private
     def habtm_assoc_ids(habtm_assoc)
       current = @record.send(habtm_assoc.name).to_a.map(&:id) # TODO: `pluck` would use less memory
@@ -506,7 +647,7 @@ module PaperTrail
     end
 
     def log_version_errors(version, action)
-      version.logger && version.logger.warn(
+      version.logger&.warn(
         "Unable to create version for #{action} of #{@record.class.name}" +
           "##{@record.id}: " + version.errors.full_messages.join(", ")
       )
@@ -522,10 +663,10 @@ module PaperTrail
 
       if assoc.options[:polymorphic]
         associated_record = @record.send(assoc.name) if @record.send(assoc.foreign_type)
-        if associated_record && associated_record.class.paper_trail.enabled?
+        if associated_record && PaperTrail.request.enabled_for_model?(associated_record.class)
           assoc_version_args[:foreign_key_id] = associated_record.id
         end
-      elsif assoc.klass.paper_trail.enabled?
+      elsif PaperTrail.request.enabled_for_model?(assoc.klass)
         assoc_version_args[:foreign_key_id] = @record.send(assoc.foreign_key)
       end
 
@@ -538,20 +679,13 @@ module PaperTrail
     # @api private
     def save_habtm_association?(assoc)
       @record.class.paper_trail_save_join_tables.include?(assoc.name) ||
-        assoc.klass.paper_trail.enabled?
-    end
-
-    # Returns true if `save` will cause `record_update`
-    # to be called via the `after_update` callback.
-    def will_record_after_update?
-      on = @record.paper_trail_options[:on]
-      on.nil? || on.include?(:update)
+        PaperTrail.request.enabled_for_model?(assoc.klass)
     end
 
     def update_transaction_id(version)
       return unless @record.class.paper_trail.version_class.column_names.include?("transaction_id")
-      if PaperTrail.transaction? && PaperTrail.transaction_id.nil?
-        PaperTrail.transaction_id = version.id
+      if PaperTrail.transaction? && PaperTrail.request.transaction_id.nil?
+        PaperTrail.request.transaction_id = version.id
         version.transaction_id = version.id
         version.save
       end