paper_trail-actor 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5feb0e3bd1d5d354acc67d9da8ce59737cd5f9d2003aac8a06d6d97abe9a964d
-  data.tar.gz: 4c539f383eff32c652da404f3bf8edcc215cf3e1b1357b6d1566d0ad8abc37c0
+  metadata.gz: 8d8d84d52637e0114f5ab6c64b3caf0d10b2a94d6049d1e4c1ec0826d4dd94f4
+  data.tar.gz: fdabf9efe06ee201f706b17fc47fc75ffe590c57657c479b6b4bb1a26428eb94
 SHA512:
-  metadata.gz: 396ac19a6b0ec27b2bddbc46c58e34819d6a1761fc2acee5cff4b3e9143b939c3a0f0dda67c4463d8581d44ef9fbc79ba492326ba8d66ba2c0cb8e5e2ca357ce
-  data.tar.gz: e8077674949aa3d963b543d74c495edb6ccf975fb86821c8dc97ecc9db0527702ca5f412ee28b12849b8edf2701319cf89dee9dc3354415ffc9830ed46cf5912
+  metadata.gz: 50b13f56e781102f2c2da25054ea6530feff8d544a8320bc912157f4cb639f9a559ee6edc2166f58295aac8e7f7c716f06ea8f1abddc1fcf873a92f1e17ab3fd
+  data.tar.gz: ceec6f0626b24475afb00c413607491cb9456bab684a4ad835dc77798fbb3cf910a007c97e51ce5eb884dc176a2d03eb8828849704e5f5b3e342d5a6c054b8c2

data/CHANGELOG.md

@@ -52,3 +52,35 @@
 ### Fixed
 
 - None
