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

Links

• Packagist: rcsofttech/audit-trail-bundle
• Issues: GitHub issue tracker
• Changelog: CHANGELOG.md
• Contributing: CONTRIBUTING.md

License

MIT License.