paper_trail 4.2.0 → 5.0.0

data/lib/paper_trail/attributes_serialization.rb

@@ -1,5 +1,14 @@
 module PaperTrail
+  # "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`.
   module AttributesSerialization
+    # 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
@@ -11,6 +20,9 @@ module PaperTrail
     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
@@ -25,16 +37,72 @@ module PaperTrail
       end
     end
 
-    SERIALIZE, DESERIALIZE =
-      if ::ActiveRecord::VERSION::MAJOR >= 5
-        [:serialize, :deserialize]
-      else
-        [:type_cast_for_database, :type_cast_from_database]
+    # The `AbstractSerializer` (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
+    # below.
+    #
+    # At runtime, the `AbstractSerializer` has only one child class, the
+    # `CastedAttributeSerializer`, whose implementation varies depending on the
+    # version of ActiveRecord.
+    class AbstractSerializer
+      def initialize(klass)
+        @klass = klass
       end
 
-    if ::ActiveRecord::VERSION::STRING < '4.2'
-      # Backport Rails 4.2 and later's `type_for_attribute` to build
-      # on a common interface.
+      private
+
+      def apply_serialization(method, attr, val)
+        @klass.type_for_attribute(attr).send(method, val)
+      end
+    end
+
+    if ::ActiveRecord::VERSION::MAJOR >= 5
+      # This implementation uses AR 5's `serialize` and `deserialize`.
+      class CastedAttributeSerializer < AbstractSerializer
+        def serialize(attr, val)
+          apply_serialization(:serialize, attr, val)
+        end
+
+        def deserialize(attr, val)
+          apply_serialization(:deserialize, attr, val)
+        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 CastedAttributeSerializer < AbstractSerializer
+        def serialize(attr, val)
+          val = defined_enums[attr][val] if defined_enums[attr]
+          apply_serialization(:type_cast_for_database, attr, val)
+        end
+
+        def deserialize(attr, val)
+          val = apply_serialization(:type_cast_from_database, attr, val)
+
+          if defined_enums[attr]
+            defined_enums[attr].key(val)
+          else
+            val
+          end
+        end
+
+        private
+
+        def defined_enums
+          @defined_enums ||= (@klass.respond_to?(:defined_enums) ? @klass.defined_enums : {})
+        end
+      end
+    end
+
+    # Backport Rails 4.2 and later's `type_for_attribute` so we can build
+    # on a common interface.
+    if ::ActiveRecord::VERSION::STRING < "4.2"
       def type_for_attribute(attr_name)
         serialized_attribute_types[attr_name.to_s] || NO_OP_ATTRIBUTE
       end
@@ -49,40 +117,44 @@ module PaperTrail
 
     # Used for `Version#object` attribute.
     def serialize_attributes_for_paper_trail!(attributes)
-      alter_attributes_for_paper_trail!(SERIALIZE, attributes)
+      alter_attributes_for_paper_trail!(:serialize, attributes)
     end
 
     def unserialize_attributes_for_paper_trail!(attributes)
-      alter_attributes_for_paper_trail!(DESERIALIZE, attributes)
+      alter_attributes_for_paper_trail!(:deserialize, attributes)
     end
 
-    def alter_attributes_for_paper_trail!(serializer, attributes)
+    def alter_attributes_for_paper_trail!(serialization_method, attributes)
       # Don't serialize before values before inserting into columns of type
       # `JSON` on `PostgreSQL` databases.
       return attributes if paper_trail_version_class.object_col_is_json?
 
+      serializer = CastedAttributeSerializer.new(self)
       attributes.each do |key, value|
-        attributes[key] = type_for_attribute(key).send(serializer, value)
+        attributes[key] = serializer.send(serialization_method, key, value)
       end
     end
 
     # Used for Version#object_changes attribute.
     def serialize_attribute_changes_for_paper_trail!(changes)
-      alter_attribute_changes_for_paper_trail!(SERIALIZE, changes)
+      alter_attribute_changes_for_paper_trail!(:serialize, changes)
     end
 
     def unserialize_attribute_changes_for_paper_trail!(changes)
-      alter_attribute_changes_for_paper_trail!(DESERIALIZE, changes)
+      alter_attribute_changes_for_paper_trail!(:deserialize, changes)
     end
 
-    def alter_attribute_changes_for_paper_trail!(serializer, changes)
+    def alter_attribute_changes_for_paper_trail!(serialization_method, changes)
       # Don't serialize before values before inserting into columns of type
       # `JSON` on `PostgreSQL` databases.
       return changes if paper_trail_version_class.object_changes_col_is_json?
 
+      serializer = CastedAttributeSerializer.new(self)
       changes.clone.each do |key, change|
