Audit Log

View Options

Override configureAuditLog() in your controller to customize the page:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

use EasyCorp\Bundle\EasyAdminProBundle\AuditLog\Config\AuditLog;
use EasyCorp\Bundle\EasyAdminProBundle\AuditLog\Option\DateTimeFormat;
use Symfony\Component\Security\Core\User\UserInterface;

public function configureAuditLog(): AuditLog
{
    return AuditLog::new()
        ->setPageSize(40)
        ->setUserName(
            fn (?UserInterface $user): string =>
                $user?->getUserIdentifier() ?? '-',
        )
        ->setDateTimeFormat(DateTimeFormat::Medium, DateTimeFormat::Short);
}

The available options are:

setPageSize(int $pageSize)

Number of entry groups shown per page. Defaults to 40 in the controller that ships with the bundle (and to 30 when you build an AuditLog object without calling it). Must be a positive integer.

setUserName(\Closure $callback)

Format the actor's name. The callback receives your user entity, or null if it can't be found, and returns the name to display.

displayUserName(bool $display = true)

Whether to show the actor's name. Enabled by default.

displayUserAvatar(bool $display = true)

Whether to show the actor's avatar. Disabled by default.

setAvatarUrl(\Closure $callback)

Return an avatar URL for the user passed to the callback. Enable avatars with displayUserAvatar() to display it.

setGravatarEmail(\Closure $callback)

Return the user's email address for a Gravatar avatar. This is used when no avatar URL callback is set.

setDateTimeFormat(DateTimeFormat $dateFormat, DateTimeFormat $timeFormat)

Choose None, Short, Medium, Long or Full for each part of the timestamp. Both default to Short.

Tracked Actions

For every tracked entity, the Doctrine listener records these actions:

• Created (entity.created): a new entity was persisted.
• Updated (entity.updated): a tracked property changed.
• Deleted (entity.deleted): the entity was removed.
• Restored (entity.restored): a previously soft-deleted entity was brought back.

Changes to owning-side associations (ManyToOne and the owning side of OneToOne) are tracked as well, because Doctrine includes them in the entity change set. Changes to collection-valued associations (OneToMany and ManyToMany) are not tracked. The full snapshot stored for create and delete entries includes every to-one association, owning or inverse side.

Soft deletes are tracked by default (track_soft_deletes). The bundle recognizes a soft delete by the conventional deletedAt field: when that field goes from null to a date, the change is recorded as a delete instead of an update, and the reverse is recorded as a restore. If an entity uses a different field name, map it with soft_delete_field:

1
2
3
4
5

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    audit_log:
        soft_delete_field:
            'App\Entity\Order': archivedAt

Choosing Which Entities Are Tracked

By default the audit log tracks every Doctrine entity in your application (included_entities: '*'). To limit tracking to a specific set of entities, replace '*' with a list of entity FQCNs:

1
2
3
4
5
6

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    audit_log:
        included_entities:
            - 'App\Entity\Order'
            - 'App\Entity\Invoice'

Use excluded_entities to keep tracking everything except a few classes:

1
2
3
4
5

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    audit_log:
        excluded_entities:
            - 'App\Entity\WebhookLog'

Excluding Sensitive Properties

Some properties must never appear in the audit log. The excluded_properties.global option lists property names that are stripped from the diff of every entity. It defaults to a set of common sensitive property names:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    audit_log:
        excluded_properties:
            global:
                - password
                - plainPassword
                - salt
                - token
                - apiKey
                - secret
                - twoFactorCode
                - resetToken
                - confirmationToken
            entities:
                'App\Entity\User':
                    - lastLoginIp
                'App\Entity\Payment':
                    - cardNumber
                    - cvv

The entities map adds per-entity exclusions on top of the global list. Excluded properties are removed from the recorded diff, but the audit entry itself is still created when other properties change.

This is different from skip_if_only_changed, which discards the entire audit entry (no row is written at all) when the only properties that changed are in the list. It applies to updates only; create, delete and restore entries are always recorded. Use it for noisy bookkeeping fields such as updatedAt or lastLoginAt that would otherwise create an entry on every request:

