Auditable Relations Laravel Package

Technical Evaluation

Architecture fit. The package is a thin extension layer over owen-it/laravel-auditing rather than a standalone auditing system. It hooks into Eloquent's relationship lifecycle (attach, detach, sync, toggle) via an auditableRelation() wrapper and custom pivot models (AuditablePivot, AuditableMorphPivot, plus the new HandlesAuditablePivot trait). Architecturally this is the right shape: it delegates persistence and audit formatting to Laravel Auditing and only fills the pivot-change gap that the parent package leaves. The concern is that this gap is filled by intercepting Eloquent internals (pivot events, pivot class substitution, MorphToMany), which is inherently version-sensitive.

Integration feasibility. Feasible for teams already running Laravel Auditing on Eloquent models with BelongsToMany/MorphToMany pivots (roles, permissions, tags, memberships). It is not a drop-in: relationships must be opted in through auditableRelation(), and pivot classes must either extend AuditablePivot/AuditableMorphPivot or be handled via using(). The v1.2.0 fixes show the integration surface is wider than the README implies — chained withPivot(), withTimestamps(), as(), wherePivot(), query constraints, custom pivot classes, and MorphToMany attach all had correctness gaps until recently.

Technical risk.

• Bus factor / adoption risk (high). 4 stars, 0 dependents, single maintainer, MIT. There is no ecosystem signal of production hardening; you are effectively an early adopter.
• Maturity risk (medium-high). v1.2.0 fixed bug classes that would be silent data-integrity failures in an audit system (dropped wherePivot() constraints, pivot class swapping producing TypeError, unaudited MorphToMany attach). That is a warning that the audit contract was not fully correct in earlier releases.
• Framework-coupling risk (medium). Pivot interception, custom pivot class handling, and event wiring break on Laravel major/minor changes. Requires a regression matrix per Laravel upgrade.
• Performance/data-growth risk (medium). Documented as two extra SELECTs per operation and full related model storage. For sync() on large sets this multiplies linearly and bloats the audit table.
• Correctness confidence (improving). Pest test suite and a Laravel Boost guideline were added, which raises confidence, but coverage breadth and CI matrix are unverified.

Key questions.

1. Which Laravel and PHP versions are supported, and is there a CI matrix per version?
2. Which owen-it/laravel-auditing major is required, and what happens on a parent-package upgrade?
3. Does it audit bulk query-builder operations (DB::table(...)->attach, raw deletes) or only Eloquent relationship calls?
4. How are soft deletes, syncWithoutDetaching, updateExistingPivot, and toggle (detach half) represented in the audit trail?
5. What is the audit schema for pivots — parent model audit row, pivot row, or both — and does it double-count against existing model audits?
6. What is the sensitive-data exposure on pivot audit rows (full related model payloads stored verbatim)?
7. Is there a stated retention/purge story, and is indexing guidance provided for the audit table?
8. Who is the maintainer, what is the response SLA, and is a fork/ownership-transfer path acceptable?

Integration Approach

Stack fit. Assumes Laravel (Eloquent) + owen-it/laravel-auditing already in place, a relational pivot table, and models that emit audit events. It does not replace your auditing strategy; it complements it. If Laravel Auditing is not already adopted, this package is not the entry point — adopt the parent package first, then layer this on for pivot coverage.

Migration path.

1. Inventory pivot relationships and classify by audit value (e.g. role/permission assignments and membership changes are high value; ephemeral tag pivots may not justify the write cost).
2. Introduce AuditablePivot/AuditableMorphPivot or wrap the relationship with auditableRelation() for the pilot set only.
3. Publish/verify Laravel Auditing configuration so pivot audits land in the expected audits table with the expected auditable_type.
4. Define a backfill strategy for historical pivot state (likely a one-off snapshot job rather than reconstructing event history).
5. Roll forward relationship by relationship; do not convert all pivots at once.

Compatibility. Pin the package, Laravel, and Laravel Auditing versions explicitly. The v1.2.0 changelog is a compatibility contract you should test against: custom using() pivot classes must not be swapped, withPivot constraints must survive, and MorphToMany attach must be audited. Add regression tests for each of these before any Laravel minor upgrade. Verify the pivot's primary/unique keys work with HandlesAuditablePivot transactions.

Sequencing.

• Phase 0: validate on a disposable branch with one low-risk BelongsToMany and one MorphToMany; confirm audit rows, payload shape, and constraint preservation.
• Phase 1: pilot in a staging environment on a high-value relationship (roles/permissions), including sync() and toggle() paths.
• Phase 2: production rollout per relationship with feature-flag-style rollback (revert to unwrapped call site).
• Phase 3: add monitoring on audit write volume, transaction rollback behavior, and unaudited-operation detection.
• Phase 4: retention/indexing tuning once real volume is observed.

Operational Impact

Maintenance. Single-maintainer, low-adoption package with a small but non-trivial internal surface (Eloquent pivot internals). Treat it as a dependency you may need to fork. Budget for an internal owner who can read Eloquent relationship internals and patch on Laravel upgrades. The added Pest suite and Boost guideline reduce onboarding cost but not the ownership burden.

Support. MIT, community-only, no SLA, 0 dependents means no crowd-sourced battle testing. Escalation is effectively "fix it ourselves." Acceptable only if the audit requirement (pivot-change traceability for compliance/forensics) is high enough to justify carrying that risk.

Scaling. Two extra SELECTs per relationship operation plus full related-model payloads in the audit table. sync() on large pivot sets scales linearly in both queries and audit rows. Plan for: audit table partitioning or archival, indexes on auditable_type/auditable_id/created_at, and possible async audit writes if the parent package supports queueing. High-churn pivots (frequent syncs) should be evaluated for exclusion or summarization.

Failure modes.

• Silent miss: relationship not wrapped or pivot not swapped → changes occur with no audit trail. Highest-severity failure for a compliance use case; mitigate with an assertion/monitoring check that expected pivot operations produce audit rows.
• Constraint drift: chained wherePivot()/query constraints dropped (fixed in v1.2.0) → wrong rows audited. Regression-test any constrained relationship.
• Pivot class mismatch: custom using() pivot producing TypeError or being replaced by AuditablePivot → runtime failure on relationship operations.
• Transaction interaction: HandlesAuditablePivot audits inside a transaction; failed outer transactions should roll back audit rows, but verify this matches your compliance expectation (some regimes expect attempts logged).
• Audit bloat / write amplification: large sync() operations causing table growth and latency on the request path.
• Upgrade breakage: Laravel or Laravel Auditing upgrade silently disabling interception.

Ramp-up. A competent Laravel team can understand usage in under a day; understanding why a given pivot is or isn't audited takes longer because it depends on Eloquent pivot internals and the wrapper semantics. Onboarding docs are thin (README + release notes), so plan for an internal runbook covering: which relationships are audited, the expected audit row shape, how to verify coverage, and the fork/patch procedure. The Boost guideline helps AI tooling but is not a substitute for a written internal standard.