-        type = type_for_attribute(key)
-        changes[key] = Array(change).map { |value| type.send(serializer, value) }
+        # `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
   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,

data/lib/paper_trail/config.rb

@@ -1,15 +1,22 @@
-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_writer :track_associations
 
     def initialize
+      # Variables which affect all threads, whose access is synchronized.
+      @mutex = Mutex.new
+      @enabled = true
+
+      # Variables which affect all threads, whose access is *not* synchronized.
       @timestamp_field = :created_at
-      @serializer      = PaperTrail::Serializers::YAML
+      @serializer = PaperTrail::Serializers::YAML
     end
 
     def serialized_attributes
@@ -27,21 +34,31 @@ module PaperTrail
       )
     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.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.rb

@@ -2,3 +2,7 @@
 # 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"
+
+ActiveSupport.on_load(:active_record) do
+  include PaperTrail::Model
+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,23 +1,26 @@
 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 = [
           :set_paper_trail_enabled_for_controller,
-          :set_paper_trail_whodunnit,
           :set_paper_trail_controller_info
         ]
-        after = []
+        after = [
+          :warn_about_not_setting_whodunnit
+        ]
 
         if base.respond_to? :before_action
           # Rails 4+
-          before.map {|sym| base.before_action sym }
-          after.map  {|sym| base.after_action  sym }
+          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 }
+          before.map { |sym| base.before_filter sym }
+          after.map  { |sym| base.after_filter  sym }
         end
       end
 
@@ -76,6 +79,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 +89,26 @@ module PaperTrail
         ::PaperTrail.controller_info = info_for_paper_trail if ::PaperTrail.enabled_for_controller?
       end
 
+      def warn_about_not_setting_whodunnit
+        enabled = ::PaperTrail.enabled_for_controller?
+        user_present = user_for_paper_trail.present?
+        whodunnit_blank = ::PaperTrail.whodunnit.blank?
+        if enabled && user_present && whodunnit_blank && !@set_paper_trail_whodunnit_called
+          warn <<-EOS.strip_heredoc
+            user_for_paper_trail is present, but whodunnit has not been set.
+            PaperTrail no longer adds the set_paper_trail_whodunnit
+            before_filter for you. Please add this before_filter to your
+            ApplicationController to continue recording whodunnit. See the
+            PaperTrail readme for an example.
+          EOS
+        end
+      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

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

@@ -1,7 +1,13 @@
 module PaperTrail
   module Rails
+    # See http://guides.rubyonrails.org/engines.html
     class Engine < ::Rails::Engine
-      paths['app/models'] << 'lib/paper_trail/frameworks/active_record/models'
+      paths["app/models"] << "lib/paper_trail/frameworks/active_record/models"
+      config.paper_trail = ActiveSupport::OrderedOptions.new
+      initializer "paper_trail.initialisation" do |app|
+        ActiveRecord::Base.send :include, PaperTrail::Model
+        PaperTrail.enabled = app.config.paper_trail.fetch(:enabled, true)
+      end
     end
   end
 end

data/lib/paper_trail/frameworks/rspec.rb

@@ -1,6 +1,6 @@
-require 'rspec/core'
-require 'rspec/matchers'
-require 'paper_trail/frameworks/rspec/helpers'
+require "rspec/core"
+require "rspec/matchers"
+require "paper_trail/frameworks/rspec/helpers"
 
 RSpec.configure do |config|
   config.include ::PaperTrail::RSpec::Helpers::InstanceMethods
@@ -13,14 +13,14 @@ RSpec.configure do |config|
     ::PaperTrail.controller_info = {} if defined?(::Rails) && defined?(::RSpec::Rails)
   end
 
-  config.before(:each, :versioning => true) do
+  config.before(:each, versioning: true) do
     ::PaperTrail.enabled = true
   end
 end
 
 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) }
+  match { |actual| actual.is_a?(::PaperTrail::Model::InstanceMethods) }
 end
 
 RSpec::Matchers.define :have_a_version_with do |attributes|

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

@@ -1,6 +1,7 @@
 module PaperTrail
   module RSpec
     module Helpers
+      # Included in the RSpec configuration in `frameworks/rspec.rb`
       module InstanceMethods
         # enable versioning for specific blocks (at instance-level)
         def with_versioning
@@ -12,10 +13,11 @@ module PaperTrail
         end
       end
 
+      # Extended by the RSpec configuration in `frameworks/rspec.rb`
       module ClassMethods
         # enable versioning for specific blocks (at class-level)
         def with_versioning(&block)
-          context 'with versioning', :versioning => true do
+          context "with versioning", versioning: true do
             class_exec(&block)
           end
         end