auditor 4.3.1

What's Changed

Documentation

• docs: fix dh_auditor.provider tag name in custom-provider guide
• docs: add local Claude Code customizations to .gitignore

Note: 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 to auditor-doctrine-provider ≥ 1.2.0, which includes the fix.

References

• auditor-doctrine-provider
• Official documentation

Full Changelog: 4.3.0...4.3.1

auditor 4.3.0

✨ What's new

Custom audit representation for Doctrine types

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:

1. Binary / non-UTF-8 data — types storing binary or encrypted data produce values
   that cannot be safely JSON-encoded, corrupting the diffs column.
2. Audit ≠ storage — the value written to the database (e.g. a hashed password,
   a serialised object) is sometimes intentionally different from what should appear
   in the audit trail.

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
    }
}

What's Changed

New features

• feat: allow custom Doctrine types to define their own audit representation by @byfareska in #309

Documentation

• docs: add guide for building a custom provider

References

• auditor-doctrine-provider
• Official documentation

Full Changelog: 4.2.0...4.3.0

auditor 4.2.0

✨ What's new

Support for long-running processes (Symfony Messenger workers)

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.

Wiring kernel.reset in Symfony

Tag 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.

What's Changed

Bug fixes

• fix: support long-running processes (Messenger workers) by @Spomky in #307

References

• auditor-doctrine-provider
• Official documentation

Full Changelog: 4.1.0...4.2.0

auditor 4.1.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-provider
as the new standalone home for Doctrine support.

✨ What's new

auditor-doctrine-provider — Doctrine support is now a standalone package

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 DoctrineProvider still works in
4.x — it is deprecated and will be removed in 5.0. Migrate at your own pace.

Core attribute namespace — DH\Auditor\Attribute

PHP 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.

🔨 Deprecations

The following are deprecated in 4.1 and will be removed in 5.0:

• All 36 classes, interfaces, and traits under DH\Auditor\Provider\Doctrine\ (use
  damienharper/auditor-doctrine-provider instead)
• DH\Auditor\Provider\Doctrine\Auditing\Attribute\Auditable → DH\Auditor\Attribute\Auditable
• DH\Auditor\Provider\Doctrine\Auditing\Attribute\Ignore → DH\Auditor\Attribute\Ignore
• DH\Auditor\Provider\Doctrine\Auditing\Attribute\Security → DH\Auditor\Attribute\Security

🚀 Migrating from 4.0

For 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.

What's Changed

Architecture

• Decouple Doctrine from core and deprecate built-in DoctrineProvider by @DamienHarper in #306
• Promote PHP attributes to core namespace DH\Auditor\Attribute by @DamienHarper in #304

Dependencies

• Bump actions/checkout from 4 to 6 by @dependabot in #300
• Bump actions/setup-node from 4 to 6 by @dependabot in #299
• Bump actions/upload-artifact from 6 to 7 by @dependabot in #303
• Bump actions/download-artifact from 7.0.0 to 8.0.0 by @dependabot in #302

References

• auditor-doctrine-provider
• Official documentation

Full Changelog: 4.0.0...4.1.0

auditor 4.0.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.

✨ What's new

Extra data — attach any context to audit entries

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.

JsonFilter — query your extra data

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');

NullFilter — audit query for NULL values

A dedicated NullFilter covers the IS NULL / IS NOT NULL case cleanly without workarounds.

Extra data provider — global context for every audit entry

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.

Query improvements

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.

⚡ Performance — up to 25% faster on real flush workloads

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):

Note on benchRemove and benchDissociate: 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 entity
• ClassMetadata resolved once per entity operation and propagated — no repeated lookups
• Static cache for DBAL type name resolution (array_search over the full type map, now runs at most once per type per request)
• getDatabasePlatform() and jsonTypes() hoisted out of per-field loops
• Audit INSERT statements memoized per table — no re-preparation within a single flush
• isAuditedField() checks inlined — entity config resolved once per diff(), not per field
• DateTimeZone instance memoized for the transaction processor lifetime
• array_reverse() on UoW scheduled-entity arrays replaced with in-place reverse-index iteration

utf8_convert is now opt-in

The 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, /* ... */])

🐛 Bug fixes

@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.

