id: index title: Introduction slug: /

auditor

The missing audit log library for PHP

What is auditor?

auditor is a PHP library that provides an easy and standardized way to collect audit logs. It is designed to track changes made to your entities and persist them as audit trails.

Key Features

• 📝 Automatic change tracking — Captures inserts, updates, and deletes automatically
• 👤 User attribution — Records who made the changes and their IP address
• 🎯 Flexible configuration — Choose which entities and fields to audit
• 🔐 Security controls — Define who can view audit logs
• 🔌 Provider-based architecture — Storage and query layer are fully delegated to providers

Architecture Overview

The library is architected around two core concepts:

1. Auditing Services — Responsible for collecting audit events when changes occur
2. Storage Services — Responsible for persisting audit traces to the database

These services are implemented by Providers. Each provider handles a specific storage technology (Doctrine ORM, Eloquent, etc.).

flowchart TD
    APP["Your Application"] --> AUDITOR

    subgraph AUDITOR["AUDITOR"]
        direction TB

        subgraph CONFIG["Configuration"]
            direction LR
            enabled
            timezone
            userProvider
            securityProvider
            roleChecker
        end

        subgraph PROVIDER["Provider (e.g. DoctrineProvider)"]
            direction TB

            subgraph AUDITING["AuditingService(s)"]
                EMA["EntityManager A
                (source data)"]
            end

            subgraph STORAGE["StorageService(s)"]
                EMX["EntityManager X
                (audit storage)"]
            end

            AUDITING --> TP
            STORAGE --> TP

            TP["TransactionProcessor
            Track inserts, updates, deletes, relations
            Build payload (diffs, blame, extra_data = null)"]
        end

        subgraph EVENTS["EventDispatcher"]
            direction TB
            TP --> LE

            LE["LifecycleEvent
            payload (diffs, blame, extra_data)
            entity (the audited object)"]

            LE --> LISTENER

            LISTENER["Your Listener(s) — optional
            Enrich extra_data from entity state"]:::optional
        end
    end

    LISTENER --> DB

    DB[("Audit Tables
    users_audit, posts_audit, ...
    Columns: type, diffs, extra_data, blame, ...")]

    classDef optional stroke-dasharray: 5 5

Data Flow

1. Entity Change → Your application modifies data
2. Detection → The provider's AuditingService detects the change
3. Processing → TransactionProcessor computes diffs and prepares audit data (with extra_data = null)
4. Event → A LifecycleEvent is dispatched with the audit payload and the entity object
5. Enrichment (optional) → Your listener(s) inspect the entity and populate extra_data in the payload
6. Persistence → The provider's StorageService persists the audit entry to the database

Available Providers

Need a different backend? See Building a Custom Provider.

Database Support

Database support depends on the provider used. Via DoctrineProvider:

[!NOTE] DoctrineProvider should work with any database supported by Doctrine DBAL, though only the above are actively tested.

Version Compatibility

Quick Links

• Installation Guide
• Quick Start
• Configuration Reference
• DoctrineProvider
• Building a Custom Provider
• Querying Audits
• Extra Data
• API Reference

Related Projects

• auditor-bundle - Symfony bundle for seamless integration

License

This library is released under the MIT License.