Download the PHP package jul6art/audit-bundle without Composer

Symfony audit bundle

Requirements

• php ^8.5
• symfony ^7.4 || ^8.0
• jul6art/core-bundle ^2.0

Installation

Setting it up

The bundle records who changed what, when, and on whose behalf — one row per write, in a table you own. Three steps, and the third is the one people forget.

1. Declare the entity that holds the trail

The bundle ships Entity\AuditLog as a mapped superclass, not an entity. That is deliberate: the table name, the indexes, and whatever you expose on top — an API resource, a retention policy, a role check — belong to your application, not to a bundle.

⚠️ Bring your own identifier. A mapped superclass may not declare the primary key of its children, so the concrete class does — IdTrait from jul6art/core-bundle, or a hand-written $id. Forgetting it fails at mapping time with a clear message, which is the good kind of failure.

Then generate the migration: bin/console doctrine:migrations:diff. The columns are organization_id, user_id, impersonator_id, action, target_type, target_id, payload, diff, ip_address, user_agent, created_at.

Add indexes for the way you read the trail. The two above are the minimum for a chronological screen filtered by action; add (target_type, target_id) for a per-object history, user_id for a per-actor listing, organization_id for a multi-tenant scope.

2. Point the bundle at it

This option has no default and the bundle refuses to boot without it. A mapped superclass has no table, so a missing or wrong log_class would leave every #[Auditable] silently inoperative — an audit trail that records nothing, and says nothing about it. Failing at container build is the lesser evil.

3. Annotate what you want audited

That is all. EventListener\AuditableListener is registered on Doctrine's postPersist, postUpdate and preRemove as soon as audit.enabled is true, and it is what actually reads the attribute.

What a row says

Diff values are flattened so the row stays readable and serialisable: a date becomes ISO 8601, an enum its backing value, a related entity its id.

A soft delete reads as a deletion, not an update

A soft delete is technically an UPDATE of deletedAt, and logging it as updated produces a trail nobody can read. When the change set shows deletedAt going from null to a date, the row is recorded as deleted — and as restored on the way back.

⚠️ So do not log those actions by hand. An application that also calls $auditLogger->log('invoice.deleted') in its service ends up with two rows for one event.

Who is acting, and on whose behalf

The actor comes from the security token, through jul6art/core-bundle's TokenStorageAwareTrait. Two things follow:

• No security bundle, no actor. symfony/security-bundle is a suggest, not a requirement: without it every row is written with a null actor, which is the correct answer for a CLI command and an honest one for an application with no security layer.
• An impersonation is recorded twice over. user_id is the impersonated account — what most code wants — and impersonator_id is the administrator who started the switch. Recording only the first would say the user did what an administrator did in their name.

Writing an entry yourself

The attribute covers entity writes. Everything else — an email sent, an export downloaded, a permission granted — is a call:

The listener writes inside your transaction, without a nested flush

Since 3.1 the automatic listener inserts its row through the connection (logWithinFlush()), inside the transaction the commit already holds: the row is rolled back with the write it records, and costs one INSERT — no SAVEPOINT pair. Before, it flushed the unit of work again from postPersist/postUpdate, which recomputed every pending change set: an entity updated later in the same flush was written twice, its PreUpdate callbacks run again.

Batching a fan-out

log() flushes immediately, which is right for one action and disastrous for a hundred: each flush re-runs Doctrine's listener cascade over everything accumulated so far, so a ~50-query request becomes 1500+.

Calls nest, and only the outermost endBatch() flushes.

⚠️ Always close a batch in a finally. An exception escaping an open batch leaves the logger buffering every subsequent row until something else flushes — the trail then looks incomplete rather than broken, which is harder to notice.

An open batch holds its rows and persists them when it closes. That is not an implementation detail: the automatic listener writes from postPersist/postUpdate, which fire inside UnitOfWork::commit(), and a commit ends by clearing entityInsertions wholesale. A row merely persist()ed from a listener is swept away with it and never reaches the database — silently.

So this is safe, and it is the shape a state machine or an importer actually needs:

Silencing the listener during a fan-out

Batching the writes is not the same as not writing them. When a flow already records its intent (feature.assigned) and the per-row trail underneath is noise:

⚠️ Coarse on purpose, and finally is not optional. A leaked depth silently disables auditing for the rest of the request. Use it when the caller records the intent itself — never to hide writes.

Retention

Rows accumulate forever unless you say otherwise. Put #[Purgeable] from jul6art/core-bundle on your concrete entity (see step 1) and core:purge applies it.

There is deliberately no audit.retention option in this bundle: the retention lives on your entity. To make it an operational setting, let the interval name a parameter — jul6art/core-bundle ≥ 3.2 resolves it when core:purge runs, so an environment variable changes the purge with no rebuild and no migration:

With an older core-bundle, the interval must be a literal.

The bundle listens to core-bundle's EntityPurgedEvent and writes one entity.purged row per purged line, naming the entity, its id, its organisation and the interval that condemned it. That matters more than it looks: retention deletes for good, and the trail is the only remaining evidence the data existed.

Configuration

audit.enabled is also exposed as a container parameter.

Quality assurance

License

The Audit Bundle is open-sourced software licensed under the MIT license.

© 2026 jul6art