Symfony Doctrine Audit Laravel Package

Getting Started

• Install the bundle and confirm Composer resolves doctrine/dbal to ^4.2; the audit schema depends on Types::ENUM and Column::getValues(), which do not exist in 4.0/4.1.
• Look first at .example/: a runnable micro-kernel that audits a product nomenclator into a second database and a JSONL file, with scenarios for every capability. Run .dev/validate/all.sh --example against MySQL/MariaDB before wiring your own app; its CI job shows the intended setup.
• Minimal integration: register the provider, publish the config, run the audit schema migration, and mark one entity as audited. Flush a create/update/delete, then read the recorded history back.
• This is Doctrine ORM, not Eloquent. Expect EntityManager, UnitOfWork, and onFlush/postFlush semantics rather than model events.
• First real use case: audit a low-churn aggregate (product, order header) and render its timeline in an admin screen. Once the trail is trustworthy, add scheduled purge with --before on the JSONL sink to bound retention.

Implementation Patterns

• Entity auditing: identifiers may be any Stringable value object — Uuid, Ulid, or a uid mapping — and are recorded in string form. Read history with (string) $id, not the raw object.
• Collection auditing: use it on owning collections and join tables. Removing an audited owner or calling Collection::clear() now records the join rows in the removed list, so "who unlinked what" history survives.
• Retention: schedule purge with --before. New JSONL records stamp date in ATOM with offset, so a boundary means the same instant regardless of the host running the purge. Pair file-storage purges with whatever pruning you do on the audit tables.
• File sink: run FileStorage alongside the database trail for archival or log shipping. Its exclusive-lock writes and truncate-on-failure behaviour keep the JSONL readable for downstream consumers and later purges.
• Identity lookups: use --identity for CLI/ops investigations. Quote values that must stay strings: --identity='code="007"'. In application code, cast identifiers to string before lookup.
• Cursor pagination: page long histories through the audit cursor API and treat cursor strings as opaque tokens — do not hand-edit or loosely serialize them.
• Testing: mirror the .example/ scenarios in your own suite and gate with .dev/validate/all.sh --example; the example covers MySQL and MariaDB, including enum-column stability.

Gotchas and Tips

• Association-containing primary keys are refused. The refusal now happens in onFlush, before the transaction opens, when the identifier is readable there. That is much safer than the old postFlush throw after commit, but it is still a design constraint: use a surrogate ID or an explicit identifier accessor. If the identifier is not readable at onFlush, don't assume a later commit saves you.
• --identity casts unquoted values. code=007 becomes the integer 7 and matches nothing. Quote numbers, references, and anything keyword-like.
• Cursor validation is strict. A cursor that does not decode back to exactly its number — including a trailing newline — is refused instead of being treated as end-of-data, and values beyond PHP_INT_MAX no longer saturate into an empty page. Code that relied on silent empty pages will now see errors; treat that as a correctness signal.
• Purge recovery file semantics. A failed purge leaves a complete <file>.purge kept-set by design; an incomplete one is deleted and the real cause reported. If <file>.purge exists, restore it before rerunning. Update operator runbooks to check for it rather than assuming the main audit file was untouched.
• Legacy JSONL timestamps are naive. Records written before 4.1 are still read in the reader's timezone. Purging a mixed old/new file with --before can be off by up to fourteen hours for the old records; migrate or tighten boundaries.
• DBAL floor is hard. Upgrading the bundle can conflict with an app pinned to DBAL 4.0/4.1. Plan the DBAL bump together with the bundle upgrade, and re-run the example against your database (MySQL/MariaDB enum handling is exercised there).
• Extra reads during onFlush. Collection and owner removals now query the database while rows still exist. This is the right trade-off for correctness, but benchmark bulk deletes and large clear() operations.
• Partial-write repair is internal. FileStorage truncates a record whose write failed after emitting bytes, under the same lock. You should no longer need manual JSONL repair for torn lines — but don't reintroduce corruption by writing to the file outside the storage API.
• Enum columns: the schema uses DBAL enum helpers to keep enum columns stable. Verify them against your actual MySQL/MariaDB versions, not just the SQLite or in-memory setup used for fast tests.