paper_trail 4.2.0 → 7.1.3

data/lib/paper_trail/attribute_serializers/README.md

@@ -0,0 +1,10 @@
+Attribute Serializers
+=====================
+
+"Serialization" here refers to the preparation of data for insertion into a
+database, particularly the `object` and `object_changes` columns in the
+`versions` table.
+
+Likewise, "deserialization" refers to any processing of data after they
+have been read from the database, for example preparing the result of
+`VersionConcern#changeset`.

data/lib/paper_trail/attribute_serializers/cast_attribute_serializer.rb

@@ -0,0 +1,80 @@
+module PaperTrail
+  # :nodoc:
+  module AttributeSerializers
+    # 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. In older versions of rails, we shim this method
+    # with `LegacyActiveRecordShim`.
+    class CastAttributeSerializer
+      def initialize(klass)
+        @klass = klass
+      end
+
+      private
+
+      # Returns a hash mapping attributes to hashes that map strings to
+      # integers. Example:
+      #
+      # ```
+      # { "status" => { "draft"=>0, "published"=>1, "archived"=>2 } }
+      # ```
+      #
+      # ActiveRecord::Enum was added in AR 4.1
+      # http://edgeguides.rubyonrails.org/4_1_release_notes.html#active-record-enums
+      def defined_enums
+        @defined_enums ||= (@klass.respond_to?(:defined_enums) ? @klass.defined_enums : {})
+      end
+    end
+
+    if ::ActiveRecord::VERSION::MAJOR >= 5
+      # This implementation uses AR 5's `serialize` and `deserialize`.
+      class CastAttributeSerializer
+        def serialize(attr, val)
+          @klass.type_for_attribute(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
+          else
+            @klass.type_for_attribute(attr).deserialize(val)
+          end
+        end
+      end
+    else
+      # This implementation uses AR 4.2's `type_cast_for_database`. For
+      # versions of AR < 4.2 we provide an implementation of
+      # `type_cast_for_database` in our shim attribute type classes,
+      # `NoOpAttribute` and `SerializedAttribute`.
+      class CastAttributeSerializer
+        def serialize(attr, val)
+          castable_val = val
+          if defined_enums[attr]
+            # `attr` is an enum. Find the number that corresponds to `val`. If `val` is
+            # a number already, there won't be a corresponding entry, just use `val`.
+            castable_val = defined_enums[attr][val] || val
+          end
+          @klass.type_for_attribute(attr).type_cast_for_database(castable_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
+          else
+            val = @klass.type_for_attribute(attr).type_cast_from_database(val)
+            if defined_enums[attr]
+              defined_enums[attr].key(val)
+            else
+              val
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/attribute_serializers/legacy_active_record_shim.rb

@@ -0,0 +1,48 @@
+module PaperTrail
+  module AttributeSerializers
+    # Included into model if AR version is < 4.2. Backport Rails 4.2 and later's
+    # `type_for_attribute` so we can build on a common interface.
+    module LegacyActiveRecordShim
+      # An attribute which needs no processing. It is part of our backport (shim)
+      # of rails 4.2's attribute API. See `type_for_attribute` below.
+      class NoOpAttribute
+        def type_cast_for_database(value)
+          value
+        end
+
+        def type_cast_from_database(data)
+          data
+        end
+      end
+      NO_OP_ATTRIBUTE = NoOpAttribute.new
+
+      # An attribute which requires manual (de)serialization to/from what we get
+      # from the database. It is part of our backport (shim) of rails 4.2's
+      # attribute API. See `type_for_attribute` below.
+      class SerializedAttribute
+        def initialize(coder)
+          @coder = coder.respond_to?(:dump) ? coder : PaperTrail.serializer
+        end
+
+        def type_cast_for_database(value)
+          @coder.dump(value)
+        end
+
+        def type_cast_from_database(data)
+          @coder.load(data)
+        end
+      end
+
+      def type_for_attribute(attr_name)
+        serialized_attribute_types[attr_name.to_s] || NO_OP_ATTRIBUTE
+      end
+
+      def serialized_attribute_types
+        @attribute_types ||= Hash[serialized_attributes.map do |attr_name, coder|
+          [attr_name, SerializedAttribute.new(coder)]
+        end]
+      end
+      private :serialized_attribute_types
+    end
+  end
+end

data/lib/paper_trail/attribute_serializers/object_attribute.rb

@@ -0,0 +1,39 @@
+require "paper_trail/attribute_serializers/cast_attribute_serializer"
+
+module PaperTrail
+  module AttributeSerializers
+    # Serialize or deserialize the `version.object` column.
+    class ObjectAttribute
+      def initialize(model_class)
+        @model_class = model_class
+      end
+
+      def serialize(attributes)
+        alter(attributes, :serialize)
+      end
+
+      def deserialize(attributes)
+        alter(attributes, :deserialize)
+      end
+
+      private
+
+      # Modifies `attributes` in place.
+      # TODO: Return a new hash instead.
+      def alter(attributes, serialization_method)
+        # Don't serialize before values before inserting into columns of type
+        # `JSON` on `PostgreSQL` databases.
+        return attributes if object_col_is_json?
+
+        serializer = CastAttributeSerializer.new(@model_class)
+        attributes.each do |key, value|
+          attributes[key] = serializer.send(serialization_method, key, value)
+        end
+      end
+
+      def object_col_is_json?
+        @model_class.paper_trail.version_class.object_col_is_json?
+      end
+    end
+  end
+end

data/lib/paper_trail/attribute_serializers/object_changes_attribute.rb

@@ -0,0 +1,42 @@
+require "paper_trail/attribute_serializers/cast_attribute_serializer"
+
+module PaperTrail
+  module AttributeSerializers
+    # Serialize or deserialize the `version.object_changes` column.
+    class ObjectChangesAttribute
+      def initialize(item_class)
+        @item_class = item_class
+      end
+
+      def serialize(changes)
+        alter(changes, :serialize)
+      end
+
+      def deserialize(changes)
+        alter(changes, :deserialize)
+      end
+
+      private
+
+      # Modifies `changes` in place.
+      # TODO: Return a new hash instead.
+      def alter(changes, serialization_method)
+        # Don't serialize before values before inserting into columns of type
+        # `JSON` on `PostgreSQL` databases.
+        return changes if object_changes_col_is_json?
+
+        serializer = CastAttributeSerializer.new(@item_class)
+        changes.clone.each do |key, change|
+          # `change` is an Array with two elements, representing before and after.
+          changes[key] = Array(change).map do |value|
+            serializer.send(serialization_method, key, value)
+          end
+        end
+      end
+
+      def object_changes_col_is_json?
+        @item_class.paper_trail.version_class.object_changes_col_is_json?
+      end
+    end
+  end
+end

data/lib/paper_trail/cleaner.rb

@@ -1,4 +1,5 @@
 module PaperTrail
+  # Utilities for deleting version records.
   module Cleaner
     # Destroys all but the most recent version(s) for items on a given date
     # (or on all dates). Useful for deleting drafts.
@@ -6,7 +7,8 @@ module PaperTrail
     # Options:
     #
     # - :keeping - An `integer` indicating the number of versions to be kept for
-    #   each item per date. Defaults to `1`.
+    #   each item per date. Defaults to `1`. The most recent matching versions
+    #   are kept.
     # - :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`.
@@ -14,13 +16,13 @@ module PaperTrail
     #   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|
-        group_versions_by_date(versions).each do |date, _versions|
+      options = { keeping: 1, date: :all }.merge(options)
+      gather_versions(options[:item_id], options[:date]).each do |_item_id, item_versions|
+        group_versions_by_date(item_versions).each do |_date, 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)
+          date_versions.pop(options[:keeping])
+          date_versions.map(&:destroy)
         end
       end
     end
@@ -30,10 +32,14 @@ module PaperTrail
     # 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.
+    # that were created on specified date. Versions are returned in
+    # chronological order.
     def gather_versions(item_id = nil, date = :all)
-      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
+      unless date == :all || date.respond_to?(:to_date)
+        raise ArgumentError, "Expected date to be a Timestamp or :all"
+      end
+      versions = item_id ? PaperTrail::Version.where(item_id: item_id) : PaperTrail::Version
+      versions = versions.order(PaperTrail::Version.timestamp_sort_order)
       versions = versions.between(date.to_date, date.to_date + 1.day) unless date == :all
 
       # If `versions` has not been converted to an ActiveRecord::Relation yet,
@@ -46,7 +52,7 @@ module PaperTrail
     # versions.
     # @api private
     def group_versions_by_date(versions)
-      versions.group_by { |v| v.send(PaperTrail.timestamp_field).to_date }
+      versions.group_by { |v| v.created_at.to_date }
     end
   end
 end

data/lib/paper_trail/config.rb

@@ -1,47 +1,48 @@
-require 'singleton'
-require 'paper_trail/serializers/yaml'
+require "singleton"
+require "paper_trail/serializers/yaml"
 
 module PaperTrail
+  # Global configuration affecting all threads. Some thread-specific
+  # configuration can be found in `paper_trail.rb`, others in `controller.rb`.
   class Config
     include Singleton
-    attr_accessor :timestamp_field, :serializer, :version_limit
+    attr_accessor :serializer, :version_limit
     attr_writer :track_associations
 
     def initialize
-      @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
+      # Variables which affect all threads, whose access is synchronized.
+      @mutex = Mutex.new
+      @enabled = true
 
-    def serialized_attributes=(_)
-      ActiveSupport::Deprecation.warn(
-        "PaperTrail.config.serialized_attributes= is deprecated without " +
-          "replacement and no longer has any effect."
-      )
+      # Variables which affect all threads, whose access is *not* synchronized.
+      @serializer = PaperTrail::Serializers::YAML
     end
 
-    def track_associations
-      @track_associations.nil? ?
-        PaperTrail::VersionAssociation.table_exists? :
+    # Previously, we checked `PaperTrail::VersionAssociation.table_exists?`
+    # here, but that proved to be problematic in situations when the database
+    # connection had not been established, or when the database does not exist
+    # yet (as with `rake db:create`).
+    def track_associations?
+      if @track_associations.nil?
+        ActiveSupport::Deprecation.warn <<-EOS.strip_heredoc.gsub(/\s+/, " ")
+          PaperTrail.config.track_associations has not been set. As of PaperTrail 5, it
+          defaults to false. Tracking associations is an experimental feature so
+          we recommend setting PaperTrail.config.track_associations = false in
+          your config/initializers/paper_trail.rb
+        EOS
+        false
+      else
         @track_associations
+      end
     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
+      @mutex.synchronize { !!@enabled }
     end
 
-    def enabled= enable
-      PaperTrail.paper_trail_store[:paper_trail_enabled] = enable
+    def enabled=(enable)
+      @mutex.synchronize { @enabled = enable }
     end
   end
 end

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

@@ -1,6 +1,10 @@
-require 'paper_trail/version_concern'
+require "paper_trail/version_concern"
 
 module PaperTrail
+  # This is the default ActiveRecord model provided by PaperTrail. Most simple
+  # applications will only use this and its partner, `VersionAssociation`, but
+  # it is possible to sub-class, extend, or even do without this model entirely.
+  # See the readme for details.
   class Version < ::ActiveRecord::Base
     include PaperTrail::VersionConcern
   end

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

@@ -1,7 +1,11 @@
-require 'paper_trail/version_association_concern'
+require "paper_trail/version_association_concern"
 
 module PaperTrail
+  # This is the default ActiveRecord model provided by PaperTrail. Most simple
+  # applications will only use this and its partner, `Version`, but it is
+  # possible to sub-class, extend, or even do without this model entirely.
+  # See the readme for details.
   class VersionAssociation < ::ActiveRecord::Base
     include PaperTrail::VersionAssociationConcern
   end
-end
+end

data/lib/paper_trail/frameworks/cucumber.rb

@@ -8,6 +8,7 @@ end
 
 module PaperTrail
   module Cucumber
+    # Helper method for enabling PT in Cucumber features.
     module Extensions
       # :call-seq:
       # with_versioning

data/lib/paper_trail/frameworks/rails.rb

@@ -1,7 +1,2 @@
-require 'paper_trail/frameworks/rails/controller'
-require 'paper_trail/frameworks/rails/engine'
-
-module PaperTrail
-  module Rails
-  end
-end
+require "paper_trail/frameworks/rails/controller"
+require "paper_trail/frameworks/rails/engine"

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

@@ -1,24 +1,14 @@
 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`.
     module Controller
-
-      def self.included(base)
-        before = [
+      def self.included(controller)
+        controller.before_action(
           :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
@@ -76,6 +66,7 @@ module PaperTrail
 
       # Tells PaperTrail who is responsible for any changes that occur.
       def set_paper_trail_whodunnit
+        @set_paper_trail_whodunnit_called = true
         ::PaperTrail.whodunnit = user_for_paper_trail if ::PaperTrail.enabled_for_controller?
       end
 
@@ -85,10 +76,21 @@ module PaperTrail
         ::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."
+        )
+      end
     end
   end
+end
 
-  if defined?(::ActionController)
-    ::ActiveSupport.on_load(:action_controller) { include PaperTrail::Rails::Controller }
+if defined?(::ActionController)
+  ::ActiveSupport.on_load(:action_controller) do
+    include ::PaperTrail::Rails::Controller
   end
 end