PostgreSQL 16 — false-positive schema migrations (#241)

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.

Quoted SQL identifiers in table names (#238)

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.

Multi-database MySQL/MariaDB schemas (#236)

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.

ManyToMany associations on unidirectional relations (#234)

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 values — false-positive audit entries (#278)

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.

MySQL — false-positive ALTER TABLE on every audit:schema:update run (#276)

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.

Multiple entity managers with disjoint namespace mappings (#281)

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.

SoftDeleteable — EntityNotFoundException when auditing a relation change (#285)

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.

SoftDeleteable — duplicate REMOVE audit entries (#296)

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.

🔨 Breaking changes

Updated requirements

PHP 8.4+ modernization

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:

Removed methods (DoctrineHelper)

Three long-deprecated static helpers have been removed in favour of native DBAL 4 equivalents:

Schema update required

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

🚀 Migrating from 3.x

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.

🛠 Developer experience

• Documentation moved in-repo — all docs live in docs/ and are versioned alongside the code.
• PHPBench benchmark suite — composer bench, composer bench:baseline, composer bench:compare for reproducible before/after comparisons.
• Blackfire profiling — make profile spins up the Blackfire agent as a Docker sidecar for flame-graph profiling.
• Updated CI matrix — PHP 8.4 and 8.5 × Symfony 8.0 × SQLite / MySQL / PostgreSQL / MariaDB.
• PHPStan 2.x, Rector 2.x, PHPUnit 12.x across the board.

What's Changed

Requirements & infrastructure

• Upgrade to PHP 8.4+, Symfony 8.0, Doctrine DBAL 4.x & ORM 3.x by @DamienHarper in #262
• Upgrade PHPStan 2.x, Rector 2.x, PHPUnit 12.x by @DamienHarper in #262
• Add CI workflow for 4.x matrix by @DamienHarper in #262
• DBAL 3.x dead code removal by @DamienHarper in #268

Modernization (PHP 8.4+)

• Introduce TransactionType enum, replace Transaction string constants by @DamienHarper in #264
• PHP 8.4 property hooks on Entry, User, Configuration by @DamienHarper in #264
• Replace EventSubscriberInterface with #[AsEventListener] by @DamienHarper in #264
• Replace setName()/setDescription() with #[AsCommand] by @DamienHarper in #264
• Rename Annotation namespace → Attribute, AnnotationLoader → AttributeLoader by @DamienHarper in #264

New features

• Extra data — extra_data JSON column and LifecycleEvent::$entity by @DamienHarper in #265
• JsonFilter for querying extra_data JSON paths by @DamienHarper in #266
• NullFilter 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 #267
• extra_data_provider callable on Configuration — attach global context to every audit entry without per-entity listeners by @DamienHarper in #298

Performance

• 10 flush-pipeline micro-optimizations (~25% on insert/update/mixed) by @DamienHarper in #270
• utf8_convert made opt-in (default: false) by @DamienHarper in #270
• PHPBench benchmark suite + Blackfire profiling support by @DamienHarper in #271

Bug fixes

• Fix auditing entities with a @Id ManyToOne association (#249) by @DamienHarper in #269
• Fix continuous schema migrations on PostgreSQL 16 caused by spurious charset/collation column platform options (#241) by @DamienHarper in #272
• Fix invalid audit table names for quoted SQL identifiers — PostgreSQL reserved words such as "user" now produce "user_audit" instead of "user"_audit (#238) by @DamienHarper in #273
• Fix broken table names when entities use a schema 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
• Fix ManyToMany association/dissociation changes silently dropped when only the owning-side entity carries #[Auditable] — unidirectional relations now produce associate/dissociate audit entries (#234) by @DamienHarper in #275
• Fix false-positive ALTER TABLE on every audit:schema:update run on MySQL without defaultTableOptions — STRING column platformOptions (charset/collation) are now preserved during schema update (#276) by @DamienHarper in #277
• Fix false-positive audit entries for decimal columns when numerically equal values differ only in string representation (e.g. "60.00" vs "60") — decimal strings are now normalised before comparison (#278) by @DamienHarper in #279
• Fix crash when using multiple entity managers with namespace-restricted MappingDriverChain 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 #294
• Fix EntityNotFoundException 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 #295
• Fix duplicate REMOVE audit entries on soft-delete — Transaction::remove() now deduplicates entities to ensure exactly one entry regardless of listener registration order (#296) by @DamienHarper in #297

Documentation

• Documentation moved in-repo (docs/) by @DamienHarper in #263
• Extra data guide with Mermaid diagrams by @DamienHarper in #265
• JsonFilter documentation and JSON indexing guides by @DamienHarper in #266
• Full v4 upgrade guide by @DamienHarper in #264

References

• Full upgrade guide (3.x → 4.0)
• Official documentation
• UPGRADE-4.0.md

Full Changelog: 3.4.0...4.0.0

What's Changed

• Bump actions/upload-artifact from 4 to 5 by @dependabot[bot] in #250
• Bump actions/download-artifact from 5.0.0 to 6.0.0 by @dependabot[bot] in #251
• Bump actions/checkout from 5 to 6 by @dependabot[bot] in #253
• Update doctrine/data-fixtures dependency, supersedes #231 by @DamienHarper in #254
• Bump actions/download-artifact from 6.0.0 to 7.0.0 by @dependabot[bot] in #255
• Bump actions/cache from 4 to 5 by @dependabot[bot] in #256
• Bump actions/upload-artifact from 5 to 6 by @dependabot[bot] in #257
• Jsonb support by @dmitryuk in #260
• Allow Symfony 8 and add PHP 8.4 and 8.5 to the test matrix by @janklan in #259
• Fixed retrieving primary key for target entity by @NH-JZ in #258

New Contributors

• @NH-JZ made their first contribution in #258

References

Official documentation

Full Changelog: 3.3.4...3.4.0

What's Changed

• Bump codecov/codecov-action from 4 to 5 by @dependabot[bot] in #233
• Bump actions/download-artifact from 4.1.8 to 4.1.9 by @dependabot[bot] in #240
• Bump actions/download-artifact from 4.1.9 to 4.2.1 by @dependabot[bot] in #242
• Fix Doctrine deprecates by @dmitryuk in #247
• Bump actions/download-artifact from 4.2.1 to 5.0.0 by @dependabot[bot] in #245
• Bump actions/checkout from 4 to 5 by @dependabot[bot] in #246

References

Official documentation

Full Changelog: 3.3.3...3.3.4

What's Changed

• Fix DBAL mapping access as Array is deprecated by @dmitryuk in #237

References

Official documentation

Full Changelog: 3.3.2...3.3.3

What's Changed

• Revert unwanted change about UUID to string conversion, fixes #230 by @DamienHarper in 490ffe8
• Make Reader and Query implement interfaces so that their mocking is easier, fixes #201 by @DamienHarper in 7feab9d
• Add support to quoted entity table names, fixes #196 by @DamienHarper in a6f1b93

References

Official documentation

Full Changelog: 3.3.1...3.3.2

What's Changed

• Inherit defaultTableOptions by @oleg-andreyev in #232

References

Official documentation

Full Changelog: 3.3.0...3.3.1