paper_trail 4.2.0 → 7.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e7937d44654d4f77422ffe61d4bc2d81b7ed4026
-  data.tar.gz: 9ec1f8bc013795818775e58e1cd9c33e5dd36499
+  metadata.gz: 4882c535d132836d08cb122573826e8325286d5e
+  data.tar.gz: 629910ced4c4c38c6c2f6b5e1c695c2ca9c62057
 SHA512:
-  metadata.gz: e546ad5e910cc2a08aeaaf0dca6754e05f3a89fbfb022b49a078025e09a623e359a552c2e52f3126c84662fad2cd804c34db709689211852ff43e32ff40db3a1
-  data.tar.gz: 0ef05118041333567e076bc8407330917cc36ec5d23aec22fd6dced9367b10a466c4284eccddbb3f4d0675c4154165f24097eafe4acf0135e133c426a2b71d4b
+  metadata.gz: 042dfb1f7c98f3cb8e2fd153e28751282296e8e80a533a3f8a0afa06364c2bf6f7752b3500bd402b663d8b06acd574b8f8384a3cc2624f8633b7294398b416a9
+  data.tar.gz: 20c950e1a32aead04e4baacfb9be6d2a2694f0eaf626f6111b456907eac4ae2b3f7f4f8f13dff18294504680fb88af0a46f2ed4a36808faf8fd741d2af2f4ee5

data/lib/generators/paper_trail/install_generator.rb

@@ -1,40 +1,114 @@
-require 'rails/generators'
-require 'rails/generators/active_record'
+require "rails/generators"
+require "rails/generators/active_record"
 
 module PaperTrail
+  # Installs PaperTrail in a rails app.
   class InstallGenerator < ::Rails::Generators::Base
     include ::Rails::Generators::Migration
 
-    source_root File.expand_path('../templates', __FILE__)
-    class_option :with_changes, :type => :boolean, :default => false,
-      :desc => "Store changeset (diff) with each version"
-    class_option :with_associations, :type => :boolean, :default => false,
-      :desc => "Store transactional IDs to support association restoration"
+    # Class names of MySQL adapters.
+    # - `MysqlAdapter` - Used by gems: `mysql`, `activerecord-jdbcmysql-adapter`.
+    # - `Mysql2Adapter` - Used by `mysql2` gem.
+    MYSQL_ADAPTERS = [
+      "ActiveRecord::ConnectionAdapters::MysqlAdapter",
+      "ActiveRecord::ConnectionAdapters::Mysql2Adapter"
+    ].freeze
 
-    desc 'Generates (but does not run) a migration to add a versions table.'
+    source_root File.expand_path("../templates", __FILE__)
+    class_option(
+      :with_changes,
+      type: :boolean,
+      default: false,
+      desc: "Store changeset (diff) with each version"
+    )
+    class_option(
+      :with_associations,
+      type: :boolean,
+      default: false,
+      desc: "Store transactional IDs to support association restoration"
+    )
+
+    desc "Generates (but does not run) a migration to add a versions table." \
+         "  Also generates an initializer file for configuring PaperTrail"
 
     def create_migration_file
-      add_paper_trail_migration('create_versions')
-      add_paper_trail_migration('add_object_changes_to_versions') if options.with_changes?
+      add_paper_trail_migration("create_versions")
+      add_paper_trail_migration("add_object_changes_to_versions") if options.with_changes?
       if options.with_associations?
-        add_paper_trail_migration('create_version_associations')
-        add_paper_trail_migration('add_transaction_id_column_to_versions')
+        add_paper_trail_migration("create_version_associations")
+        add_paper_trail_migration("add_transaction_id_column_to_versions")
       end
     end
 
+    def create_initializer
+      create_file(
+        "config/initializers/paper_trail.rb",
+        "PaperTrail.config.track_associations = #{!!options.with_associations?}"
+      )
+    end
+
     def self.next_migration_number(dirname)
       ::ActiveRecord::Generators::Base.next_migration_number(dirname)
     end
 
     protected
+
     def add_paper_trail_migration(template)
