Auditable Relations Laravel Package

Product Decisions This Supports

• Audit-trail completeness (compliance scope): Determines whether "who granted this access?" is answerable. Laravel Auditing covers model CRUD; relationship changes (attach, detach, sync, toggle) are where role grants, permission assignments, team membership, and catalog tagging actually happen. This package closes that specific gap, which makes it a scope decision for any SOC 2 / ISO 27001 / HIPAA-adjacent milestone.
• Build vs. buy for pivot auditing: The v1.2.0 changelog is effectively a list of the edge cases an in-house build would hit — MorphToMany attaches, the attach half of toggle(), dropped pivot configuration (withPivot, withTimestamps, using, as, wherePivot), custom pivot classes breaking on type checks. Buying (MIT, free) is cheap; the real cost is verification, not licensing.
• Feature surface: Enables admin-facing "Activity History" and "Access Change Log" views for access-control entities, with less bespoke event plumbing.
• Data retention and storage sizing: Audits store full related models and cost two extra SELECTs per operation. That's a product decision about retention windows, PII exposure in audit rows, and whether snapshot-level fidelity is acceptable versus a field-level diff.
• GDPR / right-to-erasure posture: Immutable-ish audit trails and erasure requests conflict. Decide the redaction strategy before shipping, not after.
• Vendor-risk and ownership: 4 stars, 0 dependents, single maintainer, released 2026-09-24. The honest framing is "adopt as a fork we own," not "adopt as a dependency we rely on."

When to Consider This Package

Consider it when:

• You already run owen-it/laravel-auditing and the only gap is relationship-level events — this is additive, not a replacement.
• Access-granting or compliance-relevant data lives in many-to-many or morph-to-many relations (roles, permissions, teams, tags, categories).
• Write volume on those relations is modest and audit reads are occasional (support tickets, quarterly reviews, incident forensics).
• You rely on custom pivot models, MorphToMany, or toggle() — v1.2.0 specifically fixes those, and older versions would silently miss or corrupt them.
• Your team can vendor/fork a small package and add contract tests around your own relations.

Look elsewhere when:

• High-volume writes: bulk sync() in nightly imports or backfills will multiply into two extra SELECTs and a full related-model snapshot per row.
• You need tamper-evident guarantees (hash chaining, WORM storage, append-only ledger). Pair with an external SIEM or dedicated audit store instead of treating this as the system of record.
• You need compact field-level diffs rather than full related-model snapshots, or you can't tolerate related-model PII landing in audit rows.
• You're not already on Laravel Auditing, or you're not on Laravel.
• Procurement requires an SLA, security review, or named maintainer — no dependents and 4 stars won't clear that bar.
• Erasure obligations are strict and you have no redaction/purge plan for audit data.

How to Pitch It (Stakeholders)

For executives: "Our audit log currently answers 'who edited this user record' but not 'who added this person to an admin role.' That second question is the one auditors and incident reviews actually ask, and today we can't answer it from logs. This is a small, free, MIT-licensed Laravel package that closes exactly that gap and nothing more. The license cost is zero and the integration is narrow, but I'd frame it as something we adopt and own rather than a strategic dependency — it's early-stage with a single maintainer. Recommendation: fund a short spike to fork it, pin the version, and write tests against our own relations before it touches a compliance-critical path."

For engineering: Adoption is a trait/wrapper around your existing relations (auditableRelation()) layered on Laravel Auditing. v1.2.0 preserves pivot configuration chained on BelongsToMany, audits MorphToMany attaches and the attach half of toggle(), respects custom using() pivot classes instead of swapping them, and audits pivot saves/deletes transactionally via the new HandlesAuditablePivot trait. It ships a Pest suite and a Laravel Boost guideline, which lowers onboarding cost. Two things to plan for up front: performance — two extra SELECTs per operation plus full related-model storage per audit row, so index and set retention deliberately — and maintenance — 4 stars, zero dependents, so pin the version, fork it into our namespace, and cover our own relation shapes with tests rather than assuming upstream coverage.