paper_trail 3.0.6 → 4.2.0

data/lib/paper_trail/cleaner.rb

@@ -1,35 +1,52 @@
 module PaperTrail
   module Cleaner
-    # Destroys all but the most recent version(s) for items on a given date (or on all dates). Useful for deleting drafts.
+    # Destroys all but the most recent version(s) for items on a given date
+    # (or on all dates). Useful for deleting drafts.
     #
     # Options:
-    # :keeping      An `integer` indicating the number of versions to be kept for each item per date.
-    #               Defaults to `1`.
-    # :date         Should either be a `Date` object specifying which date to destroy versions for or `:all`,
-    #               which will specify that all dates should be cleaned. Defaults to `:all`.
-    # :item_id      The `id` for the item to be cleaned on, or `nil`, which causes all items to be cleaned.
-    #               Defaults to `nil`.
+    #
+    # - :keeping - An `integer` indicating the number of versions to be kept for
+    #   each item per date. Defaults to `1`.
+    # - :date - Should either be a `Date` object specifying which date to
+    #   destroy versions for or `:all`, which will specify that all dates
+    #   should be cleaned. Defaults to `:all`.
+    # - :item_id - The `id` for the item to be cleaned on, or `nil`, which
+    #   causes all items to be cleaned. Defaults to `nil`.
+    #
     def clean_versions!(options = {})
       options = {:keeping => 1, :date => :all}.merge(options)
       gather_versions(options[:item_id], options[:date]).each do |item_id, versions|
-        versions.group_by { |v| v.send(PaperTrail.timestamp_field).to_date }.each do |date, versions|
-          # remove the number of versions we wish to keep from the collection of versions prior to destruction
-          versions.pop(options[:keeping])
-          versions.map(&:destroy)
+        group_versions_by_date(versions).each do |date, _versions|
+          # Remove the number of versions we wish to keep from the collection
+          # of versions prior to destruction.
+          _versions.pop(options[:keeping])
+          _versions.map(&:destroy)
         end
       end
     end
 
     private
 
-    # Returns a hash of versions grouped by the `item_id` attribute formatted like this: {:item_id => PaperTrail::Version}.
-    # If `item_id` or `date` is set, versions will be narrowed to those pointing at items with those ids that were created on specified date.
+    # Returns a hash of versions grouped by the `item_id` attribute formatted
+    # like this: {:item_id => PaperTrail::Version}. If `item_id` or `date` is
+    # set, versions will be narrowed to those pointing at items with those ids
+    # that were created on specified date.
     def gather_versions(item_id = nil, date = :all)
-      raise "`date` argument must receive a Timestamp or `:all`" unless date == :all || date.respond_to?(:to_date)
+      raise ArgumentError.new("`date` argument must receive a Timestamp or `:all`") unless date == :all || date.respond_to?(:to_date)
       versions = item_id ? PaperTrail::Version.where(:item_id => item_id) : PaperTrail::Version
       versions = versions.between(date.to_date, date.to_date + 1.day) unless date == :all
-      versions = PaperTrail::Version.all if versions == PaperTrail::Version # if versions has not been converted to an ActiveRecord::Relation yet, do so now
+
+      # If `versions` has not been converted to an ActiveRecord::Relation yet,
+      # do so now.
+      versions = PaperTrail::Version.all if versions == PaperTrail::Version
       versions.group_by(&:item_id)
     end
+
+    # Given an array of versions, returns a hash mapping dates to arrays of
+    # versions.
+    # @api private
+    def group_versions_by_date(versions)
+      versions.group_by { |v| v.send(PaperTrail.timestamp_field).to_date }
+    end
   end
 end

data/lib/paper_trail/config.rb

@@ -1,14 +1,47 @@
 require 'singleton'
+require 'paper_trail/serializers/yaml'
 
 module PaperTrail
   class Config
     include Singleton
-    attr_accessor :enabled, :timestamp_field, :serializer, :version_limit
+    attr_accessor :timestamp_field, :serializer, :version_limit
+    attr_writer :track_associations
 
     def initialize
-      @enabled         = true # Indicates whether PaperTrail is on or off.
       @timestamp_field = :created_at
       @serializer      = PaperTrail::Serializers::YAML
     end