-      migration_dir = File.expand_path('db/migrate')
+      migration_dir = File.expand_path("db/migrate")
+      if self.class.migration_exists?(migration_dir, template)
+        ::Kernel.warn "Migration already exists: #{template}"
+      else
+        migration_template(
+          "#{template}.rb.erb",
+          "db/migrate/#{template}.rb",
+          item_type_options: item_type_options,
+          migration_version: migration_version,
+          versions_table_options: versions_table_options
+        )
+      end
+    end
+
+    private
+
+    # MySQL 5.6 utf8mb4 limit is 191 chars for keys used in indexes.
+    # See https://github.com/airblade/paper_trail/issues/651
+    def item_type_options
+      opt = { null: false }
+      opt[:limit] = 191 if mysql?
+      ", #{opt}"
+    end
+
+    def migration_version
+      major = ActiveRecord::VERSION::MAJOR
+      if major >= 5
+        "[#{major}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+
+    def mysql?
+      MYSQL_ADAPTERS.include?(ActiveRecord::Base.connection.class.name)
+    end
 
-      unless self.class.migration_exists?(migration_dir, template)
-        migration_template "#{template}.rb", "db/migrate/#{template}.rb"
+    # Even modern versions of MySQL still use `latin1` as the default character
+    # encoding. Many users are not aware of this, and run into trouble when they
+    # try to use PaperTrail in apps that otherwise tend to use UTF-8. Postgres, by
+    # comparison, uses UTF-8 except in the unusual case where the OS is configured
+    # with a custom locale.
+    #
+    # - https://dev.mysql.com/doc/refman/5.7/en/charset-applications.html
+    # - http://www.postgresql.org/docs/9.4/static/multibyte.html
+    #
+    # Furthermore, MySQL's original implementation of UTF-8 was flawed, and had
+    # to be fixed later by introducing a new charset, `utf8mb4`.
+    #
+    # - https://mathiasbynens.be/notes/mysql-utf8mb4
+    # - https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html
+    #
+    def versions_table_options
+      if mysql?
+        ', { options: "ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci" }'
       else
-        warn("ALERT: Migration already exists named '#{template}'." +
-               " Please check your migrations directory before re-running")
+        ""
       end
     end
   end

data/lib/generators/paper_trail/templates/add_object_changes_to_versions.rb.erb

@@ -0,0 +1,12 @@
+# This migration adds the optional `object_changes` column, in which PaperTrail
+# will store the `changes` diff for each update event. See the readme for
+# details.
+class AddObjectChangesToVersions < ActiveRecord::Migration<%= migration_version %>
+  # The largest text column available in all supported RDBMS.
+  # See `create_versions.rb` for details.
+  TEXT_BYTES = 1_073_741_823
+
+  def change
+    add_column :versions, :object_changes, :text, limit: TEXT_BYTES
+  end
+end

data/lib/generators/paper_trail/templates/{add_transaction_id_column_to_versions.rb → add_transaction_id_column_to_versions.rb.erb}

@@ -1,4 +1,6 @@
-class AddTransactionIdColumnToVersions < ActiveRecord::Migration
+# This migration and CreateVersionAssociations provide the necessary
+# schema for tracking associations.
+class AddTransactionIdColumnToVersions < ActiveRecord::Migration<%= migration_version %>
   def self.up
     add_column :versions, :transaction_id, :integer
     add_index :versions, [:transaction_id]

data/lib/generators/paper_trail/templates/create_version_associations.rb.erb

@@ -0,0 +1,22 @@
+# This migration and AddTransactionIdColumnToVersions provide the necessary
+# schema for tracking associations.
+class CreateVersionAssociations < ActiveRecord::Migration<%= migration_version %>
+  def self.up
+    create_table :version_associations do |t|
+      t.integer  :version_id
+      t.string   :foreign_key_name, null: false
+      t.integer  :foreign_key_id
+    end
+    add_index :version_associations, [:version_id]
+    add_index :version_associations,
+      %i(foreign_key_name foreign_key_id),
+      name: "index_version_associations_on_foreign_key"
+  end
+
+  def self.down
+    remove_index :version_associations, [:version_id]
+    remove_index :version_associations,
+      name: "index_version_associations_on_foreign_key"
+    drop_table :version_associations
+  end
+end

