Doctrine Auditable Bundle Laravel Package

Product Decisions This Supports

• Audit trail / compliance roadmap item. Entity-level change history ("who changed what, when, from what value to what value") is a recurring requirement behind SOC 2, ISO 27001, HIPAA, and internal financial controls. This package is one implementation path for that requirement and lets you scope the work as configuration + schema rather than new feature development.
• Build vs. buy vs. borrow — now marginally more favorable. A homegrown Doctrine event-subscriber audit listener is typically 2–4 sprints including schema design, diffing logic, serialization of old/new values, and tests. The 5.0.0 release removes the biggest hidden cost of the previous assessment: framework-version compatibility work. Symfony 6 and PHP 8.0+ are now supported out of the box, so the integration estimate is realistically ~1 sprint of wiring, migration, and validation rather than 1 sprint plus an unbounded fork-and-backport effort.
• Architecture choice: application-layer vs. database-layer auditing. Committing to an ORM-level audit listener implicitly decides against DB triggers or CDC/log-shipping. That decision is unchanged by 5.0.0 and still has downstream consequences (writes bypassing the ORM go unaudited; no coverage of bulk DQL updates).
• Data governance and retention policy. Audit rows grow unbounded. Adopting this forces explicit decisions on retention windows, partition/archival strategy, PII handling in stored diffs, and whether audit data is exposed in admin tooling or exportable for DSAR (GDPR right-of-access) requests.
• Support and incident forensics. A field-level history table materially shortens "why did this record change?" investigations for support and finance, and is often the actual day-one value even when compliance is the stated driver. The move to cache-warming-time configuration validation is a small operational win here: misconfigured auditable entities fail at deploy/CI rather than silently producing audit gaps in production — which matters, because a silent gap is exactly what fails an audit.
• Prioritization signal — still a commodity, still not a differentiator. The pre-release signals (5 stars, 0 dependents, opportunity score 0.38) predate this release and should be re-baselined. One release does not change the strategic conclusion: fund the capability (audit trail), not the library; keep the integration thin enough to swap later.
• ⚠️ Applicability flag for this stack — unchanged and still disqualifying. Despite being catalogued as a "Laravel/PHP package," this is a Symfony bundle built on Doctrine ORM. It provides no Eloquent/Laravel integration, and 5.0.0 adds Symfony 6 support, not Laravel support. If the product is on Laravel, this package remains not a candidate at all — the entire evaluation should pivot to Eloquent observers/Auditable trait packages or a manual listener.
• ⚠️ Breaking-change flag for 5.0.0. Classes intended for inheritance are now final. Any integration plan that assumed extending the listener, attribute, or configuration classes to customize behavior is now invalid — customization must go through decoration/composition (Symfony service decorators, interfaces) or a fork. Budget for this if the design leaned on subclassing.

When to Consider This Package

Adopt only when all of the following hold:

• The application is Symfony 6 (now supported) or a maintained 5.x line, with Doctrine ORM 2.x — not Laravel, not Eloquent, not a mixed stack. Note that 5.0.0's attribute-mapping support implies ORM 2.9+; Doctrine ORM 3 compatibility is still not stated or guaranteed.
• You are on PHP 8.0 or newer. The 5.0.0 bump drops PHP 7.x entirely, so legacy services must stay pinned to the 4.x line (which reintroduces the original staleness problem).
• You need field-level old/new value capture on a small, well-bounded set of entities (e.g., contracts, invoices, user roles) rather than blanket auditing of the whole schema.
• You are currently using or evaluating Gedmo DoctrineExtensions Loggable and are dissatisfied with it (performance, schema bloat, conflict with other Gedmo listeners, or upgrade friction) — this package's stated reason to exist.
• Your team can live with composition-only customization — no subclassing of library internals after 5.0.0.
• Your team accepts a thinner but still real maintenance burden: the project shipped its first release since April 2022, which is a genuine positive signal and materially reduces the "abandoned dependency" risk — but a single release after a three-year gap is not yet a maintenance cadence. Assume you may still need to fork and vendor it, and that PHP 8.3/8.4 testing is on you.
• You can accommodate a cache-warming configuration model: auditable entity configuration is resolved at container compile/warmup, so changes require a cache rebuild and errors surface at deploy time rather than first request. This is desirable in CI-driven pipelines; verify it fits your deploy and local-dev workflow.
• Auditing happens in-process and synchronously; you do not need an external sink, message queue, or tamper-evident hash chain.
• The feature is internal-facing or low blast-radius, so a dependency that may stall again is a nuisance rather than a security liability.