1
2
3
4
5
6
7
8
9
10

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    audit_log:
        skip_if_only_changed:
            global:
                - updatedAt
            entities:
                'App\Entity\User':
                    - lastLoginAt
                    - currentSessionToken

If one of those properties changes alongside a tracked property, the entry is still created and includes the changes normally.

Tracking Scope

The tracking_scope option controls in which context Doctrine entity changes are recorded:

all (default)

Record changes everywhere: inside EasyAdmin, in your own controllers, in commands, in Messenger handlers, and so on.

only_easyadmin

Record changes only when they happen inside an EasyAdmin backend request. Changes made elsewhere are ignored.

except_easyadmin

Record changes everywhere except inside EasyAdmin backend requests.

The client IP address is stored with each entry by default. Set store_ip_address to false to omit it (for example, to reduce the amount of personal data you retain).

Write Failure Policy

By default, an audit write failure is logged and your application keeps the entity change (on_write_failure: fail_open). Choose fail_closed if a change must not succeed without an audit entry:

1
2
3
4

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    audit_log:
        on_write_failure: fail_closed

For this guarantee, the audit log must use the same database connection as the entity. The change and its audit entry then commit or roll back together. With separate connections, fail_closed reports the error, but the entity change has already been committed and cannot be rolled back.

Migrations pause logging automatically (see Migrations).

Manual Disable / Enable

When the callback shape does not fit the workflow (streaming work with intermediate flushes and recoverable errors), call disable() and enable() explicitly:

1
2
3
4
5
6
7
8
9
10

$this->auditLogger->disable();
try {
    foreach ($this->stream->records() as $batch) {
        $this->em->persist($batch);
        $this->em->flush();
        $this->em->clear();
    }
} finally {
    $this->auditLogger->enable();
}

Call isEnabled() when you need to know whether logging is currently active, for example to skip work that only matters when entries are being recorded.

Migrations

Audit logging pauses automatically while Doctrine migrations run, provided doctrine/migrations is installed. You don't need to disable it yourself. Direct SQL changes aren't tracked by the Doctrine ORM listener in any case.

If you want to record that a migration completed, call log() from a command or service after the migration.

Disabling the Audit Log in the Test Environment

If you don't need audit entries in your tests, disable the feature for the test environment:

1
2
3
4
5

# config/packages/easyadmin_pro.yaml
when@test:
    easyadmin_pro:
        audit_log:
            enabled: false

Keep it enabled in development to try out your audit setup. You can use withoutLogging() when loading fixtures.

Checkpoints

Run this command regularly, for example once a minute with cron or Symfony Scheduler:

1

$ php bin/console easyadmin:audit-log:checkpoint

It creates a checkpoint when either configured threshold is reached:

1
2
3
4
5
6
7

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    audit_log:
        integrity:
            checkpoints:
                every_entries: 1000
                max_age_seconds: 300

These thresholds are checked when the command runs; they don't start a background task. To cover pending entries immediately, bypass the thresholds with --force:

1

$ php bin/console easyadmin:audit-log:checkpoint --force

If all entries are already covered, no new checkpoint is created.

Anchoring Checkpoints Off-Site

Keep checkpoint copies outside the database, in storage your application cannot overwrite or delete. These copies give you an independent record to compare against if the database is changed or restored from a backup.

Use JSON output to export the signed checkpoint:

1

$ php bin/console easyadmin:audit-log:checkpoint --format=json

Connect this output to your archival process, for example using storage with a write-once retention policy. When created is true, archive the returned checkpoint, including its payload and signature. The bundle doesn't upload checkpoints or compare them with external copies for you.

Verifying the Chain

Check the stored entries and checkpoints with:

1

$ php bin/console easyadmin:audit-log:verify

The command only reads data. Schedule it regularly and alert on a non-zero exit code:

