Blameable Laravel Package

Product Decisions This Supports

• "Who did this?" attribution as a first-class product capability. Blameable adds created_by / updated_by / deleted_by relationships to Eloquent models, which underpins support workflows ("who deleted this record?"), admin tooling, and record-ownership displays without custom plumbing.
• Build vs. buy on audit metadata. The alternative is hand-rolling user-stamping traits, observers, and migrations in every project. This package is a small, single-purpose dependency that replaces ~1–2 days of internal build plus ongoing maintenance — a clear "adopt" unless requirements exceed simple attribution.
• Roadmap input for compliance and trust features. If the roadmap includes SOC 2 / GDPR audit trails, change history, or tamper-evident logs, this package covers only the attribution slice. It is a stepping stone, not the destination — pair it with a full activity-log solution rather than assuming it satisfies an audit requirement.
• Scoping of admin and support surfaces. Attribution enables "records created by X", "recently modified by my team", and undo/soft-delete recovery flows. These are cheap wins that can be scheduled once adoption is confirmed.
• Feature prioritization for soft deletes. Because deleted_by is captured, decisions about restore/recovery UX (who can restore what, with what trail) become implementable rather than theoretical.

When to Consider This Package

Adopt when:

• The app is Laravel + Eloquent and needs simple, per-record "who created/updated/deleted this" metadata.
• Requirements are attribution only — identity of the actor, not a full diff of what changed.
• You want convention-over-configuration: a trait on models, a handful of nullable foreign keys, and predictable relations on the User model.
• The team values a narrow dependency over an internal utility, and wants PHP 8.4–compatible, actively maintained code.
• Soft deletes are in use and you need the deleter's identity persisted for support or recovery.

Look elsewhere when:

• You need field-level change history (old → new values), timelines, or per-attribute diffs — use an activity-log/audit package instead.
• Compliance requires immutable, append-only, retention-governed audit storage; blame columns on mutable rows are not a compliant audit trail.
• You need auditing across non-Eloquent data sources, queue-only writes, or raw bulk operations that bypass model events.
• Multi-tenancy or impersonation makes a single user_id ambiguous (e.g., system jobs, impersonating admins, service accounts) — verify the fallback semantics fit before committing.
• You want to avoid any additional schema coupling on core tables; each audited model gains three nullable FKs.

Release signal (v1.2.0): maintenance-only release — dependency bumps, a modernized test matrix, and PHP 8.4 support. No new features, no breaking changes, no deprecations. Treat it as evidence of healthy upkeep and current-version compatibility, not as a capability upgrade.

How to Pitch It (Stakeholders)

For executives: This is a small, low-risk open-source component that answers a question every support and compliance conversation eventually hits — who changed this record? Buying it (free, OSS) costs us a dependency instead of engineering days, and the latest release confirms it runs on our current PHP version and is actively maintained. It does not by itself satisfy an audit or compliance requirement; it's one building block, and if a formal audit trail enters the roadmap we'll need a dedicated solution alongside it.

For engineering: A single trait plus three nullable foreign keys gives you created_by / updated_by / deleted_by relations and helpers across models, with no opinion imposed on the rest of your schema. v1.2.0 is a hygiene release — dependency updates, testbench/phpunit bumps, and PHP 8.4 compatibility — so upgrading is low-risk and there are no migration or API changes. Caveat worth validating in a spike: attribution relies on model events, so bulk writes, DB::table() updates, and queued jobs without an authenticated user will need a deliberate fallback (system user or null) if you depend on these columns for reporting.