README

A lightweight Symfony bundle to automatically audit and historize Doctrine ORM entity changes (create/update/delete) with optional async persistence via Symfony Messenger.

Designed for Symfony 7.4+ / 8.x, PHP 8.3+.

Features

✅ Opt-in auditing with PHP Attributes:
- #[Audited] on a Doctrine entity class to enable auditing
- #[AuditLabel('…')] on an entity class to override the displayed label
- #[AuditIgnore] on an entity property to exclude it from audits (PII/secrets/noise)
✅ Captures create / update / delete actions
✅ Stores audit records in a History entity (Doctrine ORM)
✅ Supports async writing using Symfony Messenger (recommended)
✅ Extensible: actor resolver, label strategy, change detector, writer…

Requirements

PHP 8.3+
Symfony 7.4+ (Symfony 8.x supported)
Doctrine ORM + DoctrineBundle
Symfony Messenger (optional but recommended for async)

Installation

composer require zhortein/auditable-bundle

If you don’t use Symfony Flex recipes, enable the bundle:

// config/bundles.php
return [
    // ...
    Zhortein\AuditableBundle\ZhorteinAuditableBundle::class => ['all' => true],
];

Doctrine mapping & migrations

The bundle ships a Doctrine entity (AuditEntry). Its mapping is registered automatically by a compiler pass, so you don't need to declare a doctrine.orm.mappings entry manually.

Generate and run migrations after installation:

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

This creates the audit_entry table with the necessary schema for storing audit trail entries.

Quick start

1) Mark entities as audited

use Zhortein\AuditableBundle\Attribute\Audited;
use Zhortein\AuditableBundle\Attribute\AuditLabel;
use Zhortein\AuditableBundle\Attribute\AuditIgnore;

#[Audited]
#[AuditLabel('Customer')]
class Customer
{
    private string $email;

    #[AuditIgnore]
    private string $passwordHash;
}

2) (Recommended) Configure async message handling

By default, the bundle is configured for async persistence via Symfony Messenger.

Step A: Define the Messenger transport

If your project doesn't already have a Messenger async transport, add one:

# config/packages/messenger.yaml
framework:
  messenger:
    transports:
      async: '%env(MESSENGER_TRANSPORT_DSN)%'
    routing:
      'Zhortein\AuditableBundle\Message\PersistAuditEntryMessage': async

See config/packages/messenger.yaml.example in the bundle for a complete configuration example.

Step B: Configure the bundle

Create or update the bundle configuration:

# config/packages/zhortein_auditable.yaml
zhortein_auditable:
  enabled: true
  async:
    enabled: true
    transport: 'async'

See config/packages/zhortein_auditable.yaml.example in the bundle for all available options.

Synchronous mode (optional)

If you prefer synchronous persistence (audit records written immediately without Messenger):

zhortein_auditable:
  enabled: true
  async:
    enabled: false

Note: Async mode is recommended for production to avoid blocking request handling with database writes.

Configuration reference

The bundle's configuration options are documented with comments in config/packages/zhortein_auditable.yaml.example.

Key settings:

enabled: Master switch to enable/disable auditing globally (default: true)
async.enabled: Use Messenger for async persistence (default: true)
async.transport: Messenger transport name for audit messages (default: 'async')
listener.track_insert/update/delete: Control which operations are tracked (all default to true)
fields.max_string_length: Maximum length for serialized field values (default: 180)
fields.global_ignored: List of properties to always exclude from all entities (default: [])

Actor resolution:

By default, the bundle uses Symfony Security to resolve the current user via SecurityActorResolver. No additional configuration is needed.

The resolver automatically handles:

Regular authenticated users → stores user ID or user identifier
Null users (not authenticated) → stores null
Impersonation → stores both original user and impersonator IDs

What gets stored

Each AuditEntry record in the audit trail contains:

Entity metadata: Fully qualified class name and entity ID
Action: One of create, update, delete, or log
Level: Severity level (debug, info, warning, error, critical)
Title & Description: Human-readable summary of the change
Context: Optional context tag for grouping related entities
Actor: User ID or identifier of who made the change (null if unauthenticated)
Impersonator: Original user ID if the change was made during impersonation
Timestamp: When the change occurred (as DateTimeImmutable)
Data: JSON-encoded field changes (old value → new value), excluding #[AuditIgnore] properties

Example audit entry for an update:

Title: "Update [Customer] - 2 field(s) changed"
Description: 
  - "Email: john@example.com → john.doe@example.com"
  - "Phone: +1234567890 → +1987654321"
Data: { "email": { "old": "john@example.com", "new": "john.doe@example.com" }, ... }

Security / PII

This bundle is meant to help you build auditable applications—but you are responsible for what you store.

Use #[AuditIgnore] for secrets (password hashes, tokens) and sensitive data that should not be persisted in audit logs.
Consider encrypting audit payloads or restricting access to the History table depending on your domain constraints.

License

MIT (see LICENSE]).

zhortein / auditable-bundle

Maintainers

Details