+
+    def serialized_attributes
+      ActiveSupport::Deprecation.warn(
+        "PaperTrail.config.serialized_attributes is deprecated without " +
+          "replacement and always returns false."
+      )
+      false
+    end
+
+    def serialized_attributes=(_)
+      ActiveSupport::Deprecation.warn(
+        "PaperTrail.config.serialized_attributes= is deprecated without " +
+          "replacement and no longer has any effect."
+      )
+    end
+
+    def track_associations
+      @track_associations.nil? ?
+        PaperTrail::VersionAssociation.table_exists? :
+        @track_associations
+    end
+    alias_method :track_associations?, :track_associations
+
+    # Indicates whether PaperTrail is on or off. Default: true.
+    def enabled
+      value = PaperTrail.paper_trail_store.fetch(:paper_trail_enabled, true)
+      value.nil? ? true : value
+    end
+
+    def enabled= enable
+      PaperTrail.paper_trail_store[:paper_trail_enabled] = enable
+    end
   end
 end

data/lib/paper_trail/frameworks/active_record.rb

@@ -1,5 +1,4 @@
-# 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`
-Dir[File.join(File.dirname(__FILE__), 'active_record', 'models', 'paper_trail', '*.rb')].each do |file|
-  require "paper_trail/frameworks/active_record/models/paper_trail/#{File.basename(file, '.rb')}"
-end
+# 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"
+require "paper_trail/frameworks/active_record/models/paper_trail/version"

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

@@ -0,0 +1,7 @@
+require 'paper_trail/version_association_concern'
+
+module PaperTrail
+  class VersionAssociation < ::ActiveRecord::Base
+    include PaperTrail::VersionAssociationConcern
+  end
+end

data/lib/paper_trail/frameworks/rails.rb

@@ -1,4 +1,5 @@
 require 'paper_trail/frameworks/rails/controller'
+require 'paper_trail/frameworks/rails/engine'
 
 module PaperTrail
   module Rails

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

@@ -3,8 +3,22 @@ module PaperTrail
     module Controller
 
       def self.included(base)
-        base.before_filter :set_paper_trail_enabled_for_controller
-        base.before_filter :set_paper_trail_whodunnit, :set_paper_trail_controller_info
+        before = [
+          :set_paper_trail_enabled_for_controller,
+          :set_paper_trail_whodunnit,
+          :set_paper_trail_controller_info
+        ]
+        after = []
+
+        if base.respond_to? :before_action
+          # Rails 4+
+          before.map {|sym| base.before_action sym }
+          after.map  {|sym| base.after_action  sym }
+        else
+          # Rails 3.
+          before.map {|sym| base.before_filter sym }
+          after.map  {|sym| base.after_filter  sym }
+        end
       end
 
       protected
@@ -36,24 +50,26 @@ module PaperTrail
       #
       # The columns `ip` and `user_agent` must exist in your `versions` # table.
       #
-      # Use the `:meta` option to `PaperTrail::Model::ClassMethods.has_paper_trail`
-      # to store any extra model-level data you need.
+      # Use the `:meta` option to
+      # `PaperTrail::Model::ClassMethods.has_paper_trail` to store any extra
+      # model-level data you need.
       def info_for_paper_trail
         {}
       end
 
-      # Returns `true` (default) or `false` depending on whether PaperTrail should
-      # be active for the current request.
+      # Returns `true` (default) or `false` depending on whether PaperTrail
+      # should be active for the current request.
       #
-      # Override this method in your controller to specify when PaperTrail should
-      # be off.
+      # Override this method in your controller to specify when PaperTrail
+      # should be off.
       def paper_trail_enabled_for_controller
         ::PaperTrail.enabled?
       end
 
       private
 
-      # Tells PaperTrail whether versions should be saved in the current request.
+      # Tells PaperTrail whether versions should be saved in the current
+      # request.
       def set_paper_trail_enabled_for_controller
         ::PaperTrail.enabled_for_controller = paper_trail_enabled_for_controller
       end
@@ -63,8 +79,8 @@ module PaperTrail
         ::PaperTrail.whodunnit = user_for_paper_trail if ::PaperTrail.enabled_for_controller?
       end
 
-      # Tells PaperTrail any information from the controller you want
-      # to store alongside any changes that occur.
+      # Tells PaperTrail any information from the controller you want to store
+      # alongside any changes that occur.
       def set_paper_trail_controller_info
         ::PaperTrail.controller_info = info_for_paper_trail if ::PaperTrail.enabled_for_controller?
       end

data/lib/paper_trail/frameworks/rspec.rb

@@ -22,3 +22,8 @@ RSpec::Matchers.define :be_versioned do
   # check to see if the model has `has_paper_trail` declared on it
   match { |actual| actual.kind_of?(::PaperTrail::Model::InstanceMethods) }
 end
