paper_trail-actor 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5feb0e3bd1d5d354acc67d9da8ce59737cd5f9d2003aac8a06d6d97abe9a964d
-  data.tar.gz: 4c539f383eff32c652da404f3bf8edcc215cf3e1b1357b6d1566d0ad8abc37c0
+  metadata.gz: 7b84892ec641d12e2f30f9779c934369db0ff3b3246cc6c12837f3750a704392
+  data.tar.gz: 6d2dcde8f48e153acf1680c0f9dc278c2a5ed696dda0341557d0f104f12e5dbb
 SHA512:
-  metadata.gz: 396ac19a6b0ec27b2bddbc46c58e34819d6a1761fc2acee5cff4b3e9143b939c3a0f0dda67c4463d8581d44ef9fbc79ba492326ba8d66ba2c0cb8e5e2ca357ce
-  data.tar.gz: e8077674949aa3d963b543d74c495edb6ccf975fb86821c8dc97ecc9db0527702ca5f412ee28b12849b8edf2701319cf89dee9dc3354415ffc9830ed46cf5912
+  metadata.gz: 0cdefc8cb362df6ae343b23d60ff02ba28a3ebded2cc51f4a7e292cf70587b6a826074e0ed2a3554c5ff73f79893966b84314209247b509f9681153f818b45ff
+  data.tar.gz: 8a50a20d5d6183cd6d0871ac24f3c84a6461339ec08fd1aacbd78e95ae0a6a207601720161d268288e170605df012aae47f4cb05533525ae0e39f462583e4793

data/CHANGELOG.md

@@ -52,3 +52,21 @@
 ### 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.

data/README.md

@@ -1,82 +1,123 @@
 # PaperTrail-Actor
 
-Originally forked from the now unmaintained [paper_trail-globalid](https://github.com/ankit1910/paper_trail-globalid).
+This gem is an extension for [PaperTrail](https://github.com/paper-trail-gem/paper_trail) that allows you to set an `ActiveRecord` object as the "whodunnit" field. This enhancement provides more granular tracking of who made changes, making it easier to trace modifications in your application.
 
-This gem is an extension to the [PaperTrail](https://github.com/paper-trail-gem/paper_trail) gem.
+## Features
 
-- 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.
+- **Set an ActiveRecord Object for Whodunnit:** Use an `ActiveRecord` object to track who made changes.
+- **Return the ActiveRecord Object:** The method `#actor` can be used to get the object responsible for changes.
+- **Coexistence with Existing Versions:** Works seamlessly alongside existing PaperTrail versions, regardless of when they were created.
+
+## How it works
+
+This gem works by storing the [globalid](https://github.com/rails/globalid) to the whodunnit field of PaperTrail version tables. This allows you to add different object types to the whodunnit field, know exactly which object is responsible, and retrive that object with ease.
+
+For example, if you have both `Admin` objects and `User` objects that are capable of making changes, this gem ensures that you can clearly identify who made the change instead of using purely an ID and not knowing if it was for an `Admin` or a `User`
 
 ## Installation
 
-1. Add PaperTrail-Actor to your `Gemfile`.
+1. Add `paper_trail-actor` to your Gemfile:
   ```ruby
   gem "paper_trail-actor"
   ```
-2. And then execute:
+2. Run the following command:
   ```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.)
+To use this gem, you first need to set a user (or any `ActiveRecord` object) to the `whodunnit` field.
 
 ```ruby
 product = Product.find(42)
-admin = Admin.find(1)                                       # <Admin:0x007fa2df9a5590>
+admin = Admin.find(1)
 
 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 # Returns the `Admin` object with id 1
+```
+
+When you update the product, PaperTrail will remember who made the change:
 
+```ruby
 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 # Returns the `Admin` object with id 1
 ```
 
-### Setting whodunnit to something other than an ActiveRecord object
+### Flexible Whodunnit
 
-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.
+The gem is designed to be flexible. You can set `whodunnit` with various types of objects:
 
-```ruby
-PaperTrail.request.whodunnit = "Alex the admin"
-PaperTrail.request.whodunnit                                # "Alex the admin"
-PaperTrail.request.actor                                    # "Alex the admin"
+- **Strings:**
+  ```ruby
+  PaperTrail.request.whodunnit = "Alex the admin" # "Alex the admin"
+  ```
+
+- **New/unpersisted ActiveRecord Objects:**
+  ```ruby
+  PaperTrail.request.whodunnit = Admin.new # Sets the string representation of the admin
+  ```
+
+- **Non-ActiveRecord Objects:**
+  ```ruby
+  class Job
+    def to_s
+      "A job in the system"
+    end
+  end
+
+  PaperTrail.request.whodunnit = Job.new  # "A job in the system"
+  ```
 
-product.update(name: "99 Flake")
-product.versions.last.whodunnit                             # "Alex the admin"
-product.versions.last.actor                                 # "Alex the admin"
+When you update the product, PaperTrail will store the string for who made the change:
+
+```ruby
+product.update(name: "Ice cream")
+product.versions.last.whodunnit # "A job in the system"
+product.versions.last.actor # "A job in the system"
 ```
 
-### Updating whodunnit on existing PaperTrail versions
+### Updating Existing Versions
 
-You can retrospectivly update PaperTrail versions to have a new actor.
+If you have existing PaperTrail versions and need to update them, you can do so by:
 
 ```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>
+first_product_version = product.versions.first
+admin_id = first_product_version.actor # For example, "1"
+admin = Admin.find_by(id: admin_id)
+
+if admin.present?
+  first_product_version.whodunnit = admin
+  first_product_version.save
+end
 ```
 
 ### Setting whodunnit with a controller callback
 
-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.
+You can set the user for PaperTrail in the same way that the [PaperTrail documentation states](https://github.com/paper-trail-gem/paper_trail#setting-whodunnit-with-a-controller-callback).
+
+However, setting this to an ActiveRecord object now records the globalid. It also allows the object to be retrived from created PaperTrail versions with the `#actor` method.
+
+If your controller has a `#current_user` method, PaperTrail-Actor will assign the globalid of the current user to whodunnit. If your controller doesn't have a `#current_user`, or if the current user is `nil`, then whodunnit will not be set.
 
-Here’s an example in your `ApplicationController`:
+You may want set `#user_for_paper_trail` to call a different method to find out who is responsible. To do so, override the `#user_for_paper_trail` method in your controller:
 
 ```ruby
 class ApplicationController < ActionController::Base
+  before_action :set_paper_trail_whodunnit
+
   def user_for_paper_trail
-    logged_in? ? current_user : "Public user"
+    logged_in? ? current_admin : "Public user"
   end
 end
 ```
+
+## Contributing
+
+1. Please add tests for PRs that are created.
+2. Run the tests `bundle exec rake spec` to ensure that they all pass.
+3. Lint the code `bundle exec rake standard:fix` to ensure that convention is maintained.

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.0"
 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.0
 platform: ruby
 authors:
 - tttffff
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-20 00:00:00.000000000 Z
+date: 2025-04-29 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:
     - - ">="
@@ -149,6 +121,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 +132,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: