4.3.1

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

4.3.0

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

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

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

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

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

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

3.3.4

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

3.3.3

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

3.3.2

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

3.3.1

What's Changed

• Inherit defaultTableOptions by @oleg-andreyev in #232

References

Official documentation

Full Changelog: 3.3.0...3.3.1