+
+## [0.5.0] - 2025-04-29
+
+- Small improvements.
+
+### Breaking Changes
+
+- None
+
+### Added
+
+- [#12](https://github.com/tttffff/paper_trail-actor/pull/12) Default user for paper trail.
+  When using `#set_paper_trail_whodunnit`, the default `#user_for_paper_trail` is now the `#current_user` object, not it's `id`.
+
+### Fixed
+
+- [#10](https://github.com/tttffff/paper_trail-actor/pull/10) Allow other object types.
+  Can now use any object that implements globalid, not just ActiveRecord objects.
+ 
+## [0.5.1] - 2025-11-15
+
+### Breaking Changes
+
+- None
+
+### Added
+
+- None
+
+### Fixed
+
+- Explicitly set required ruby version.

data/README.md

@@ -1,82 +1,182 @@
 # PaperTrail-Actor
 
-Originally forked from the now unmaintained [paper_trail-globalid](https://github.com/ankit1910/paper_trail-globalid).
+Track changes in your Rails application with precision. PaperTrail-Actor extends [PaperTrail](https://github.com/paper-trail-gem/paper_trail) to store full ActiveRecord objects (not just IDs) as the actor responsible for changes.
 
-This gem is an extension to the [PaperTrail](https://github.com/paper-trail-gem/paper_trail) gem.
+**Problem it solves:** When both `Admin` and `User` models can modify records, storing only an ID makes it impossible to know which model type made the change. PaperTrail-Actor stores GlobalIDs to uniquely identify actors across different model types.
 
-- Allows setting an `ActiveRecord` object for the whodunnit field on the PaperTrail request object and version objects.
-- Adds the method `#actor` to the PaperTrail request object which returns the `ActiveRecord` object that will be responsible for subsequent changes.
-- Adds the method `#actor` to PaperTrail version objects which returns the `ActiveRecord` object that was responsible for change.
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Setup](#basic-setup)
+  - [Supported Object Types](#supported-object-types)
+  - [Controller Integration](#controller-integration)
+  - [Migrating Existing Data](#migrating-existing-data)
+- [How It Works](#how-it-works)
+
+## Features
+
+- **Store any ActiveRecord object** as the actor who made changes
+- **Retrieve the full object** with a simple `#actor` method
+- **Backward compatible** with existing PaperTrail versions
+- **Flexible** - works with strings, unpersisted records, and non-ActiveRecord objects
+
+## Requirements
+
+- Ruby 2.7+
+- Rails 6.0+
+- PaperTrail 11.0+
 
 ## Installation
 
-1. Add PaperTrail-Actor to your `Gemfile`.
+1. Add to your Gemfile:
   ```ruby
   gem "paper_trail-actor"
   ```
-2. And then execute:
+2. Install the gem:
   ```sh
   bundle install
   ```
 
-## Basic Usage
+## Usage
+
+### Basic Setup
 
-This gem works by storing the [globalid](https://github.com/rails/globalid) to the whodunnit field of PaperTrail version tables.
-- It is designed not to hinder or break existing PaperTrail functionalities.
-- PaperTrail versions with and without a globalid can live side by side (e.g. versions created before installing this gem.)
+Set any ActiveRecord object as the actor responsible for changes:
 
 ```ruby
+admin = Admin.find(1)
+PaperTrail.request.whodunnit = admin
+
+# Now all changes will be attributed to this admin
+# See Supported Object Types section below for detailed examples
+```
+
+### Supported Object Types
+
+The gem handles various object types gracefully:
+
+**Persisted ActiveRecord objects:**
+```ruby
+admin = Admin.find(1)
 product = Product.find(42)
-admin = Admin.find(1)                                       # <Admin:0x007fa2df9a5590>
 
 PaperTrail.request.whodunnit = admin
-PaperTrail.request.whodunnit                                # "gid://app/Admin/1"
-PaperTrail.request.actor                                    # <Admin:0x007fa2df9a5590> returns the actual object
+PaperTrail.request.whodunnit # => "gid://app/Admin/1"
+PaperTrail.request.actor     # => #<Admin id: 1>
 
+# Make changes - PaperTrail will track the actor
 product.update(name: "Ice cream")
-product.versions.last.whodunnit                             # "gid://app/Admin/1"
-product.versions.last.actor                                 # <Admin:0x007fa2df9a5590> returns the actual object
+product.versions.last.whodunnit # => "gid://app/Admin/1"
+product.versions.last.actor     # => #<Admin id: 1>
 ```
 
-### Setting whodunnit to something other than an ActiveRecord object
+**Strings:**
+```ruby
+PaperTrail.request.whodunnit = "Alex the admin"
+PaperTrail.request.whodunnit # => "Alex the admin"
+PaperTrail.request.actor     # => "Alex the admin"
+```
 
-You can continue to set whodunnit to something other than an `ActiveRecord` object.
-- It follows standard PaperTrail functionality and adds the raw value to the whodunnit field.
-- The `#actor` method will return the raw value.
+**New/unpersisted ActiveRecord objects:**
+```ruby
+PaperTrail.request.whodunnit = Admin.new(name: "New Admin")
+# Cannot get a globalid for an unpersisted object. So we use the `#to_s` for the object.
+PaperTrail.request.whodunnit # => "#<Admin:0x00007f8e8c0a0b80>"
+PaperTrail.request.actor     # => "#<Admin:0x00007f8e8c0a0b80>"
+```
 
+**Non-ActiveRecord objects:**
 ```ruby
-PaperTrail.request.whodunnit = "Alex the admin"
-PaperTrail.request.whodunnit                                # "Alex the admin"
-PaperTrail.request.actor                                    # "Alex the admin"
+class BackgroundJob
+  def to_s
+    "BackgroundJob-#{object_id}"
+  end
+end
 
-product.update(name: "99 Flake")
-product.versions.last.whodunnit                             # "Alex the admin"
-product.versions.last.actor                                 # "Alex the admin"
+PaperTrail.request.whodunnit = BackgroundJob.new
+PaperTrail.request.whodunnit # => "BackgroundJob-12345"
+PaperTrail.request.actor     # => "BackgroundJob-12345"
 ```
 
-### Updating whodunnit on existing PaperTrail versions
+### Controller Integration
 
-You can retrospectivly update PaperTrail versions to have a new actor.
+Set the actor automatically in your controllers using PaperTrail's built-in callback:
 
 ```ruby
-most_recent_product_version = product.versions.last
-admin_name = most_recent_product_version.actor              # "Alex the admin"
-alex_the_admin = Admin.find_by(name: admin_name)            # Do check for `nil` before updating the whodunit field
-most_recent_product_version.whodunnit = alex_the_admin
-most_recent_product_version.save
-most_recent_product_version.actor                           # <Admin:0x00000120fbb7d0>
+class ApplicationController < ActionController::Base
+  before_action :set_paper_trail_whodunnit
+end
 ```
 
-### Setting whodunnit with a controller callback
+If your controller has a `#current_user` method, PaperTrail-Actor will automatically use it and attribute all changes within the request cycle to that user.
 
-Similar to how you can configure the PaperTrail gem, as described in [Setting Whodunnit with a Controller Callback](https://github.com/paper-trail-gem/paper_trail/?tab=readme-ov-file#setting-whodunnit-with-a-controller-callback), you can now set this to an ActiveRecord object. This allows storing the global ID and retrieving the actor using the `#actor` methods.
+```ruby
+# In your CRUD actions
+def update
+  # Nothing else required here to attribute the user as the actor.
+  @product.update(product_params)
+  @product.versions.last.actor # => #<User id: 42> (full User object)
+end
+```
 
-Here’s an example in your `ApplicationController`:
+**Before PaperTrail-Actor:**
+```ruby
+# whodunnit was just a string like "42"
+version.whodunnit # => "42"
+# You couldn't tell if this was User 42 or Admin 42
+```
+
+**After PaperTrail-Actor:**
+```ruby
+# whodunnit stores the full GlobalID
+version.whodunnit # => "gid://app/User/42"
+version.actor     # => #<User id: 42>
+# Now you know exactly who to attribute the change to
+```
+
+Override `#user_for_paper_trail` to customize the actor selection logic:
 
 ```ruby
 class ApplicationController < ActionController::Base
+  before_action :set_paper_trail_whodunnit
+
+  private
+
   def user_for_paper_trail
-    logged_in? ? current_user : "Public user"
+    logged_in? ? current_admin : "Public user"
   end
 end
 ```
+
+### Migrating Existing Data
+
+**When to migrate:** Install PaperTrail-Actor on an existing app with PaperTrail data.
+
+**How to migrate:** Convert existing string IDs to GlobalIDs:
+
+```ruby
+# Find a version with a plain ID
+version = product.versions.first
+# => #<PaperTrail::Version id: 1, whodunnit: "123">
+
+# Convert to GlobalID
+admin = Admin.find_by(id: version.whodunnit)
+if admin.present?
+  version.update!(whodunnit: admin)
+  version.whodunnit # => "gid://app/Admin/123"
+  version.actor     # => #<Admin id: 123>
+end
+```
+
+## How It Works
+
+PaperTrail-Actor serializes ActiveRecord objects using [GlobalID](https://github.com/rails/globalid) and stores them in PaperTrail's `whodunnit` column. This enables:
+
+- **Type-safe actor identification**: `gid://app/Admin/1` vs `gid://app/User/1`
+- **Automatic deserialization**: Call `#actor` to get back the original ActiveRecord object
+- **Graceful fallback**: Non-ActiveRecord objects are stored as strings
+
+For example, if you have both `Admin` and `User` models that can make changes, this gem ensures you can clearly identify who made the change instead of using only an ID without knowing the model type.

data/lib/paper_trail-actor/actor_mixin.rb

@@ -0,0 +1,16 @@
+module PaperTrailActor
+  module ActorMixin
+    # Used for #whodunnit= methods
+    def global_id_string_or_fallback(input_value)
+      if input_value.respond_to?(:to_global_id) && input_value.id
+        input_value.to_global_id.to_s
+      else
+        input_value.to_s
+      end
+    end
+
+    def actor
+      ::GlobalID::Locator.locate(whodunnit) || whodunnit
+    end
+  end
+end

data/lib/paper_trail-actor/rails/controller.rb

@@ -0,0 +1,9 @@
+module PaperTrailActor
+  module Rails
+    module Controller
+      def user_for_paper_trail
+        current_user if defined?(current_user)
+      end
+    end
+  end
+end

data/lib/paper_trail-actor/request.rb

@@ -1,15 +1,11 @@
+require_relative "actor_mixin"
+
 module PaperTrailActor
   module Request
-    def whodunnit=(value)
-      if value.is_a? ActiveRecord::Base
-        super(value.to_gid)
-      else
-        super
-      end
-    end
+    include ActorMixin
 
-    def actor
-      ::GlobalID::Locator.locate(store[:whodunnit]) || whodunnit
+    def whodunnit=(input_value)
+      super(global_id_string_or_fallback(input_value))
     end
   end
 end

data/lib/paper_trail-actor/version.rb

@@ -1,3 +1,3 @@
 module PaperTrailActor
-  VERSION = "0.4.0"
+  VERSION = "0.5.1"
 end

data/lib/paper_trail-actor/version_concern.rb

@@ -1,20 +1,12 @@
+require_relative "actor_mixin"
+
 module PaperTrailActor
   module VersionConcern
+    include ActorMixin
+
     def whodunnit=(input_value)
-      whodunnit_value = if input_value.is_a?(ActiveRecord::Base)
-        input_value.to_gid
-      else
-        input_value
-      end
+      whodunnit_value = global_id_string_or_fallback(input_value)
       _write_attribute("whodunnit", whodunnit_value)
     end
-
-    # Returns an object which was responsible for a change
-    # you need to store global_id to whodunnit field to make this method return the object(who was responsible)
-    # for example, whodunnit => "gid://app/Order/1" then
-    # whodunnit_user will return Order.find_by(id: 1) in application scope.
-    def actor
-      ::GlobalID::Locator.locate(whodunnit) || whodunnit
-    end
   end
 end

data/lib/paper_trail-actor.rb

@@ -1,6 +1,7 @@
 require "paper_trail-actor/version"
 require "paper_trail-actor/request"
 require "paper_trail-actor/version_concern"
+require "paper_trail-actor/rails/controller"
 
 module ::PaperTrail
   module Request
@@ -8,10 +9,14 @@ module ::PaperTrail
       prepend ::PaperTrailActor::Request
     end
   end
-end
 
-module ::PaperTrail
   module VersionConcern
     include ::PaperTrailActor::VersionConcern
   end
+
+  module Rails
+    module Controller
+      prepend ::PaperTrailActor::Rails::Controller
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail-actor
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - tttffff
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-20 00:00:00.000000000 Z
+date: 2025-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: paper_trail
@@ -53,35 +53,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: activerecord
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: activesupport
+  name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -136,8 +108,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: An extension to PaperTrail. Using this gem, you can fetch the ActiveRecord
-  object that was responsible for changes
+description: An extension to PaperTrail that allows you to retrieve the ActiveRecord
+  object (actor) that was responsible for creating or modifying records, enabling
+  better audit trails and change attribution.
 email:
 - tristanfellows@icloud.com
 executables: []
@@ -149,6 +122,8 @@ files:
 - README.md
 - Rakefile
 - lib/paper_trail-actor.rb
+- lib/paper_trail-actor/actor_mixin.rb
+- lib/paper_trail-actor/rails/controller.rb
 - lib/paper_trail-actor/request.rb
 - lib/paper_trail-actor/version.rb
 - lib/paper_trail-actor/version_concern.rb
@@ -158,7 +133,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/tttffff/paper_trail-actor
   source_code_uri: https://github.com/tttffff/paper_trail-actor
-  changelog_uri: https://github.com/tttffff/paper_trail-actor/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/tttffff/paper_trail-actor/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -167,7 +142,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -177,6 +152,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: An extension to PaperTrail. Using this gem, you can fetch the ActiveRecord
-  object that was responsible for changes
+summary: Fetch the ActiveRecord object responsible for PaperTrail changes
 test_files: []