README

AuditTrailBundle records Doctrine ORM entity changes in Symfony applications. It captures changes during Doctrine flush, stores audit logs, supports multiple delivery transports, and provides tools for integrity verification, review, export, and recovery.

Documentation

Full documentation now lives on GitHub Pages:

Current docs: AuditTrailBundle 4.x documentation
Configuration: configuration reference
Transports: database, async database, queue, HTTP, and chain
Usage & AuditReader: attributes, context, events, and query API
Operations: revert, CLI, exports, and serialization
Upgrade & Architecture: upgrade guides and architecture notes

For older versions, use the README and docs from the matching GitHub tag unless archived public docs are added later.

Features

Doctrine entity audit logs for create, update, delete, soft-delete, restore, access, and revert flows
Split-phase architecture that avoids nested Doctrine flush() calls
Database, async database, queue, HTTP, and chain-style delivery options
PHP attributes for #[Auditable], #[AuditCondition], #[AuditAccess], and #[Sensitive]
Sensitive data masking with #[SensitiveParameter] and bundle-level sensitive fields
AuditReader API for history, filtering, diffs, changed fields, pagination, and existence checks
EasyAdmin integration, Symfony profiler support, CLI commands, exports, and revert tooling
HMAC signing for stored audit logs and transport payloads
Extension points for voters, context contributors, transports, AI metadata, and revert handlers

Quick Start

Install

composer require rcsofttech/audit-trail-bundle

Optional packages depend on the features you enable:

composer require symfony/messenger          # async database or queue transport
composer require symfony/http-client       # HTTP transport
composer require easycorp/easyadmin-bundle # EasyAdmin dashboard

Prepare The Database

The database transport is enabled by default. Generate and run a Doctrine migration for the audit log table:

php bin/console make:migration
php bin/console doctrine:migrations:migrate

Mark An Entity As Auditable

The example uses PHP 8.4 asymmetric property visibility (public private(set)) and constructor property promotion for normal entity fields. Keep the generated ID outside the constructor so callers cannot pass it accidentally.

<?php

declare(strict_types=1);

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Rcsofttech\AuditTrailBundle\Attribute\Auditable;

#[ORM\Entity]
#[Auditable(ignoredProperties: ['internalCode'])]
class Product
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    public private(set) ?int $id = null;

    public function __construct(
        #[ORM\Column(length: 180)]
        public private(set) string $name,

        #[ORM\Column]
        public private(set) int $priceInCents,

        #[ORM\Column(length: 40, nullable: true)]
        public private(set) ?string $internalCode = null,
    ) {
    }
}

Minimal Configuration

# config/packages/audit_trail.yaml
audit_trail:
    enabled: true
    ignored_properties: ['updatedAt', 'updated_at']
    retention_days: 365
    transports:
        database:
            enabled: true
            async: false

Requirements

PHP 8.4+
Symfony 7.4 or 8.0
Doctrine ORM 3.6+
DoctrineBundle 3.1+
ext-mbstring

License

MIT License.

rcsofttech / audit-trail-bundle

Maintainers

Package info

Fund package maintenance!

Statistics

Security