dh_auditor.provider tag name in custom-provider guideNote: A bug affecting inverse-side OneToMany association auditing when multiple entities are flushed together (issue #310) has been identified in the deprecated built-in
DoctrineProvider. It will not be backported. Users relying on this behaviour should migrate toauditor-doctrine-provider≥ 1.2.0, which includes the fix.
Full Changelog: https://github.com/DamienHarper/auditor/compare/4.3.0...4.3.1
Introduces the NeedsConversionToAuditableType interface, allowing Doctrine type authors
to decouple their audit representation from their database representation.
Previously, the auditor always called convertToDatabaseValue() to produce the value
stored in the diffs column. This caused two practical problems:
diffs column.A Doctrine type implementing NeedsConversionToAuditableType provides a
convertToAuditableValue() method that the auditor calls instead of
convertToDatabaseValue() when building diffs.
use DH\Auditor\Transaction\NeedsConversionToAuditableType;
use Doctrine\DBAL\Platforms\AbstractPlatform;
use Doctrine\DBAL\Types\Type;
final class BinaryStringType extends Type implements NeedsConversionToAuditableType
{
// ...
public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): ?string
{
return $value?->getBinary(); // raw binary — not audit-safe
}
public function convertToAuditableValue(mixed $value, AbstractPlatform $platform): string
{
return $value?->toBase64(); // human-readable audit representation
}
}
Full Changelog: https://github.com/DamienHarper/auditor/compare/4.2.0...4.3.0
When using auditor inside Symfony Messenger workers, only the first message was audited
correctly. Subsequent messages silently failed because the DoctrineSubscriber held a stale
EntityManager reference after reset, and DoctrineProvider reused cached PreparedStatement
objects bound to a closed connection.
DoctrineProvider now implements Symfony\Contracts\Service\ResetInterface. Its reset()
method clears the prepared statement cache and resets all subscriber transaction caches,
ensuring clean state between messages.
DoctrineSubscriber now retrieves the EntityManager directly from event arguments
(OnFlushEventArgs, LifecycleEventArgs) instead of relying on a constructor-injected
reference that could become stale.
kernel.reset in SymfonyTag DoctrineProvider with kernel.reset so that Symfony's services_resetter calls
reset() automatically between messages:
# config/services.yaml
services:
DH\Auditor\Provider\Doctrine\DoctrineProvider:
tags:
- { name: kernel.reset, method: reset }
If your service definition uses autoconfigure: true, Symfony detects ResetInterface
and registers the tag automatically — no additional config needed.
Full Changelog: https://github.com/DamienHarper/auditor/compare/4.1.0...4.2.0
A milestone release on the road to 5.0. auditor 4.1 decouples the core package from Doctrine ORM/DBAL, promotes PHP attributes to a provider-agnostic core namespace, and introduces
auditor-doctrine-provideras the new standalone home for Doctrine support.
The DoctrineProvider and all related classes have been extracted from auditor into a
dedicated package: damienharper/auditor-doctrine-provider.
The auditor core is now Doctrine-free. Only symfony/event-dispatcher and
symfony/options-resolver remain as hard dependencies — making it easier to use auditor
with any ORM or persistence layer.
composer require damienharper/auditor-doctrine-provider
No action required for existing users. The built-in
DoctrineProviderstill works in 4.x — it is deprecated and will be removed in 5.0. Migrate at your own pace.
DH\Auditor\AttributePHP attributes (#[Auditable], #[Ignore], #[Security]) are now defined in the
provider-agnostic core namespace DH\Auditor\Attribute, making them available to any
provider — not just Doctrine.
// Before (4.0, still works but deprecated)
use DH\Auditor\Provider\Doctrine\Auditing\Attribute\Auditable;
// After (4.1, canonical)
use DH\Auditor\Attribute\Auditable;
The old DH\Auditor\Provider\Doctrine\Auditing\Attribute\* classes remain as deprecated
thin extensions through 4.x and will be removed in 5.0. The AttributeLoader recognises
both namespaces transparently — no change needed on entities that already use the old import.
The following are deprecated in 4.1 and will be removed in 5.0:
DH\Auditor\Provider\Doctrine\ (use
damienharper/auditor-doctrine-provider instead)DH\Auditor\Provider\Doctrine\Auditing\Attribute\Auditable → DH\Auditor\Attribute\AuditableDH\Auditor\Provider\Doctrine\Auditing\Attribute\Ignore → DH\Auditor\Attribute\IgnoreDH\Auditor\Provider\Doctrine\Auditing\Attribute\Security → DH\Auditor\Attribute\SecurityFor most applications the migration boils down to:
# 1. Install the standalone provider
composer require damienharper/auditor-doctrine-provider
# 2. Update attribute imports (optional in 4.x, required before 5.0)
# DH\Auditor\Provider\Doctrine\Auditing\Attribute\* → DH\Auditor\Attribute\*
No schema changes. No behavioral changes. Audit data is fully preserved.
DoctrineProvider by @DamienHarper in #306DH\Auditor\Attribute by @DamienHarper in #304Full Changelog: https://github.com/DamienHarper/auditor/compare/4.0.0...4.1.0
The biggest release since 3.0, auditor 4.0 is a full modernization of the library: it drops legacy compatibility layers, embraces PHP 8.4+, Symfony 8, and Doctrine 4/ORM 3 — and comes with meaningful new features and a ~25% performance improvement on real-world flush workloads.
Audit entries can now carry arbitrary supplementary data through a new nullable JSON extra_data column. Wire up a LifecycleEvent listener, inspect the audited entity, and populate whatever context matters to your application — the current HTTP request, the user's role at the time, a business workflow step, anything.
// Attach extra context from a Symfony service
class AuditEnricher
{
#[AsEventListener]
public function onAudit(LifecycleEvent $event): void
{
$event->getPayload()['extra_data'] = [
'ip' => $this->requestStack->getCurrentRequest()?->getClientIp(),
'role' => $this->security->getUser()?->getRoles(),
];
}
}
After upgrading, run audit:schema:update --force to add the column. See the Extra Data guide.
A new JsonFilter lets you query the extra_data column with a clean, expressive API. Nested JSON paths, all the standard operators, and native JSON indexing support for MySQL, MariaDB, PostgreSQL, and SQLite out of the box.
// Find all audit entries where extra_data.role = "ROLE_ADMIN"
$filter = new JsonFilter('extra_data', 'role', '=', 'ROLE_ADMIN');
A dedicated NullFilter covers the IS NULL / IS NOT NULL case cleanly without workarounds.
A new extra_data_provider callable on Configuration lets you attach context to every audit entry automatically, without wiring up a LifecycleEvent listener on each entity. Set it once and the return value is merged into extra_data for all audit entries produced during a flush.
$configuration->setExtraDataProvider(function (): ?array {
return [
'ip' => $this->requestStack->getCurrentRequest()?->getClientIp(),
'role' => $this->security->getUser()?->getRoles(),
];
});
The provider runs before the LifecycleEvent listener, so per-entity listeners can override or extend the global context. See the Extra Data guide for the full precedence and merging rules.
resetQueryPart() lets you reset individual parts of a query (filters, orderBy, limit) without rebuilding it from scratch — useful when reusing a base query for multiple result sets.
Ten targeted micro-optimizations to the Doctrine flush pipeline reduce audit overhead significantly, with zero behavioral change. Measured with PHPBench (N=1000, PHP 8.5.3, xdebug off, in-memory SQLite):
| Workload | v3.4.0 | v4.0.0 | Gain |
|---|---|---|---|
| Insert (N entities) | 39.2ms | 29.6ms | −25% |
| Update (N entities, 3 fields) | 16.4ms | 12.3ms | −25% |
| Mixed (insert + update + remove) | 20.7ms | 16.2ms | −22% |
| Associate (ManyToMany) | 13.9ms | 13.0ms | −7% |
| Remove | 1.1ms | 1.2ms | ≈ 0 |
Note on
benchRemoveandbenchDissociate: these operations take ~1ms total, where audit overhead is smaller than measurement noise. They are not meaningfully impacted in either direction.
Key optimizations:
blame() (user/security providers) called once per transaction, not once per entityClassMetadata resolved once per entity operation and propagated — no repeated lookupsarray_search over the full type map, now runs at most once per type per request)getDatabasePlatform() and jsonTypes() hoisted out of per-field loopsINSERT statements memoized per table — no re-preparation within a single flushisAuditedField() checks inlined — entity config resolved once per diff(), not per fieldDateTimeZone instance memoized for the transaction processor lifetimearray_reverse() on UoW scheduled-entity arrays replaced with in-place reverse-index iterationutf8_convert is now opt-inThe implicit mb_convert_encoding() pass that ran on every audit entry has been removed from the default path. DBAL 4 enforces UTF-8 connections on PHP 8.4+ — the conversion was a no-op for virtually all modern applications.
If your application handles data from legacy non-UTF-8 sources, re-enable it explicitly:
new Configuration(['utf8_convert' => true, /* ... */])
[@Id](https://github.com/Id) ManyToOne association not audited (#249)Entities that use a ManyToOne relationship as their primary key (#[ORM\Id] #[ORM\ManyToOne]) were not correctly audited: the identifier resolution failed on the composite key structure, causing the audit entry to be skipped or malformed. The ID extraction now handles ManyToOne primary keys correctly.
When using PostgreSQL 16 with a UTF-8 database, doctrine:migrations:diff was generating a new (empty) migration on every run because auditor was setting charset/collation as per-column platform options. PostgreSQL does not support per-column charset/collation, so Doctrine's comparator detected a difference on every introspection cycle. Column platform options are now only propagated on MySQL/MariaDB where they are meaningful.
Entities mapped to PostgreSQL reserved words (e.g. #[ORM\Table(name: '"user"')]) caused malformed SQL — INSERT INTO "user"_audit instead of INSERT INTO "user_audit" — because the audit suffix was appended outside the closing quote. Both the reader and the transaction processor now delegate to the pre-computed computed_audit_table_name stored in Configuration, which already handled quoting correctly since v3.x.
Applications that map entities across multiple MySQL/MariaDB databases using the schema attribute (e.g. #[ORM\Table(schema: 'other_db')]) experienced crashes: auditor was generating table names with a __ separator (other_db__user) instead of dot notation (other_db.user). MySQL supports cross-database access via database.table natively, and Doctrine ORM handles it correctly without any metadata modification. The __ separator and the metadata-rewriting behaviour of TableSchemaListener have been removed.
Association and dissociation changes on ManyToMany relations were silently ignored when only the owning-side entity carried #[Auditable]. The hydrator was requiring both entities to be audited before recording the event, but since the audit entry is written to the owner's audit table, only the owner needs to be audited. Unidirectional ManyToMany relations (and bidirectional ones where only the owner is auditable) now produce correct associate/dissociate entries.
Decimal columns storing numerically equal values in different string representations (e.g. "60.00" vs "60") were incorrectly triggering audit entries on update. The diff computation was doing a raw string comparison, so "60.00" and "60" were treated as different values. Decimal strings are now normalised (trailing zeros and unnecessary decimal points stripped) before comparison, so only genuine numeric changes produce an audit entry.
On MySQL without an explicit defaultTableOptions DBAL connection parameter, audit:schema:update was always emitting a no-op ALTER TABLE … CHANGE column column … statement for every STRING column, even when the audit table was already up-to-date. The root cause was that processColumns() unconditionally dropped and re-added STRING columns with platformOptions: [], while MySQL's introspector returns columns with explicit charset/collation in their platform options — the schema comparator therefore always detected a difference. The fix preserves the existing platformOptions when none are explicitly configured, keeping the desired schema identical to the introspected one.
Applications using multiple Doctrine entity managers with namespace-restricted MappingDriverChain drivers (the standard Symfony configuration) crashed during flush: Configuration::getEntities() iterated all registered entities for every auditing EM, and called getClassMetadata() for entities whose namespace was not covered by that EM's driver chain. Doctrine's MappingDriverChain throws MappingException: not found in the chain configured namespaces in this case. The fix uses isTransient() — which returns true without throwing for unmanaged classes — as a lightweight guard before calling getClassMetadata(). Unlike an getAllMetadata()-based allowlist, isTransient() uses reflection for path-based AttributeDriver and namespace-prefix matching for MappingDriverChain, so it correctly handles both standard and Symfony-style multi-EM setups.
Changing a ManyToOne field whose previous value pointed to an entity hidden by a Doctrine SQL filter (e.g. Gedmo SoftDeleteable) threw EntityNotFoundException during flush. AuditTrait::summarize() calls UoW::initializeObject() to hydrate the related proxy before building the diff; when the entity row is inaccessible (filtered out), Doctrine throws. The fix wraps initializeObject() in a try/catch and falls back to a minimal summary built from UoW::getEntityIdentifier() — which reads directly from Doctrine's identity map without touching the proxy's properties — producing a ClassName#ID label instead of crashing.
Soft-deleting an entity could produce two REMOVE audit entries instead of one, depending on the order in which Gedmo's SoftDeleteableListener and auditor's DoctrineSubscriber were registered on the event manager. Both TransactionHydrator::hydrateWithScheduledDeletions() and DoctrineSubscriber::postSoftDelete() could each add the same entity to the transaction, resulting in a duplicate entry. Transaction::remove() now deduplicates entities before processing, ensuring exactly one REMOVE audit entry is produced regardless of listener registration order.
| v3.x | v4.0 | |
|---|---|---|
| PHP | ≥ 8.2 | ≥ 8.4 |
| Symfony | ≥ 5.4 | ≥ 8.0 |
| Doctrine DBAL | ≥ 3.2 | ≥ 4.0 |
| Doctrine ORM | ≥ 2.13 | ≥ 3.2 |
The codebase has been rewritten to take full advantage of PHP 8.4, Symfony 8, and ORM 3. Each change has a straightforward mechanical replacement:
| What changed | Before (3.x) | After (4.0) |
|---|---|---|
| Transaction type constants | Transaction::INSERT |
TransactionType::INSERT |
| Entry access | $entry->getType() |
$entry->type |
| User access | $user->getIdentifier() |
$user->identifier |
| Configuration | $config->isEnabled() |
$config->enabled |
| Namespace | ...\Auditing\Annotation\* |
...\Auditing\Attribute\* |
| Loader class | AnnotationLoader |
AttributeLoader |
| Event listeners | EventSubscriberInterface |
#[AsEventListener] |
| Console commands | setName() / setDescription() |
#[AsCommand] |
| Entity in LifecycleEvent | not available | $event->entity |
Three long-deprecated static helpers have been removed in favour of native DBAL 4 equivalents:
| Removed | Replacement |
|---|---|
DoctrineHelper::createSchemaManager() |
$connection->createSchemaManager() |
DoctrineHelper::introspectSchema() |
$schemaManager->introspectSchema() |
DoctrineHelper::getMigrateToSql() |
See upgrade guide |
The new extra_data column must be added to existing audit tables:
# Preview the changes
bin/console audit:schema:update --dump-sql
# Apply them
bin/console audit:schema:update --force
A complete step-by-step upgrade guide is available in docs/upgrade/v4.md.
For most applications, the migration boils down to:
# 1. Update your dependencies
composer require \
damienharper/auditor:^4.0 \
symfony/framework-bundle:^8.0 \
doctrine/dbal:^4.0 \
doctrine/orm:^3.2
# 2. Apply the schema migration
bin/console audit:schema:update --force
# 3. Search-and-replace the renamed symbols (see table above)
# 4. Run your test suite
The breaking changes are mechanical — they are the natural outcome of dropping legacy compatibility shims and adopting modern PHP/Symfony/Doctrine idioms. No audit data is affected; the on-disk format is fully preserved.
docs/ and are versioned alongside the code.composer bench, composer bench:baseline, composer bench:compare for reproducible before/after comparisons.make profile spins up the Blackfire agent as a Docker sidecar for flame-graph profiling.TransactionType enum, replace Transaction string constants by @DamienHarper in #264Entry, User, Configuration by @DamienHarper in #264EventSubscriberInterface with #[AsEventListener] by @DamienHarper in #264setName()/setDescription() with #[AsCommand] by @DamienHarper in #264Annotation namespace → Attribute, AnnotationLoader → AttributeLoader by @DamienHarper in #264extra_data JSON column and LifecycleEvent::$entity by @DamienHarper in #265JsonFilter for querying extra_data JSON paths by @DamienHarper in #266NullFilter for IS NULL / IS NOT NULL query conditions by @DamienHarper in #263 (via feat commit)Query::resetQueryPart() to selectively reset query parts by @DamienHarper in #267extra_data_provider callable on Configuration — attach global context to every audit entry without per-entity listeners by @DamienHarper in #298utf8_convert made opt-in (default: false) by @DamienHarper in #270[@Id](https://github.com/Id) ManyToOne association (#249) by @DamienHarper in #269charset/collation column platform options (#241) by @DamienHarper in #272"user" now produce "user_audit" instead of "user"_audit (#238) by @DamienHarper in #273schema attribute on MySQL/MariaDB — the __ separator has been replaced by the correct . dot notation, and TableSchemaListener no longer mangles Doctrine class metadata (#236) by @DamienHarper in #274#[Auditable] — unidirectional relations now produce associate/dissociate audit entries (#234) by @DamienHarper in #275audit:schema:update run on MySQL without defaultTableOptions — STRING column platformOptions (charset/collation) are now preserved during schema update (#276) by @DamienHarper in #277"60.00" vs "60") — decimal strings are now normalised before comparison (#278) by @DamienHarper in #279MappingDriverChain drivers (Symfony-style multi-EM setup) — getClassMetadata() is now guarded by isTransient() to skip entities not managed by the current EM (#281) by @DamienHarper in #294EntityNotFoundException when auditing a ManyToOne relation change whose previous value points to an entity hidden by a Doctrine filter (e.g. SoftDeleteable) — initializeObject() now falls back to a ClassName#ID summary instead of crashing (#285) by @DamienHarper in #295REMOVE audit entries on soft-delete — Transaction::remove() now deduplicates entities to ensure exactly one entry regardless of listener registration order (#296) by @DamienHarper in #297docs/) by @DamienHarper in #263JsonFilter documentation and JSON indexing guides by @DamienHarper in #266Full Changelog: https://github.com/DamienHarper/auditor/compare/3.4.0...4.0.0
Full Changelog: https://github.com/DamienHarper/auditor/compare/3.3.4...3.4.0
Full Changelog: https://github.com/DamienHarper/auditor/compare/3.3.3...3.3.4
Full Changelog: https://github.com/DamienHarper/auditor/compare/3.3.2...3.3.3
Full Changelog: https://github.com/DamienHarper/auditor/compare/3.3.1...3.3.2
Full Changelog: https://github.com/DamienHarper/auditor/compare/3.3.0...3.3.1
Full Changelog: https://github.com/DamienHarper/auditor/compare/3.2.0...3.3.0
⚠️ diff format has slightly changed in audits: old and new keys are now only set when needed and their respective values can be nested diff arrays
Full Changelog: https://github.com/DamienHarper/auditor/compare/3.1.0...3.2.0
Full Changelog: https://github.com/DamienHarper/auditor/compare/3.0.1...3.1.0
Full Changelog: https://github.com/DamienHarper/auditor/compare/3.0.0...3.0.1
This release is focused on bringing Symfony 7, doctrine/orm 3.x and doctrine/dbal 4.x support as well as dropping PHP 8.0 and 8.1 compatibility.
ext-json requirement by @DamienHarper in https://github.com/DamienHarper/auditor/pull/191DoctrineHelper::getDoctrineType() by @DamienHarper in https://github.com/DamienHarper/auditor/pull/210diffs column type when JSON type is supported by @DamienHarper in https://github.com/DamienHarper/auditor/pull/170Full Changelog: https://github.com/DamienHarper/auditor/compare/2.4.8...3.0.0
ViewerController does not extend AbstractController anymore. So, if you use a custom controller extending ViewerController, you have to adjust it manually.Full Changelog: https://github.com/DamienHarper/auditor/compare/2.4.7...2.4.8
diffs column type when JSON type is supported (cf. #52) by @DamienHarper in https://github.com/DamienHarper/auditor/commit/2fd4f3efaeb54bb837e98e54ddffd04e037f4419Full Changelog: https://github.com/DamienHarper/auditor/compare/2.4.6...2.4.7
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.4.5...2.4.6
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.4.4...2.4.5
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.4.3...2.4.4
doctrine/orm 2.14 by @DamienHarper in https://github.com/DamienHarper/auditor/commit/929fe156162e3b5cbcd9cdfd1d61266e38ba1ee7Full Changelog: https://github.com/DamienHarper/auditor/compare/2.4.2...2.4.3
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.4.1...2.4.2
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.4.0...2.4.1
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.3.2...2.4.0
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.3.1...2.3.2
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.3.0...2.3.1
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.2.1...2.3.0
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.2.0...2.2.1
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.1.1...2.2.0
Full Changelog: https://github.com/DamienHarper/auditor/compare/2.1.0...2.1.1
How can I help you explore Laravel packages today?