+
+RSpec::Matchers.define :have_a_version_with do |attributes|
+  # check if the model has a version with the specified attributes
+  match { |actual| actual.versions.where_object(attributes).any? }
+end

data/lib/paper_trail/frameworks/sinatra.rb

@@ -3,8 +3,10 @@ require 'active_support/core_ext/object' # provides the `try` method
 module PaperTrail
   module Sinatra
 
-    # Register this module inside your Sinatra application to gain access to controller-level methods used by PaperTrail
+    # Register this module inside your Sinatra application to gain access to
+    # controller-level methods used by PaperTrail.
     def self.registered(app)
+      app.use RequestStore::Middleware
       app.helpers self
       app.before { set_paper_trail_whodunnit }
     end

data/lib/paper_trail/has_paper_trail.rb

@@ -1,3 +1,6 @@
+require 'active_support/core_ext/object' # provides the `try` method
+require 'paper_trail/attributes_serialization'
+
 module PaperTrail
   module Model
 
@@ -6,34 +9,60 @@ module PaperTrail
     end
 
     module ClassMethods
-      # Declare this in your model to track every create, update, and destroy.  Each version of
-      # the model is available in the `versions` association.
+      # Declare this in your model to track every create, update, and destroy.
+      # Each version of the model is available in the `versions` association.
       #
       # Options:
-      # :on           the events to track (optional; defaults to all of them).  Set to an array of
-      #               `:create`, `:update`, `:destroy` as desired.
-      # :class_name   the name of a custom Version class.  This class should inherit from `PaperTrail::Version`.
-      # :ignore       an array of attributes for which a new `Version` will not be created if only they change.
-      #               it can also aceept a Hash as an argument where the key is the attribute to ignore (a `String` or `Symbol`),
-      #               which will only be ignored if the value is a `Proc` which returns truthily.
-      # :if, :unless  Procs that allow to specify conditions when to save versions for an object
-      # :only         inverse of `ignore` - a new `Version` will be created only for these attributes if supplied
-      #               it can also aceept a Hash as an argument where the key is the attribute to track (a `String` or `Symbol`),
-      #               which will only be counted if the value is a `Proc` which returns truthily.
-      # :skip         fields to ignore completely.  As with `ignore`, updates to these fields will not create
-      #               a new `Version`.  In addition, these fields will not be included in the serialized versions
-      #               of the object whenever a new `Version` is created.
-      # :meta         a hash of extra data to store.  You must add a column to the `versions` table for each key.
-      #               Values are objects or procs (which are called with `self`, i.e. the model with the paper
-      #               trail).  See `PaperTrail::Controller.info_for_paper_trail` for how to store data from
-      #               the controller.
-      # :versions     the name to use for the versions association.  Default is `:versions`.
-      # :version      the name to use for the method which returns the version the instance was reified from.
-      #               Default is `:version`.
+      #
+      # - :on - The events to track (optional; defaults to all of them). Set
+      #   to an array of `:create`, `:update`, `:destroy` as desired.
+      # - :class_name - The name of a custom Version class.  This class should
+      #   inherit from `PaperTrail::Version`.
+      # - :ignore - An array of attributes for which a new `Version` will not be
+      #   created if only they change. It can also aceept a Hash as an
+      #   argument where the key is the attribute to ignore (a `String` or
+      #   `Symbol`), which will only be ignored if the value is a `Proc` which
+      #   returns truthily.
+      # - :if, :unless - Procs that allow to specify conditions when to save
+      #   versions for an object.
+      # - :only - Inverse of `ignore`. A new `Version` will be created only
+      #   for these attributes if supplied it can also aceept a Hash as an
+      #   argument where the key is the attribute to track (a `String` or
+      #   `Symbol`), which will only be counted if the value is a `Proc` which
+      #   returns truthily.
+      # - :skip - Fields to ignore completely.  As with `ignore`, updates to
+      #   these fields will not create a new `Version`.  In addition, these
+      #   fields will not be included in the serialized versions of the object
+      #   whenever a new `Version` is created.
+      # - :meta - A hash of extra data to store. You must add a column to the
+      #   `versions` table for each key. Values are objects or procs (which
+      #   are called with `self`, i.e. the model with the paper trail).  See
+      #   `PaperTrail::Controller.info_for_paper_trail` for how to store data
+      #   from the controller.
+      # - :versions - The name to use for the versions association.  Default
+      #   is `:versions`.
+      # - :version - The name to use for the method which returns the version
+      #   the instance was reified from. Default is `:version`.
+      # - :save_changes - Whether or not to save changes to the object_changes
+      #   column if it exists. Default is true
+      #
       def has_paper_trail(options = {})
