PaperTrail Documentation

In PaperTrail, serialization is the process of preparing data for storage in the versions table, specifically for the object and object_changes columns.

Deserialization is the reverse process: handling data after it has been read from the database, such as when preparing the results of VersionConcern#changeset.

If you do not want to track which user made changes and want to suppress the warning stating that whodunnit has not been set, override the user_for_paper_trail method in your ApplicationController to return nil.

# in application_controller.rb
def user_for_paper_trail
  nil # disable whodunnit tracking
end

If using test runners like Spork, Zeus, or Spring, you must manually require the PaperTrail framework helpers within your prefork block or test helper to ensure they are loaded correctly.

# spec/rails_helper.rb
require 'spork'

Spork.prefork do
  ENV["RAILS_ENV"] ||= 'test'
  require 'spec_helper'
  require File.expand_path("../../config/environment", __FILE__)
  require 'rspec/rails'
  require 'paper_trail/frameworks/rspec'
  require 'paper_trail/frameworks/cucumber'
end

To avoid the security complexities and configuration requirements of YAML.safe_load, it is recommended to switch from the YAML serializer to JSON.

Users with PostgreSQL should consider using json(b) columns. Users with other databases can use JSON stored in a text column. This change makes you unaffected by the YAML.safe_load security updates applied in PaperTrail 13 and 14.

To speed up tests, you can disable PaperTrail globally for the entire Ruby process in your test environment configuration. To enable versioning for specific tests, implement a with_versioning helper method in your test_helper.rb that toggles PaperTrail.enabled and PaperTrail.request.enabled.

# in config/environments/test.rb
config.after_initialize do
  PaperTrail.enabled = false
end

# in test/test_helper.rb
def with_versioning
  was_enabled = PaperTrail.enabled?
  was_enabled_for_request = PaperTrail.request.enabled?
  PaperTrail.enabled = true
  PaperTrail.request.enabled = true
  begin
    yield
  ensure
    PaperTrail.enabled = was_enabled
    PaperTrail.request.enabled = was_enabled_for_request
  end
end

# usage
test 'something that needs versioning' do
  with_versioning do
    # your test
  end
end

Run the paper_trail:install generator to create a migration file for the versions table. The generator does not run the migration automatically; you must run it manually.

You can optionally provide a custom version class name as an argument.

bin/rails generate paper_trail:install [VERSION_CLASS_NAME] [options]

To use PaperTrail with Cucumber, require paper_trail/frameworks/cucumber in your features/support/env.rb. By default, PaperTrail will be disabled for all scenarios. To enable it for a specific scenario, wrap the code in a with_versioning block within a step definition.

# features/support/env.rb
ENV["RAILS_ENV"] ||= 'cucumber'
require File.expand_path(File.dirname(__FILE__) + '/../../config/environment')
# ...
require 'paper_trail/frameworks/cucumber'

# usage in step definition
Given /I want versioning on my model/ do
  with_versioning do
    # PaperTrail will be turned on for all code inside of this block
  end
end

To track specific attribute changes, add an object_changes column to your versions table. PaperTrail will then store the diff in each version.

As of version 10.0.0, changes are stored for create, update, and destroy events. The changeset method on a version record reads this column and returns a hash of the changes (e.g., {'attribute' => [old_value, new_value]}).

Note: PaperTrail stores full object snapshots, not diffs, to ensure each version is self-contained and independent.