For scripts, use --format=json and check exit_code. Other useful options are --chain=<id> to verify an older chain and -v to print full hashes in the text report. Disabled integrity and unexpected errors also produce exit code 2.

Entries recorded before integrity was enabled are counted separately; they have no signatures and aren't included in chain verification.

Understanding the Guarantees

Verification detects altered entries and broken links, including gaps caused by deleted or reordered entries. It also checks the end of the chain against the stored chain head and signed checkpoints.

There are three limits to keep in mind:

• A valid chain doesn't prove that every application change was logged. For that, use fail_closed on the same database connection as your entities (see Write Failure Policy).
• Someone with database write access can remove entries after the latest checkpoint and rewind the chain head without local verification detecting it. Frequent checkpoints keep this window small.
• Someone with both database write access and a signing key can rewrite entries and local checkpoints. Checkpoints stored independently outside the database let you detect changes to the history they cover.

Integrity makes changes detectable; it doesn't prevent database edits. A successful local check also can't detect a whole database restored to an older, internally consistent backup. See Restoring a Database Backup.

Rotating Keys

To switch signing keys, add the new secret to your key ring and select it as the active key:

1
2
3
4
5
6
7
8

# config/packages/easyadmin_pro.yaml
easyadmin_pro:
    audit_log:
        integrity:
            active_key_id: 'audit-2026-07'
            keys:
                audit-2026-01: '%env(AUDIT_LOG_HMAC_KEY)%'
                audit-2026-07: '%env(AUDIT_LOG_HMAC_KEY_NEXT)%'

Deploy the configuration to every application process, including workers, then create and export a checkpoint. New entries use the new key; existing entries keep their original signatures. For a rolling deployment, distribute the new key to all processes before changing active_key_id.

Keep old keys for as long as any entry or checkpoint needs them. The verification report lists these under key_ids_seen. Checkpoints are never deleted by cleanup, so a key that signed one must be retained indefinitely.

Use stable key names of up to 64 characters, starting with a letter or digit and containing only letters, digits, ., _ or -. The algorithm option supports sha256 (default), sha384 and sha512. Changing it affects new signatures; old ones remain verifiable.

How Retention Interacts With Integrity

When integrity is enabled, entries are not deleted individually: the log is a hash chain, and removing an arbitrary entry would break it. Cleanup therefore deletes only whole segments that a checkpoint has already closed, always starting from the oldest, so the surviving chain stays verifiable. The checkpoint that closed the last deleted segment becomes the trusted starting point of what remains.

This has two consequences:

• The open tail is never deleted. Entries newer than the last checkpoint are always kept, whatever their age. If a cleanup reports that everything was retained, create a checkpoint first and run it again:

  1
  2

  $ php bin/console easyadmin:audit-log:checkpoint --force
  $ php bin/console easyadmin:audit-log:cleanup --older-than="6 months" --force

• Retention granularity equals the checkpoint cadence. When the cutoff date falls inside a checkpointed segment, that whole segment is kept. Deletion never leaves a partial segment behind.

The checkpoints and the chain head are never deleted, so the log stays verifiable after cleanup. When integrity is disabled, the command deletes by date without the checkpoint restriction.

--all forces a final checkpoint over the full history before deleting every entry, then keeps the chain head and all checkpoints: the next entry continues at the next sequence, chained to the head's last hash.

Starting a New Chain

Use --reset-chain to close the current chain with a final checkpoint and begin a brand-new one. It deletes nothing, but it requires both the audit log and its integrity feature to be enabled (otherwise the command fails with exit code 1):

1
2
3
4
5

# preview the reset (dry-run)
$ php bin/console easyadmin:audit-log:cleanup --reset-chain

# actually reset the chain
$ php bin/console easyadmin:audit-log:cleanup --reset-chain --force

The old chain stays in the database, still verifiable with easyadmin:audit-log:verify --chain=<old id>, while new entries begin a fresh chain at sequence 1. The stream's checkpoint history links across the reset, so it stays continuous. This is the explicit, recorded way to start over. See Restoring a Database Backup for when you need it.