Quick Start Guide

Set up the auditor core and connect a provider

auditor is a framework-agnostic audit library. It handles orchestration — event dispatching, user attribution, security — while providers handle storage and querying.

flowchart LR
    A["1️⃣ Configure<br/>Auditor"] --> B["2️⃣ Register<br/>a Provider"]
    B --> C["3️⃣ Mark entities<br/>as Auditable"]
    C --> D["🎉 Done!"]

1️⃣ Configure the Auditor

The Auditor class is the central registry. Configure it once at bootstrap time.

<?php

use DH\Auditor\Auditor;
use DH\Auditor\Configuration;
use DH\Auditor\User\User;
use Symfony\Component\EventDispatcher\EventDispatcher;

$configuration = new Configuration([
    'enabled'  => true,
    'timezone' => 'UTC',
]);

// Optional: tell auditor who is making changes
$configuration->setUserProvider(function (): ?User {
    return new User((string) $currentUser->getId(), $currentUser->getUsername());
});

// Optional: provide IP + firewall context
$configuration->setSecurityProvider(function (): array {
    return [$request->getClientIp(), 'main'];
});

$auditor = new Auditor($configuration, new EventDispatcher());

2️⃣ Register a Provider

A provider connects auditor to a specific storage technology. Each provider has its own setup (services, schema, etc.) — refer to your provider's documentation.

$auditor->registerProvider($provider);

3️⃣ Mark Entities as Auditable

Use the #[Auditable] attribute on any class you want tracked. #[Ignore] excludes individual fields; #[Security] restricts who can view the audit entries; #[DiffLabel] attaches a human-readable label to a property's raw value in the diff.

<?php

namespace App\Entity;

use DH\Auditor\Attribute\Auditable;
use DH\Auditor\Attribute\DiffLabel;
use DH\Auditor\Attribute\Ignore;
use DH\Auditor\Attribute\Security;

#[Auditable]
#[Security(view: ['ROLE_ADMIN'])]
class User
{
    private string $email;

    #[Ignore]
    private string $password;  // this field will never appear in audit diffs

    #[DiffLabel(resolver: StatusLabelResolver::class)]
    private int $status;      // raw value stored alongside a human-readable label
}

The attributes are part of auditor core (DH\Auditor\Attribute\) and work with any provider. How a provider discovers and registers auditable entities is provider-specific — see your provider's documentation for details.

🎉 Done!

From this point, every flush that touches an auditable entity will produce an audit entry. Refer to your provider's quick start for schema setup and reading audit entries back:

→ DoctrineProvider Quick Start

What's Next?

• ⚙️ Configuration Reference — Global options (user provider, security, role checker)
• 🏷️ Attributes Reference — #[Auditable], #[Ignore], #[Security], #[DiffLabel]
• 🔌 Providers — Available providers
• 🔍 Querying Audits — Reading audit entries