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.

---

Why AuditTrailBundle?

Most audit bundles capture changes synchronously, which can significantly slow down your application's write performance. AuditTrailBundle solves this by separating the Capture and Persistence phases.

Split-Phase Architecture

  Application       Doctrine ORM       AuditTrailBundle       Queue / Storage
       |                  |                    |                     |
       | flush()          |                    |                     |
       |----------------->|                    |                     |
       |                  | onFlush (Capture)  |                     |
       |                  |------------------->|                     |
       |                  |                    | Compute Diffs       |
       |                  |                    | Cache Payload       |
       |                  |<-------------------|                     |
       |                  |                    |                     |
       |                  | Execute SQL        |                     |
       |                  | (Transaction)      |                     |
       |                  |                    |                     |
       |                  | postFlush          |                     |
       |                  |------------------->|                     |
       |                  |                    | Dispatch Audit      |
       |                  |                    |-------------------->|
       | flush() returns  |                    |                     |
       |<-----------------|                    |                     |
                                                                     | Async Save

• Non-blocking: Audit capture happens during the flush, but storage is offloaded to a background process.
• Data Integrity: Cryptographic signing ensures logs cannot be tampered with.
• Developer First: Simple PHP 8 attributes, zero boilerplate.

Key Features

• High Performance: Non-blocking audits using a Split-Phase Architecture (capture in onFlush, dispatch in postFlush).
• Multiple Transports: Doctrine (Database), HTTP (ELK/Splunk), and Queue (RabbitMQ/Redis/Messenger).
• 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.
• Access Auditing: Track sensitive entity read operations (GET requests) with configurable cooldowns.
• Conditional Auditing: Skip logs based on runtime conditions or Expressions.
• Rich Context: Automatically tracks IP, User Agent, Impersonation, and custom metadata.

---

Enterprise-Ready UI

Native integration with EasyAdmin provides a professional dashboard for your audit logs out of the box.

---

Security & Compliance

Track not just what changed, but who did it and where they were.

• Sensitive Data Masking: Native support for #[SensitiveParameter] and custom #[Sensitive] attributes.
• HMAC Signatures: Every audit log is signed to prevent database tampering.
• Integrity Verification: Command-line tools to audit your audit logs.

---

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.

---

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.

<?php

use Rcsofttech\AuditTrailBundle\Attribute\Auditable;

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

    #[ORM\Column]
    public private(set) string $name;
}

4. Requirements

• PHP: 8.4+
• Symfony: 7.4+ or 8.0+
• Doctrine ORM: 3.0+

---

Community & Support

• Bugs & Features: Please use the GitHub Issue Tracker.
• Contributing: Check out our Contributing Guide.

License

MIT License.