AuditTrailBundle

Enterprise-grade, high-performance audit trail solution for Symfony.

AuditTrailBundle is a modern, lightweight bundle that automatically tracks and stores Doctrine ORM entity changes. Built for performance and compliance, it uses a unique Split-Phase Architecture to ensure your application stays fast even under heavy load.

---

Documentation

Topic	Description
Installation & Setup	Getting started guide.
Configuration	Full configuration reference (enabled, transports, integrity).
Advanced Usage	Attributes, Conditional Auditing, Impersonation, Custom Context.
Transports	Doctrine, HTTP, and Queue (Messenger) transport details.
Audit Reader	Querying audit logs programmatically.
Revert & Recovery	Point-in-time restoration of entities.
Security & Integrity	Data masking, cryptographic signing, and verification.
CLI Commands	Console commands for listing, purging, and exporting logs.
Integrations	EasyAdmin support.
Serialization	Cross-platform JSON format.
Benchmarks	Performance report.

---

Key Features

• High Performance: Non-blocking audits using a Split-Phase Architecture (capture in onFlush, dispatch in postFlush).
• Multiple Transports: Doctrine, HTTP (ELK/Splunk), Queue (RabbitMQ/Redis).
• Deep Collection Tracking: Tracks Many-to-Many and One-to-Many changes with precision.
• Sensitive Data Masking: Native support for #[SensitiveParameter] and custom #[Sensitive] attributes.
• Safe Revert Support: Easily roll back entities to any point in history.
• Conditional Auditing: Skip logs based on runtime conditions.
• Access Auditing: Track entity read operations (GET requests) with high-performance caching and configurable cooldowns.
• Rich Context: Tracks IP, User Agent, Impersonation, and custom metadata.

Quick Start

1. Installation

composer require rcsofttech/audit-trail-bundle

2. Database Setup (Doctrine Transport)

If you are using the Doctrine Transport (default), update your database schema:

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

3. Basic Usage

Add the #[Auditable] attribute to any Doctrine entity you want to track.

use Rcsofttech\AuditTrailBundle\Attribute\Auditable;

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

    #[ORM\Column]
    private string $name;
}

4. Access Auditing (Read Tracking)

To track when an entity is accessed (read), use the #[AuditAccess] attribute. This feature is strictly optimized for GET requests to minimize overhead.

use Rcsofttech\AuditTrailBundle\Attribute\AuditAccess;

#[ORM\Entity]
#[AuditAccess(cooldown: 3600, level: 'info', message: 'User accessed sensitive record')]
class SensitiveDocument
{
    // ...
}

Parameters

Parameter	Type	Default	Description
cooldown	int	0	Prevent duplicate logs for the same user/entity within X seconds (requires PSR-6 cache).
level	string	'info'	The log level for the access audit.
message	string?	null	A custom message to include in the audit log.

Note

#[AuditAccess] does not require #[Auditable] — they are independent attributes. However, if #[AuditCondition] is present on the same entity, it is respected for access logs. The expression receives action = "access" for fine-grained control.

Cache Configuration

To use the cooldown feature, you must specify a PSR-6 cache pool in your configuration:

# config/packages/audit_trail.yaml
audit_trail:
    cache_pool: 'cache.app' # Use any available PSR-6 cache pool

---

Requirements

• PHP 8.4+
• Symfony 7.4+
• Doctrine ORM 3.0+

License

MIT License.