+        options[:on] ||= [:create, :update, :destroy]
+
+        # Wrap the :on option in an array if necessary. This allows a single
+        # symbol to be passed in.
+        options[:on] = Array(options[:on])
+
+        setup_model_for_paper_trail(options)
+
+        setup_callbacks_from_options options[:on]
+      end
+
+      def setup_model_for_paper_trail(options = {})
         # Lazily include the instance methods so we don't clutter up
         # any more ActiveRecord models than we have to.
         send :include, InstanceMethods
+        send :extend, AttributesSerialization
 
         class_attribute :version_association_name
         self.version_association_name = options[:version] || :version
@@ -45,6 +74,7 @@ module PaperTrail
         self.version_class_name = options[:class_name] || 'PaperTrail::Version'
 
         class_attribute :paper_trail_options
+
         self.paper_trail_options = options.dup
 
         [:ignore, :skip, :only].each do |k|
@@ -53,13 +83,15 @@ module PaperTrail
         end
 
         paper_trail_options[:meta] ||= {}
+        paper_trail_options[:save_changes] = true if paper_trail_options[:save_changes].nil?
 
         class_attribute :versions_association_name
         self.versions_association_name = options[:versions] || :versions
 
         attr_accessor :paper_trail_event
 
-        if ::ActiveRecord::VERSION::MAJOR >= 4 # `has_many` syntax for specifying order uses a lambda in Rails 4
+        # `has_many` syntax for specifying order uses a lambda in Rails 4
+        if ::ActiveRecord::VERSION::MAJOR >= 4
           has_many self.versions_association_name,
             lambda { order(model.timestamp_sort_order) },
             :class_name => self.version_class_name, :as => :item
@@ -70,96 +102,79 @@ module PaperTrail
             :order      => self.paper_trail_version_class.timestamp_sort_order
         end
 
-        options_on = Array(options[:on]) # so that a single symbol can be passed in without wrapping it in an `Array`
-        after_create  :record_create, :if => :save_version? if options_on.empty? || options_on.include?(:create)
-        if options_on.empty? || options_on.include?(:update)
-          before_save   :reset_timestamp_attrs_for_update_if_needed!, :on => :update
-          before_update :record_update, :if => :save_version?
-          after_update  :clear_version_instance!
-        end
-        after_destroy :record_destroy, :if => :save_version? if options_on.empty? || options_on.include?(:destroy)
-      end
-
-      # Switches PaperTrail off for this class.
-      def paper_trail_off!
-        PaperTrail.enabled_for_model(self, false)
+        # Reset the transaction id when the transaction is closed.
+        after_commit :reset_transaction_id
+        after_rollback :reset_transaction_id
+        after_rollback :clear_rolled_back_versions
       end
 
-      def paper_trail_off
-        warn "DEPRECATED: use `paper_trail_off!` instead of `paper_trail_off`. Support for `paper_trail_off` will be removed in PaperTrail 3.1"
-        self.paper_trail_off!
+      def setup_callbacks_from_options(options_on = [])
+        options_on.each do |option|
+          send "paper_trail_on_#{option}"
+        end
       end
 
-      # Switches PaperTrail on for this class.
-      def paper_trail_on!
-        PaperTrail.enabled_for_model(self, true)
-      end
+      # Record version before or after "destroy" event
+      def paper_trail_on_destroy(recording_order = 'after')
+        unless %w[after before].include?(recording_order.to_s)
+          fail ArgumentError, 'recording order can only be "after" or "before"'
+        end
 
-      def paper_trail_on
-        warn "DEPRECATED: use `paper_trail_on!` instead of `paper_trail_on`. Support for `paper_trail_on` will be removed in PaperTrail 3.1"
-        self.paper_trail_on!
-      end
+        if recording_order.to_s == 'after' and
+          Gem::Version.new(ActiveRecord::VERSION::STRING).release >= Gem::Version.new("5")
+          if ::ActiveRecord::Base.belongs_to_required_by_default
+            ::ActiveSupport::Deprecation.warn(
+              "paper_trail_on_destroy(:after) is incompatible with ActiveRecord " +
+                "belongs_to_required_by_default and has no effect. Please use :before " +
+                "or disable belongs_to_required_by_default."
+            )
+          end
+        end
 
-      def paper_trail_enabled_for_model?
-        PaperTrail.enabled_for_model?(self)
-      end
+        send "#{recording_order}_destroy", :record_destroy, :if => :save_version?
 
