Download the PHP package metadev/doctrine-audit-trail-bundle without Composer

DoctrineAuditTrailBundle

Automatic, opt-in audit trail for Doctrine entity mutations on Symfony.

Every create / update / delete of a marked entity is recorded as a structured AuditTrailEntry row: the entity class and id, the action, a JSON before/after diff, and the actor (authenticated user with IP / user-agent, or a fallback label for CLI / messenger / anonymous contexts).

• Opt-in: only entities annotated with #[Auditable] are tracked.
• Synchronous & safe: diffs are computed in onFlush, written in postFlush through a dedicated entity manager so the audited unit of work is never touched and the listener never re-enters itself.
• Extensible: value formatting and actor resolution are swappable.
• GDPR-aware: ships a built-in blacklist of common secret/credential field names (password, apiKey, accessToken, …), per-field ignore via #[AuditIgnore], and a global ignored_fields list. It provides the primitives to comply — retention, anonymisation and access control remain the integrator's responsibility.

Table of contents

• Requirements
• Installation
• Host wiring
• Configuration
• Marking entities
• Reading the trail
• Extension points
• Quality & tests
• Contributing
• License

Requirements

The CI matrix runs on PHP 8.2 / 8.3 / 8.4 / 8.5 against Symfony 6.4 / 7.x / 8.x (Symfony 8 requires PHP ≥ 8.4), plus a --prefer-lowest run on PHP 8.2 + Symfony 6.4.

Installation

Register the bundle (Symfony Flex does this automatically):

Host wiring

The bundle persists logs through a dedicated entity manager (named audit by default). You declare the manager and its connection; the bundle ships and registers the AuditTrailEntry mapping onto it (via prependExtension()).

Keeping the audit store on its own connection means schema management for the audit table never collides with the application's own tables.

Create the table:

Tamper-evidence & hardening

Production prerequisite. The bundle only ever needs INSERT and SELECT on the audit table. Grant nothing more, and physically reject UPDATE / DELETE / TRUNCATE at the database level — audit data is more sensitive than the source data, and an append-only store is the strongest tamper prevention control.

Ship-ready DDL (least-privilege grants + append-only triggers for PostgreSQL and MySQL) is provided in docs/hardening.sql. For tamper evidence that survives even a privileged DBA or a restored backup, enable the optional cryptographic HMAC seal.

Configuration

Consistency model

Audit entries are written through a dedicated entity manager with its own connection. This keeps your application's unit of work untouched, but it means the audit write is not part of your business transaction. Two trade-offs follow, and you choose how to handle them via persistence:

• soft_fail: true — a failing audit write is caught and logged via the PSR logger instead of surfacing to the caller. Availability over durability: an entry may be dropped (logged as an error), but the request keeps working. The log context includes dropped_entries and total_entries so operators can quantify the loss without reproducing the failure. In async mode, soft_fail only catches dispatch failures (broker unreachable, transport rejected the envelope). Once a message has been accepted by the broker, worker failures are handled by Symfony Messenger's retry/DLQ — they are intentionally not soft-failed, because doing so would ACK a failed message and silently drop audit data instead of letting the transport retry it.
• mode: async — requires symfony/messenger. Audit entries are dispatched to a transport and persisted by a worker, removing the write from the request hot path (latency, large unit-of-work pressure). createdAt and the integrity signature are frozen at capture time, so relaying later does not alter the entry. Consistency is eventual; configure a retry/DLQ on the transport. Entries are split into chunks of batch_size (default 100) so a bulk flush never produces a single oversized message — useful because AMQP enforces a low frame_max (~128KB by default) and Redis Streams cap entry sizes. Each chunk is an independent message, so the audit batch is not atomic across chunks: one chunk may succeed while another retries or lands in the DLQ. Tune batch_size to keep the serialized payload comfortably below your transport's limit. When a dispatch fails mid-flush, the persister keeps attempting the remaining chunks (so a transient broker hiccup on chunk 1 does not silently take down chunks 2+); the aggregated failure is then either raised or — with soft_fail: true — logged as a single error carrying the exact dropped_entries count. Messages are stamped with DispatchAfterCurrentBusStamp, so when the audit triggers inside a Messenger handler the entries are only released if the parent handler completes successfully.

Strict atomicity (audit committed if and only if the business transaction commits) requires a transactional outbox and is not yet provided. Track it in the roadmap if you target regulated workloads.

Marking entities

Entities without #[Auditable] are ignored.

The optional label is persisted on each row in the entity_label column — useful for admin UIs that want a human-readable name next to (or instead of) the FQCN.

Reading the trail

Extension points

Custom value formatter

The diff is produced by a chain of ValueFormatterInterface. The built-in ScalarValueFormatter handles scalars, DateTimeInterface, BackedEnum and Stringable. Anything else falls through unchanged — so association values are best handled with a custom formatter that extracts an identifier. Tag with a higher priority than the built-in formatter (which runs last):

Custom actor resolver

Implement AuditUserResolverInterface and point the config at it:

Anonymising actor PII (IP / identifier) — GDPR

The bundle is intentionally un-opinionated about anonymisation: it records the actor as resolved, and lets you apply your own policy. All actor PII (ipAddress, userIdentifier, userAgent) flows through AuditUserResolverInterface before the entry is persisted, so the cleanest approach is to decorate the default resolver and rewrite only what you need. AuditActor exposes immutable withIpAddress(), withUserIdentifier() and withUserAgent() copy helpers for exactly this:

This keeps anonymisation, salting and retention decisions in your compliance scope — the bundle only ships the primitives.

Labelling CLI / messenger actors

Inject AuditContextHolder and set an explicit actor; it takes precedence over automatic resolution and should be reset when done:

Cryptographic seal (HMAC)

For tamper evidence — detecting that a row's content was rewritten or its timestamp backdated, even by someone who bypassed the append-only DB grants — enable the optional per-row HMAC seal:

Every audit row is then sealed with HMAC-SHA256(secret, canonical_payload) in a nullable signature column. Verify the whole table at any time:

Run it from CI, a cron, or after restoring a backup. Because the secret lives outside the database, an attacker who can only write to the audit table cannot forge a valid signature.

Plug a KMS/Vault-backed secret by implementing SignatureProviderInterface and pointing the config at it:

Scope. The seal is computed per row: it proves a row was not altered, but on its own it does not detect the deletion of a whole row (there is no chaining — a deliberate choice to avoid serialising every audit write). Pair it with the append-only DB grants in docs/hardening.sql, which prevent deletion at the source. Existing rows written before enabling the seal verify as unsigned, not tampered.

Quality & tests

The bundle ships with a full quality pipeline: PHPUnit (unit + integration + functional), PHPStan level 8 and PHP-CS-Fixer.

Run a single test file or method:

Integration tests use in-memory SQLite — no Docker or database server required.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request, and make sure composer ci is green locally.

License

This bundle is released under the MIT License.

_{This README was generated with the help of Claude.}