data/lib/generators/paper_trail/templates/{create_versions.rb → create_versions.rb.erb}

@@ -1,4 +1,6 @@
-class CreateVersions < ActiveRecord::Migration
+# This migration creates the `versions` table, the only schema PT requires.
+# All other migrations PT provides are optional.
+class CreateVersions < ActiveRecord::Migration<%= migration_version %>
 
   # The largest text column available in all supported RDBMS is
   # 1024^3 - 1 bytes, roughly one gibibyte.  We specify a size
@@ -7,12 +9,12 @@ class CreateVersions < ActiveRecord::Migration
   TEXT_BYTES = 1_073_741_823
 
   def change
-    create_table :versions do |t|
-      t.string   :item_type, :null => false
-      t.integer  :item_id,   :null => false
-      t.string   :event,     :null => false
+    create_table :versions<%= versions_table_options %> do |t|
+      t.string   :item_type<%= item_type_options %>
+      t.integer  :item_id,   null: false
+      t.string   :event,     null: false
       t.string   :whodunnit
-      t.text     :object,    :limit => TEXT_BYTES
+      t.text     :object, limit: TEXT_BYTES
 
       # Known issue in MySQL: fractional second precision
       # -------------------------------------------------
@@ -29,6 +31,6 @@ class CreateVersions < ActiveRecord::Migration
       #
       t.datetime :created_at
     end
-    add_index :versions, [:item_type, :item_id]
+    add_index :versions, %i(item_type item_id)
   end
 end

data/lib/paper_trail.rb

@@ -1,151 +1,184 @@
-require 'request_store'
-
-# Require files in lib/paper_trail, but not its subdirectories.
-Dir[File.join(File.dirname(__FILE__), 'paper_trail', '*.rb')].each do |file|
-  require File.join('paper_trail', File.basename(file, '.rb'))
-end
-
-# Require serializers
-Dir[File.join(File.dirname(__FILE__), 'paper_trail', 'serializers', '*.rb')].each do |file|
-  require File.join('paper_trail', 'serializers', File.basename(file, '.rb'))
-end
-
+require "request_store"
+require "paper_trail/cleaner"
+require "paper_trail/config"
+require "paper_trail/has_paper_trail"
+require "paper_trail/record_history"
+require "paper_trail/reifier"
+require "paper_trail/version_association_concern"
+require "paper_trail/version_concern"
+require "paper_trail/version_number"
+require "paper_trail/serializers/json"
+require "paper_trail/serializers/yaml"
+
+# An ActiveRecord extension that tracks changes to your models, for auditing or
+# versioning.
 module PaperTrail
   extend PaperTrail::Cleaner
 