-      def paper_trail_version_class
-        @paper_trail_version_class ||= version_class_name.constantize
+        return if paper_trail_options[:on].include?(:destroy)
+        paper_trail_options[:on] << :destroy
       end
 
-      # Used for Version#object attribute
-      def serialize_attributes_for_paper_trail(attributes)
-        # don't serialize before values before inserting into columns of type `JSON` on `PostgreSQL` databases
-        return attributes if self.paper_trail_version_class.object_col_is_json?
+      # Record version after "update" event
+      def paper_trail_on_update
+        before_save  :reset_timestamp_attrs_for_update_if_needed!,
+                     :on => :update
+        after_update :record_update,
+                     :if => :save_version?
+        after_update :clear_version_instance!
 
-        serialized_attributes.each do |key, coder|
-          if attributes.key?(key)
-            coder = PaperTrail::Serializers::YAML unless coder.respond_to?(:dump) # Fall back to YAML if `coder` has no `dump` method
-            attributes[key] = coder.dump(attributes[key])
-          end
-        end
+        return if paper_trail_options[:on].include?(:update)
+        paper_trail_options[:on] << :update
       end
 
-      def unserialize_attributes_for_paper_trail(attributes)
-        # don't serialize before values before inserting into columns of type `JSON` on `PostgreSQL` databases
-        return attributes if self.paper_trail_version_class.object_col_is_json?
+      # Record version after "create" event
+      def paper_trail_on_create
+        after_create :record_create,
+                     :if => :save_version?
 
-        serialized_attributes.each do |key, coder|
-          if attributes.key?(key)
-            coder = PaperTrail::Serializers::YAML unless coder.respond_to?(:dump)
-            attributes[key] = coder.load(attributes[key])
-          end
-        end
+        return if paper_trail_options[:on].include?(:create)
+        paper_trail_options[:on] << :create
       end
 
-      # Used for Version#object_changes attribute
-      def serialize_attribute_changes(changes)
-        # don't serialize before values before inserting into columns of type `JSON` on `PostgreSQL` databases
-        return changes if self.paper_trail_version_class.object_changes_col_is_json?
+      # Switches PaperTrail off for this class.
+      def paper_trail_off!
+        PaperTrail.enabled_for_model(self, false)
+      end
 
-        serialized_attributes.each do |key, coder|
-          if changes.key?(key)
-            coder = PaperTrail::Serializers::YAML unless coder.respond_to?(:dump) # Fall back to YAML if `coder` has no `dump` method
-            old_value, new_value = changes[key]
-            changes[key] = [coder.dump(old_value),
-                            coder.dump(new_value)]
-          end
-        end
+      # Switches PaperTrail on for this class.
+      def paper_trail_on!
+        PaperTrail.enabled_for_model(self, true)
       end
 
-      def unserialize_attribute_changes(changes)
-        # don't serialize before values before inserting into columns of type `JSON` on `PostgreSQL` databases
-        return changes if self.paper_trail_version_class.object_changes_col_is_json?
+      def paper_trail_enabled_for_model?
+        return false unless self.include?(PaperTrail::Model::InstanceMethods)
+        PaperTrail.enabled_for_model?(self)
+      end
 
-        serialized_attributes.each do |key, coder|
-          if changes.key?(key)
-            coder = PaperTrail::Serializers::YAML unless coder.respond_to?(:dump)
-            old_value, new_value = changes[key]
-            changes[key] = [coder.load(old_value),
-                            coder.load(new_value)]
-          end
-        end
+      def paper_trail_version_class
+        @paper_trail_version_class ||= version_class_name.constantize
       end
     end
 
@@ -173,10 +188,21 @@ module PaperTrail
       end
 
       # Returns who put the object into its current state.
-      def originator
+      def paper_trail_originator
         (source_version || send(self.class.versions_association_name).last).try(:whodunnit)
       end
 
+      def originator
+        ::ActiveSupport::Deprecation.warn "Use paper_trail_originator instead of originator."
+        self.paper_trail_originator
+      end
+
+      # Invoked after rollbacks to ensure versions records are not created
+      # for changes that never actually took place
+      def clear_rolled_back_versions
+        send(self.class.versions_association_name).reload
+      end
+
       # Returns the object (not a Version) as it was at the given timestamp.
       def version_at(timestamp, reify_options={})
         # Because a version stores how its object looked *before* the change,
@@ -221,7 +247,19 @@ module PaperTrail
         self.class.paper_trail_on! if paper_trail_was_enabled
       end
 
