Laravel Accountable Laravel Package

Product Decisions This Supports

• Audit trail / compliance scope: This package (userstamping — automatically recording created_by / updated_by on models) is the cheapest way to answer "who changed this?" for support, internal audit, and regulatory asks (SOC 2, GDPR data provenance, HIPAA-adjacent workflows). The 10.1.0 release moves it from "convenient default" to "production-grade audit primitive."
• Manual attribution as a first-class workflow: "Prevent overriding userstamp when it's already been set" means explicitly assigned stamps survive the automatic write. This unlocks decisions around data imports, migrations, backfills, and seeded demo environments — you can preserve original authorship instead of stamping every imported record as the importing admin. Product implication: historical data can be migrated without corrupting audit records.
• System/service attribution: Combined with the above, you can stamp records as system, a specific integration user, or an upstream owner rather than the currently authenticated actor. This is a common compliance requirement ("this record was created by the API, not by Jane in support").
• Scoped impersonation without global state: whileActingAs callback helper gives you a bounded context in which writes are attributed to a chosen user. Relevant product surfaces: admin "act as customer" tooling, queue/console jobs that have no auth context, replay/reprocessing flows, and support-driven corrections. Preferring a callback over global state reduces the risk of attribution leaking into unrelated writes in the same request or job.
• Build vs. buy: If audit attribution is a nice-to-have, this is a clear "buy" (adopt, don't build). If audit is central to the product (finance, healthcare, regulated SaaS), treat it as a dependency to assess for long-term maintenance and coverage rather than a complete audit-logging solution — it records who, not what changed.
• Roadmap lever: The new callback helper makes asynchronous and automated writes safer, which often unblocks feature work (bulk operations, background sync, admin tooling) that would otherwise require bespoke attribution plumbing.

When to Consider This Package

Adopt when:

• You have (or expect) Eloquent models needing created_by / updated_by (and optionally deleted_by) with minimal boilerplate.
• You write data outside a normal authenticated request — imports, seeders, migrations, artisan commands, queued jobs — and need attribution that is deliberate rather than null or accidental.
• You need scoped impersonation (support "act as", replay flows) and want it contained to a callback rather than a global Auth::login() swap.
• You already standardize on Laravel and want a small, single-purpose dependency rather than a full audit-log suite.

Look elsewhere or supplement when:

• You need field-level change history (before/after diffs, revert, time-travel) — this stamps identity, not deltas. Pair with an activity-log package or event sourcing.
• You need immutable, tamper-evident audit storage (append-only tables, hash chaining, external SIEM export). Userstamp columns are mutable rows in your app DB.
• Your models are written by many services outside Laravel — you'll need a cross-service attribution contract, not a PHP trait.
• You require guarantees around retention, PII redaction in audit records, or legal hold; that's policy and schema design work the package won't do for you.
• The package is a single-maintainer dependency and your compliance posture demands vendor support — assess maintenance cadence and pin versions.

How to Pitch It (Stakeholders)

To executives: We're standardizing how our application records who created and changed each record. This release closes two gaps that previously forced custom code or left audit data unreliable: records can now carry an intentional author (imports and migrations keep their original attribution instead of being misattributed to whoever ran the job), and we can safely attribute actions to a specific user inside a bounded scope — for example, an automated job or a support "act as" session — without that attribution bleeding into other work. Net effect: stronger audit posture for compliance and customer security questionnaires, less bespoke code to maintain, and faster delivery of admin and bulk-operation features.

To engineering: 10.1.0 is additive and non-breaking. Two capabilities: (1) explicitly set userstamps are no longer overwritten, so Model::create([... 'created_by' => $id]) and import/backfill paths preserve authorship; (2) whileActingAs($user, fn () => ...) provides callback-scoped attribution — preferred over swapping the authenticated user globally, since it's exception-safe and contained to the closure. Adopt it for queued jobs and console commands where Auth is empty, and for impersonation features. Note the boundaries: this stamps identity only — no before/after diffs, no immutable log, no cross-service contract. If audit is a product requirement rather than a convenience, pair it with a change-history/append-only log and treat the stamp columns as the "who," not the "what."

Migration note: additive minor release; verify any existing code that relied on stamps being overwritten (rare, but check import and seeder paths), and confirm the whileActingAs helper's nesting and exception behavior matches your impersonation policy before shipping admin tooling on it.