-  # Switches PaperTrail on or off.
-  def self.enabled=(value)
-    PaperTrail.config.enabled = value
-  end
-
-  # Returns `true` if PaperTrail is on, `false` otherwise.
-  # PaperTrail is enabled by default.
-  def self.enabled?
-    !!PaperTrail.config.enabled
-  end
-
-  def self.serialized_attributes?
-    ActiveSupport::Deprecation.warn(
-      "PaperTrail.serialized_attributes? is deprecated without replacement " +
-        "and always returns false."
-    )
-    false
-  end
-
-  # Sets whether PaperTrail is enabled or disabled for the current request.
-  def self.enabled_for_controller=(value)
-    paper_trail_store[:request_enabled_for_controller] = value
-  end
-
-  # Returns `true` if PaperTrail is enabled for the request, `false` otherwise.
-  #
-  # See `PaperTrail::Rails::Controller#paper_trail_enabled_for_controller`.
-  def self.enabled_for_controller?
-    !!paper_trail_store[:request_enabled_for_controller]
-  end
-
-  # Sets whether PaperTrail is enabled or disabled for this model in the
-  # current request.
-  def self.enabled_for_model(model, value)
-    paper_trail_store[:"enabled_for_#{model}"] = value
-  end
-
-  # Returns `true` if PaperTrail is enabled for this model in the current
-  # request, `false` otherwise.
-  def self.enabled_for_model?(model)
-    !!paper_trail_store.fetch(:"enabled_for_#{model}", true)
-  end
-
-  # Set the field which records when a version was created.
-  def self.timestamp_field=(field_name)
-    PaperTrail.config.timestamp_field = field_name
-  end
-
-  # Returns the field which records when a version was created.
-  def self.timestamp_field
-    PaperTrail.config.timestamp_field
-  end
-
-  # Sets who is responsible for any changes that occur. You would normally use
-  # this in a migration or on the console, when working with models directly.
-  # In a controller it is set automatically to the `current_user`.
-  def self.whodunnit=(value)
-    paper_trail_store[:whodunnit] = value
-  end
-
-  # Returns who is reponsible for any changes that occur.
-  def self.whodunnit
-    paper_trail_store[:whodunnit]
-  end
-
-  # Sets any information from the controller that you want PaperTrail to
-  # store.  By default this is set automatically by a before filter.
-  def self.controller_info=(value)
-    paper_trail_store[:controller_info] = value
-  end
-
-  # Returns any information from the controller that you want
-  # PaperTrail to store.
-  #
-  # See `PaperTrail::Rails::Controller#info_for_paper_trail`.
-  def self.controller_info
-    paper_trail_store[:controller_info]
-  end
-
-  # Getter and Setter for PaperTrail Serializer
-  def self.serializer=(value)
-    PaperTrail.config.serializer = value
-  end
-
-  def self.serializer
-    PaperTrail.config.serializer
-  end
-
-  def self.active_record_protected_attributes?
-    @active_record_protected_attributes ||= ::ActiveRecord::VERSION::MAJOR < 4 ||
-      !!defined?(ProtectedAttributes)
-  end
-
-  def self.transaction?
-    ::ActiveRecord::Base.connection.open_transactions > 0
-  end
-
-  def self.transaction_id
-    paper_trail_store[:transaction_id]
-  end
-
-  def self.transaction_id=(id)
-    paper_trail_store[:transaction_id] = id
-  end
-
-  private
-
-  # Thread-safe hash to hold PaperTrail's data. Initializing with needed
-  # default values.
-  def self.paper_trail_store
-    RequestStore.store[:paper_trail] ||= { :request_enabled_for_controller => true }
-  end
-
-  # Returns PaperTrail's configuration object.
-  def self.config
-    @config ||= PaperTrail::Config.instance
-    yield @config if block_given?
-    @config
-  end
-
   class << self
-    alias_method :configure, :config
-  end
-end
-
-# Ensure `ProtectedAttributes` gem gets required if it is available before the
-# `Version` class gets loaded in.
-unless PaperTrail.active_record_protected_attributes?
-  PaperTrail.send(:remove_instance_variable, :@active_record_protected_attributes)
-  begin
-    require 'protected_attributes'
-  rescue LoadError
-    # In case `ProtectedAttributes` gem is not available.
+    # @api private
+    def clear_transaction_id
+      self.transaction_id = nil
+    end
+
+    # Switches PaperTrail on or off.
+    # @api public
+    def enabled=(value)
+      PaperTrail.config.enabled = value
+    end
+
+    # Returns `true` if PaperTrail is on, `false` otherwise.
+    # PaperTrail is enabled by default.
+    # @api public
+    def enabled?
+      !!PaperTrail.config.enabled
+    end
+
+    # Sets whether PaperTrail is enabled or disabled for the current request.
+    # @api public
+    def enabled_for_controller=(value)
+      paper_trail_store[:request_enabled_for_controller] = value
+    end
+
+    # Returns `true` if PaperTrail is enabled for the request, `false` otherwise.
+    #
+    # See `PaperTrail::Rails::Controller#paper_trail_enabled_for_controller`.
+    # @api public
+    def enabled_for_controller?
+      !!paper_trail_store[:request_enabled_for_controller]
+    end
+
+    # Sets whether PaperTrail is enabled or disabled for this model in the
+    # current request.
+    # @api public
+    def enabled_for_model(model, value)
+      paper_trail_store[:"enabled_for_#{model}"] = value
+    end
+
+    # Returns `true` if PaperTrail is enabled for this model in the current
+    # request, `false` otherwise.
+    # @api public
+    def enabled_for_model?(model)
+      !!paper_trail_store.fetch(:"enabled_for_#{model}", true)
+    end
+
+    # Returns a `::Gem::Version`, convenient for comparisons. This is
+    # recommended over `::PaperTrail::VERSION::STRING`.
+    # @api public
+    def gem_version
+      ::Gem::Version.new(VERSION::STRING)
+    end
+
+    # Set the field which records when a version was created.
+    # @api public
+    def timestamp_field=(_field_name)
+      raise(
+        "PaperTrail.timestamp_field= has been removed, without replacement. " \
+          "It is no longer configurable. The timestamp field in the versions table " \
+          "must now be named created_at."
+      )
+    end
+
+    # Sets who is responsible for any changes that occur. You would normally use
+    # this in a migration or on the console, when working with models directly.
+    # In a controller it is set automatically to the `current_user`.
+    # @api public
+    def whodunnit=(value)
+      paper_trail_store[:whodunnit] = value
+    end
+
+    # If nothing passed, returns who is reponsible for any changes that occur.
+    #
+    #   PaperTrail.whodunnit = "someone"
+    #   PaperTrail.whodunnit # => "someone"
+    #
+    # If value and block passed, set this value as whodunnit for the duration of the block
+    #
+    #   PaperTrail.whodunnit("me") do
+    #     puts PaperTrail.whodunnit # => "me"
+    #   end
+    #
+    # @api public
+    def whodunnit(value = nil)
+      if value
+        raise ArgumentError, "no block given" unless block_given?
+
+        previous_whodunnit = paper_trail_store[:whodunnit]
+        paper_trail_store[:whodunnit] = value
+
+        begin
+          yield
+        ensure
+          paper_trail_store[:whodunnit] = previous_whodunnit
+        end
+      elsif paper_trail_store[:whodunnit].respond_to?(:call)
+        paper_trail_store[:whodunnit].call
+      else
+        paper_trail_store[:whodunnit]
+      end
+    end
+
+    # Sets any information from the controller that you want PaperTrail to
+    # store.  By default this is set automatically by a before filter.
+    # @api public
+    def controller_info=(value)
+      paper_trail_store[:controller_info] = value
+    end
+
+    # Returns any information from the controller that you want
+    # PaperTrail to store.
+    #
+    # See `PaperTrail::Rails::Controller#info_for_paper_trail`.
+    # @api public
+    def controller_info
+      paper_trail_store[:controller_info]
+    end
+
+    # Getter and Setter for PaperTrail Serializer
+    # @api public
+    def serializer=(value)
+      PaperTrail.config.serializer = value
+    end
+
+    # @api public
+    def serializer
+      PaperTrail.config.serializer
+    end
+
+    # @api public
+    def transaction?
+      ::ActiveRecord::Base.connection.open_transactions > 0
+    end
+
+    # @api public
+    def transaction_id
+      paper_trail_store[:transaction_id]
+    end
+
+    # @api public
+    def transaction_id=(id)
+      paper_trail_store[:transaction_id] = id
+    end
+
+    # Thread-safe hash to hold PaperTrail's data. Initializing with needed
+    # default values.
+    # @api private
+    def paper_trail_store
+      RequestStore.store[:paper_trail] ||= { request_enabled_for_controller: true }
+    end
+
+    # Returns PaperTrail's configuration object.
+    # @api private
+    def config
+      @config ||= PaperTrail::Config.instance
+      yield @config if block_given?
+      @config
+    end
+    alias configure config
+
+    def version
+      VERSION::STRING
+    end
   end
 end
 
@@ -154,9 +187,8 @@ ActiveSupport.on_load(:active_record) do
 end
 
 # Require frameworks
-require 'paper_trail/frameworks/sinatra'
-if defined?(::Rails) && ActiveRecord::VERSION::STRING >= '3.2'
-  require 'paper_trail/frameworks/rails'
+if defined?(::Rails) && ActiveRecord::VERSION::STRING >= "3.2"
+  require "paper_trail/frameworks/rails"
 else
-  require 'paper_trail/frameworks/active_record'
+  require "paper_trail/frameworks/active_record"
 end