-      # Temporarily overwrites the value of whodunnit and then executes the provided block.
+      # Utility method for reifying. Anything executed inside the block will
+      # appear like a new record.
+      def appear_as_new_record
+        instance_eval {
+          alias :old_new_record? :new_record?
+          alias :new_record? :present?
+        }
+        yield
+        instance_eval { alias :new_record? :old_new_record? }
+      end
+
+      # Temporarily overwrites the value of whodunnit and then executes the
+      # provided block.
       def whodunnit(value)
         raise ArgumentError, 'expected to receive a block' unless block_given?
         current_whodunnit = PaperTrail.whodunnit
@@ -231,11 +269,14 @@ module PaperTrail
         PaperTrail.whodunnit = current_whodunnit
       end
 
-      # Mimicks behavior of `touch` method from `ActiveRecord::Persistence`, but generates a version
+      # 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`.
       #
-      # TODO: lookinto leveraging the `after_touch` callback from `ActiveRecord` to allow the
-      #  regular `touch` method go generate a version as normal. May make sense to switch the `record_update`
-      #  method to leverage an `after_update` callback anyways (likely for v3.1.0)
+      # 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)
       def touch_with_version(name = nil)
         raise ActiveRecordError, "can not touch on a new record object" unless persisted?
 
@@ -244,11 +285,20 @@ module PaperTrail
         current_time = current_time_from_proper_timezone
 
         attributes.each { |column| write_attribute(column, current_time) }
-        save!
+
+        record_update(true) unless will_record_after_update?
+        save!(:validate => false)
       end
 
       private
 
+      # Returns true if `save` will cause `record_update`
+      # to be called via the `after_update` callback.
+      def will_record_after_update?
+        on = paper_trail_options[:on]
+        on.nil? || on.include?(:update)
+      end
+
       def source_version
         send self.class.version_association_name
       end
@@ -259,63 +309,162 @@ module PaperTrail
             :event     => paper_trail_event || 'create',
             :whodunnit => PaperTrail.whodunnit
           }
-
-          if changed_notably? and self.class.paper_trail_version_class.column_names.include?('object_changes')
-            data[:object_changes] = self.class.paper_trail_version_class.object_changes_col_is_json? ? changes_for_paper_trail :
-              PaperTrail.serializer.dump(changes_for_paper_trail)
+          if respond_to?(:updated_at)
+            data[PaperTrail.timestamp_field] = updated_at
+          end
+          if pt_record_object_changes? && changed_notably?
+            data[:object_changes] = pt_recordable_object_changes
+          end
+          if self.class.paper_trail_version_class.column_names.include?('transaction_id')
+            data[:transaction_id] = PaperTrail.transaction_id
           end
-          send(self.class.versions_association_name).create! merge_metadata(data)
+          version = send(self.class.versions_association_name).create! merge_metadata(data)
+          set_transaction_id(version)
+          save_associations(version)
         end
       end
 
-      def record_update
-        if paper_trail_switched_on? && changed_notably?
-          object_attrs = object_attrs_for_paper_trail(item_before_change)
+      def record_update(force = nil)
+        if paper_trail_switched_on? && (force || changed_notably?)
           data = {
             :event     => paper_trail_event || 'update',
-            :object    => self.class.paper_trail_version_class.object_col_is_json? ? object_attrs : PaperTrail.serializer.dump(object_attrs),
+            :object    => pt_recordable_object,
             :whodunnit => PaperTrail.whodunnit
           }
-
-          if self.class.paper_trail_version_class.column_names.include?('object_changes')
-            data[:object_changes] = self.class.paper_trail_version_class.object_changes_col_is_json? ? changes_for_paper_trail :
-              PaperTrail.serializer.dump(changes_for_paper_trail)
+          if respond_to?(:updated_at)
+            data[PaperTrail.timestamp_field] = updated_at
+          end
+          if pt_record_object_changes?
+            data[:object_changes] = pt_recordable_object_changes
+          end
+          if self.class.paper_trail_version_class.column_names.include?('transaction_id')
+            data[:transaction_id] = PaperTrail.transaction_id
           end
