Upgrade from 4.x to 5.0

This guide covers the changes needed when upgrading from auditor 4.x to 5.0.

Overview

auditor 5.0 completes the extraction of the Doctrine ORM provider into the standalone damienharper/auditor-doctrine-provider package. The DH\Auditor\Provider\Doctrine namespace has been removed from the core library.

The class FQCNs are identical in the external package — no code changes are required for most users.

Who is affected?

Migration Steps

1. Install the Doctrine provider package (if not already installed)

composer require damienharper/auditor-doctrine-provider:^2.0

2. Update auditor itself

composer require damienharper/auditor:^5.0

3. Update NeedsConversionToAuditableType imports (if applicable)

The interface has moved from the core package to the doctrine-provider package.

// Before (4.x)
use DH\Auditor\Transaction\NeedsConversionToAuditableType;

// After (5.0)
use DH\Auditor\Provider\Doctrine\Transaction\NeedsConversionToAuditableType;

Breaking Changes

Removed: DH\Auditor\Provider\Doctrine\* from core

The entire src/Provider/Doctrine/ namespace has been removed from damienharper/auditor. It is now exclusively provided by damienharper/auditor-doctrine-provider under the same namespace.

Removed: DH\Auditor\Transaction\NeedsConversionToAuditableType

This interface (introduced in 4.1, PR #309) required doctrine/dbal as a core dependency. It has moved to DH\Auditor\Provider\Doctrine\Transaction\NeedsConversionToAuditableType in auditor-doctrine-provider.

Removed: Doctrine packages from core require-dev

doctrine/dbal, doctrine/orm, doctrine/data-fixtures, and gedmo/doctrine-extensions are no longer installed when running composer install on damienharper/auditor alone.

Requirements Changes

Schema Version 2 (Breaking Changes)

auditor 5.0 also introduces a revised audit table format (schema v2). This section documents the breaking changes to the Entry read model and LifecycleEvent payload. The actual DDL migration is handled by audit:schema:migrate in auditor-doctrine-provider.

Removed: $entry->transactionHash

The transactionHash property has been removed. Use transactionId instead.

// Before (4.x)
$entry->transactionHash;    // SHA-1 VARCHAR(40) from transaction_hash column

// After (5.0)
$entry->transactionId;      // ULID CHAR(26) from transaction_id column

For un-migrated v1 rows, Entry::fromArray() automatically falls back to transaction_hash so that $entry->transactionId is still populated before your tables are migrated.

Changed: blame columns unified into $entry->blame

The four individual DB columns (blame_user, blame_user_fqdn, blame_user_firewall, ip) are replaced by a single blame JSON column. The convenience accessors are unchanged:

$entry->username;      // blame JSON → username key
$entry->userFqdn;      // blame JSON → user_fqdn key
$entry->userFirewall;  // blame JSON → user_firewall key
$entry->ip;            // blame JSON → ip key

// New: access the full blame array
$entry->blame;         // ['username' => ..., 'user_fqdn' => ..., 'user_firewall' => ..., 'ip' => ...]

For un-migrated v1 rows the individual columns are synthesised into a blame array automatically.

Changed: getDiffs() return value for schema v2 rows

For entries written with schema_version >= 2, getDiffs() now returns the changes sub-array from the unified diffs envelope. Legacy v1 entries are returned as-is (unchanged behaviour).

// schema_version = 1 (legacy): raw ['field' => ['old' => x, 'new' => y], ...] + [@source](https://github.com/source) stripped
// schema_version >= 2: envelope['changes'] = ['field' => ['old' => x, 'new' => y], ...]
$changes = $entry->getDiffs();

New: getDiffSource() — entity metadata from the diffs envelope

Returns the source block embedded in every v2 diffs envelope:

$source = $entry->getDiffSource();
// ['id' => '42', 'class' => 'App\Entity\Post', 'label' => 'My post', 'table' => 'post']
// Returns null for schema_version = 1 entries.

New: getDiffTarget() — target metadata for association entries

Returns the target block for associate/dissociate entries (schema v2 only):

$target = $entry->getDiffTarget();
// ['id' => '7', 'class' => 'App\Entity\Tag', 'label' => 'PHP', 'table' => 'tag']
// Returns null for non-association entries or schema_version = 1.

New: $entry->schemaVersion

$entry->schemaVersion;  // int: 1 (legacy) or 2 (current)

Changed: LifecycleEvent payload keys

Providers implementing persist(LifecycleEvent $event) must update any code that reads the old flat keys from $event->getPayload().

Migrating existing audit tables

[!IMPORTANT] audit:schema:update refuses to run while any audit table still has the legacy v1 schema. Run audit:schema:migrate first.

# Migrate DDL + convert transaction hashes + convert diffs in one pass
bin/console audit:schema:migrate --force --convert-all

See the auditor-doctrine-provider 2.0 upgrade guide for a step-by-step migration procedure.

Need Help?

• GitHub Issues
• auditor-doctrine-provider documentation