Look elsewhere — or build in-house — when:

• Stack mismatch: Laravel/Eloquent, Symfony with MongoDB ODM, or raw PDO/query-builder access patterns.
• You need Doctrine ORM 3. Not claimed by 5.0.0; validate before assuming, and treat a negative answer as disqualifying if ORM 3 is on your near-term roadmap.
• You still need PHP 7.x — 5.0.0 is a hard break, and the 4.x line you'd be stuck on is the stale one.
• Maintenance and supply-chain standards are strict. 5.0.0 improves the story and is worth re-submitting to vendor-risk/SBOM review, but one release from a single maintainer may still not clear the bar for a regulated product. Compare against actively maintained alternatives (DoctrineExtensions Loggable, auditor-bundle, simplethings/entity-audit-bundle).
• Your customization strategy depends on inheritance — making classes final is a breaking change with no migration path other than decorators or a fork.
• You need a complete audit product, not a table: query UI, diff viewer, actor attribution with impersonation handling, retention/archival automation, export for auditors, alerting on anomalous changes.
• Throughput is high or writes are hot — synchronous per-entity diffing adds latency and write amplification to every flush; you'd want async capture or CDC.
• Coverage must be exhaustive — bulk DQL updates, raw SQL migrations, and third-party writes bypass ORM listeners entirely, leaving audit gaps that fail a real audit.
• You need it this quarter and can't absorb fork maintenance — the integration is small enough that a purpose-built listener remains a defensible lower-risk path, though the gap has narrowed.

How to Pitch It (Stakeholders)

For executives (30 seconds): "We need an audit trail — it's a blocker for [enterprise deal / certification / finance controls]. The off-the-shelf component we evaluated has just shipped a new major version that fixes the main objection: it now supports Symfony 6 and PHP 8, so it's no longer dead software. It still only fits our Symfony/Doctrine services and does nothing for the Laravel side of the platform. My recommendation is unchanged in shape but firmer in confidence: approve a one-sprint spike to validate it on two or three entities, with a documented fallback to a ~3-sprint in-house implementation. Upside is ~3 sprints saved; downside is bounded because the library writes to a plain table and is cheap to replace."

For engineering: "5.0.0 is a real modernization release: PHP 8.0 minimum, Symfony 6 support, attribute-based ORM mappings, a contributor joining, and — most usefully — auditable configuration resolved at cache warmup instead of runtime, which turns silent misconfiguration into a deploy-time failure. Two things to plan around. First, classes are now final: if our design extended the listener or config classes, switch to Symfony service decoration against our own AuditWriter interface before we start. Second, Doctrine ORM 3 is not claimed — 18 months of drift means we test that ourselves in week one. Otherwise: vendor/fork plan still stands, MIT, no vendor lock-in, and the coverage caveats are unchanged — bulk DQL, raw SQL, migrations, and non-ORM writers are all unaudited."

Recommendation: pursue the capability, not the package — but re-run the technical validation, don't re-run the strategic debate. The 5.0.0 release materially de-risks the PHP/Symfony compatibility question, so the spike is cheaper than it was. Time-box it: if the first week doesn't clear Doctrine ORM 3, PHP 8.3, and the final-class decoration path, stop and build the listener in-house. The surface area is small, and the remaining risk is that a three-year release gap is followed by another one — a risk that is now lower but not gone.