-          send(self.class.versions_association_name).build merge_metadata(data)
+          version = send(self.class.versions_association_name).create merge_metadata(data)
+          set_transaction_id(version)
+          save_associations(version)
+        end
+      end
+
+      # Returns a boolean indicating whether to store serialized version diffs
+      # in the `object_changes` column of the version record.
+      # @api private
+      def pt_record_object_changes?
+        paper_trail_options[:save_changes] &&
+          self.class.paper_trail_version_class.column_names.include?('object_changes')
+      end
+
+      # Returns an object which can be assigned to the `object` attribute of a
+      # nascent version record. If the `object` column is 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 pt_recordable_object
+        object_attrs = object_attrs_for_paper_trail(attributes_before_change)
+        if self.class.paper_trail_version_class.object_col_is_json?
+          object_attrs
+        else
+          PaperTrail.serializer.dump(object_attrs)
+        end
+      end
+
+      # Returns an object which can be assigned to the `object_changes`
+      # attribute of a nascent version record. If the `object_changes` column is
+      # 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 pt_recordable_object_changes
+        if self.class.paper_trail_version_class.object_changes_col_is_json?
+          changes_for_paper_trail
+        else
+          PaperTrail.serializer.dump(changes_for_paper_trail)
         end
       end
 
       def changes_for_paper_trail
-        self.changes.delete_if do |key, value|
-          !notably_changed.include?(key)
-        end.tap { |changes| self.class.serialize_attribute_changes(changes) }
+        _changes = changes.delete_if { |k,v| !notably_changed.include?(k) }
+        self.class.serialize_attribute_changes_for_paper_trail!(_changes)
+        _changes.to_hash
       end
 
-      # Invoked via`after_update` callback for when a previous version is reified and then saved
+      # Invoked via`after_update` callback for when a previous version is
+      # reified and then saved.
       def clear_version_instance!
         send("#{self.class.version_association_name}=", nil)
       end
 
+      # Invoked via callback when a user attempts to persist a reified
+      # `Version`.
       def reset_timestamp_attrs_for_update_if_needed!
-        return if self.live? # invoked via callback when a user attempts to persist a reified `Version`
-        timestamp_attributes_for_update_in_model.each { |column| send("reset_#{column}!") }
+        return if self.live?
+        timestamp_attributes_for_update_in_model.each do |column|
+          # ActiveRecord 4.2 deprecated `reset_column!` in favor of
+          # `restore_column!`.
+          if respond_to?("restore_#{column}!")
+            send("restore_#{column}!")
+          else
+            send("reset_#{column}!")
+          end
+        end
       end
 
       def record_destroy
         if paper_trail_switched_on? and not new_record?
-          object_attrs = object_attrs_for_paper_trail(item_before_change)
           data = {
             :item_id   => self.id,
             :item_type => self.class.base_class.name,
             :event     => paper_trail_event || 'destroy',
-            :object    => self.class.paper_trail_version_class.object_col_is_json? ? object_attrs : PaperTrail.serializer.dump(object_attrs),
+            :object    => pt_recordable_object,
             :whodunnit => PaperTrail.whodunnit
           }
-          send("#{self.class.version_association_name}=", self.class.paper_trail_version_class.create(merge_metadata(data)))
+          if self.class.paper_trail_version_class.column_names.include?('transaction_id')
+            data[:transaction_id] = PaperTrail.transaction_id
+          end
+          version = self.class.paper_trail_version_class.create(merge_metadata(data))
+          send("#{self.class.version_association_name}=", version)
           send(self.class.versions_association_name).send :load_target
+          set_transaction_id(version)
+          save_associations(version)
         end
       end
 
+      # Saves associations if the join table for `VersionAssociation` exists.
+      def save_associations(version)
+        return unless PaperTrail.config.track_associations?
+        self.class.reflect_on_all_associations(:belongs_to).each do |assoc|
+          assoc_version_args = {
+              :version_id => version.id,
+              :foreign_key_name => assoc.foreign_key
+          }
+
+          if assoc.options[:polymorphic]
+            associated_record = send(assoc.name) if send(assoc.foreign_type)
+            if associated_record && associated_record.class.paper_trail_enabled_for_model?
+              assoc_version_args.merge!(:foreign_key_id => associated_record.id)
+            end
+          elsif assoc.klass.paper_trail_enabled_for_model?
+            assoc_version_args.merge!(:foreign_key_id => send(assoc.foreign_key))
+          end
+
+          PaperTrail::VersionAssociation.create(assoc_version_args) if assoc_version_args.has_key?(:foreign_key_id)
+        end
+      end
+
+      def set_transaction_id(version)
+        return unless self.class.paper_trail_version_class.column_names.include?('transaction_id')
+        if PaperTrail.transaction? && PaperTrail.transaction_id.nil?
+           PaperTrail.transaction_id = version.id
+           version.transaction_id = version.id
+           version.save
+        end
+      end
+
+      def reset_transaction_id
+        PaperTrail.transaction_id = nil
+      end
+
       def merge_metadata(data)
         # First we merge the model-level metadata in `meta`.
         paper_trail_options[:meta].each do |k,v|
@@ -323,8 +472,9 @@ module PaperTrail
             if v.respond_to?(:call)
               v.call(self)
             elsif v.is_a?(Symbol) && respond_to?(v)
-              # if it is an attribute that is changing, be sure to grab the current version
-              if has_attribute?(v) && send("#{v}_changed?".to_sym)
+              # If it is an attribute that is changing in an existing object,
+              # be sure to grab the current version.
+              if has_attribute?(v) && send("#{v}_changed?".to_sym) && data[:event] != 'create'
                 send("#{v}_was".to_sym)
               else
                 send(v)
@@ -333,19 +483,14 @@ module PaperTrail
               v
             end
         end
+
         # Second we merge any extra data from the controller (if available).
         data.merge(PaperTrail.controller_info || {})
       end
 
-      def item_before_change
-        previous = self.dup
-        # `dup` clears timestamps so we add them back.
-        all_timestamp_attributes.each do |column|
-          previous[column] = send(column) if self.class.column_names.include?(column.to_s) and not send(column).nil?
-        end
-        enums = previous.respond_to?(:defined_enums) ? previous.defined_enums : {}
-        previous.tap do |prev|
-          prev.id = id # `dup` clears the `id` so we add that back
+      def attributes_before_change
+        attributes.tap do |prev|
+          enums = self.respond_to?(:defined_enums) ? self.defined_enums : {}
           changed_attributes.select { |k,v| self.class.column_names.include?(k) }.each do |attr, before|
             before = enums[attr][before] if enums[attr]
             prev[attr] = before
@@ -353,28 +498,38 @@ module PaperTrail
         end
       end
 
-      # returns hash of object attributes (with appropriate attributes serialized), ommitting attributes to be skipped
-      def object_attrs_for_paper_trail(object)
-        _attrs = object.attributes.except(*self.paper_trail_options[:skip]).tap do |attributes|
-          self.class.serialize_attributes_for_paper_trail(attributes)
-        end
+      # Returns hash of attributes (with appropriate attributes serialized),
+      # ommitting attributes to be skipped.
+      def object_attrs_for_paper_trail(attributes_hash)
+        attrs = attributes_hash.except(*self.paper_trail_options[:skip])
+        self.class.serialize_attributes_for_paper_trail!(attrs)
+        attrs
       end
 
-      # This method is invoked in order to determine whether it is appropriate to generate a new version instance.
-      # In ActiveRecord 4, the way ActiveModel::Dirty handles the `changes` hash has changed so that
-      # `timestamp_attributes_for_update` get inserted PRIOR to the persistence happening, so we must accomodate
-      # this by checking to ensure attributes other than those ignored and update timestamps are really being modified.
+      # Determines whether it is appropriate to generate a new version
+      # instance. A timestamp-only update (e.g. only `updated_at` changed) is
+      # considered notable unless an ignored attribute was also changed.
       def changed_notably?
-        if self.paper_trail_options[:ignore].any? && (changed & self.paper_trail_options[:ignore]).any?
-          (notably_changed - timestamp_attributes_for_update_in_model.map(&:to_s)).any?
+        if ignored_attr_has_changed?
+          timestamps = timestamp_attributes_for_update_in_model.map(&:to_s)
+          (notably_changed - timestamps).any?
         else
           notably_changed.any?
         end
       end
 
+      # An attributed is "ignored" if it is listed in the `:ignore` option
+      # and/or the `:skip` option.  Returns true if an ignored attribute has
+      # changed.
+      def ignored_attr_has_changed?
+        ignored = self.paper_trail_options[:ignore] + self.paper_trail_options[:skip]
+        ignored.any? && (changed & ignored).any?
+      end
+
       def notably_changed
         only = self.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
+        # 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(self) }
         end
@@ -383,7 +538,8 @@ module PaperTrail
 
       def changed_and_not_ignored
         ignore = self.paper_trail_options[:ignore].dup
-         # remove Hash arguments and then evaluate whether the attributes (the keys of the hash) should also get pushed into the collection
+        # Remove Hash arguments and then evaluate whether the attributes (the
+        # keys of the hash) should also get pushed into the collection.
         ignore.delete_if do |obj|
           obj.is_a?(Hash) && obj.each { |attr, condition| ignore << attr if condition.respond_to?(:call) && condition.call(self) }
         end