README

A Symfony bundle that captures security events (login, logout, failed-login, impersonation) and Doctrine writes (insert/update/delete) into pluggable storage — Elasticsearch primary with Doctrine fallback, or Doctrine-only. Supports optional pre-image snapshots per entity so versioning / time-travel can be built on top.

Built for when "who changed what, when" is a compliance question.

What it does

Captures LoginSuccessEvent, LoginFailureEvent, LogoutEvent, SwitchUserEvent (enter + exit).
Captures Doctrine writes on entities marked #[Auditable]. onFlush collects, postFlush writes — so audit failures never roll back host data.
Snapshot modes per-entity: none (diff-only record), changed_fields (old+new values on changed fields), full (pre-image + post-image + diff, for versioning).
Storage: Elasticsearch primary + Doctrine fallback (or Doctrine-only). ChainedAuditWriter auto-falls-back on primary exception; audit:drain-fallback replays pending rows.
Non-blocking: exceptions during capture or flush are swallowed and written to error_log. Audit never poisons the request path.
Session-id workflow correlation: every event carries a SHA-256 hash of the session id — never the raw value — so sessions are correlatable for workflow visualization without creating a hijack vector.
Legacy migration for apps with a hand-rolled audit table: audit:migrate-legacy with a pluggable row mapper.

Requirements

PHP 8.2+
Symfony 7.0+ (tested on 7.3)
Doctrine ORM 3 / DBAL 3
symfony/security-http

Optional:

elastic/elasticsearch: ^8.0 — required when using Elasticsearch storage
symfony/messenger — enables async flush instead of kernel.terminate

Install

1. Require the package

composer require hexis/audit-bundle

In a monorepo with a path repository:

"repositories": [
  { "type": "path", "url": "packages/audit-bundle" }
],
"require": {
  "hexis/audit-bundle": "@dev"
}

2. Register the bundle

// config/bundles.php
return [
    // ...
    Hexis\AuditBundle\AuditBundle::class => ['all' => true],
];

3. Configure the bundle

# config/packages/audit.yaml
audit:
    enabled: true
    environments: [prod, dev]

    security:
        enabled: true
        events: [login, login_failure, logout, switch_user]
        firewalls: ~                       # null or empty = all firewalls

    doctrine:
        enabled: true
        entity_managers: [default]         # EMs whose UoW we hook

    storage:
        primary: doctrine                  # doctrine | elasticsearch
        fallback: ~                        # ~ | doctrine
        elasticsearch:
            client: ~                      # service id of your configured ES Client adapter
            index: 'audit-%Y.%m'           # strftime tokens %Y/%m/%d/%H supported
            index_template_name: audit
            refresh: false
        doctrine:
            connection: default
            entity_manager: ~              # ~ = default EM
            table_prefix: hexis_audit_   # derives hexis_audit_log
            table: ~                     # set to a full name to override (e.g. 'my_app_audit')
            retention_days: 365

    snapshots:
        default_mode: none                 # none | changed_fields | full
        serializer_group: audit:snapshot

    context:
        capture_ip: true
        capture_user_agent: true
        capture_request_path: true
        capture_session_id: true           # stores SHA-256 hash, never raw session id

4. Run migrations

bin/console doctrine:migrations:migrate

One table is created: hexis_audit_log (vendor-namespaced to avoid collisions with host-owned audit_log). Name is configurable via audit.storage.doctrine.table (full override) or audit.storage.doctrine.table_prefix. Indexes cover (occurred_at), (actor_id, occurred_at), (target_class, target_id, occurred_at), (event_type, occurred_at), (session_id_hash, occurred_at), and (source_of_truth, pending_replay_at).

Usage

Capture a custom event from app code

use Hexis\AuditBundle\Storage\AuditWriter;
use Hexis\AuditBundle\Domain\AuditEvent;
use Hexis\AuditBundle\Domain\EventType;
use Hexis\AuditBundle\Domain\Actor;
use Hexis\AuditBundle\Domain\Target;
use Hexis\AuditBundle\Domain\Snapshot;
use Hexis\AuditBundle\Domain\ContextCollector;

final readonly class PayrollService
{
    public function __construct(
        private AuditWriter $audit,
        private ContextCollector $context,
    ) {}

    public function approve(Payroll $payroll): void
    {
        // ... business logic ...

        $this->audit->write(new AuditEvent(
            type: EventType::CUSTOM,
            actor: $this->context->collectActor(),
            target: Target::entity(Payroll::class, $payroll->getId()),
            snapshot: Snapshot::none(),
            context: $this->context->collectContext(),
            action: 'payroll.approve',
        ));
    }
}

Opt an entity into automatic capture

use Hexis\AuditBundle\Attribute\Auditable;

#[ORM\Entity]
#[Auditable(mode: 'changed_fields', ignoreFields: ['updatedAt'])]
class Employee
{
    // ...
}

Modes:

Mode	Written	Use case
`none`	Only the fact an entity was mutated + its class/id	Low-cost activity log
`changed_fields`	`{field: {old, new}}` diff over the changed columns	Change-tracking UI
`full`	pre_image + post_image + diff via Serializer group `audit:snapshot`	Versioning / time-travel

ignoreFields excludes named fields from both diff and snapshot — good for updatedAt columns that would otherwise show up in every row.

For vendor entities you can't annotate, configure via YAML:

audit:
    doctrine:
        classes:
            Some\Vendor\Entity\Foo:
                mode: changed_fields
                ignore_fields: [updated_at]

Elasticsearch storage

The bundle never hard-codes a specific ES client. You provide an adapter service implementing Hexis\AuditBundle\Storage\Elasticsearch\ElasticsearchClient with three methods: index(), bulk(), putIndexTemplate(). The host chooses how to wire it — typically a thin adapter over elastic/elasticsearch:^8.0.

use Elastic\Elasticsearch\ClientBuilder;
use Hexis\AuditBundle\Storage\Elasticsearch\ElasticsearchClient;

final readonly class ElasticClientAdapter implements ElasticsearchClient
{
    public function __construct(private \Elastic\Elasticsearch\Client $client) {}

    public function index(string $index, string $id, array $document, bool $refresh = false): void
    {
        $this->client->index([
            'index' => $index,
            'id' => $id,
            'body' => $document,
            'refresh' => $refresh ? 'true' : 'false',
        ]);
    }

    public function bulk(iterable $operations, bool $refresh = false): void
    {
        $body = [];
        foreach ($operations as [$idx, $id, $doc]) {
            $body[] = ['index' => ['_index' => $idx, '_id' => $id]];
            $body[] = $doc;
        }
        $this->client->bulk(['body' => $body, 'refresh' => $refresh ? 'true' : 'false']);
    }

    public function putIndexTemplate(string $name, array $template): void
    {
        $this->client->indices()->putIndexTemplate(['name' => $name, 'body' => $template]);
    }
}

Configure it:

audit:
    storage:
        primary: elasticsearch
        fallback: doctrine            # optional — pending rows drain to ES later
        elasticsearch:
            client: App\Audit\ElasticClientAdapter
            index: 'audit-%Y.%m'

Then install the index template once (safe to re-run):

bin/console audit:install-elasticsearch-template

The shipped template maps actor, target, request, session_id_hash, occurred_at, etc. with appropriate types; snapshot.pre_image / snapshot.post_image / context are object fields with enabled: false so arbitrary entity shapes don't explode ES's field count.

Fallback & drain

When fallback: doctrine is set, a primary write exception falls through to the Doctrine writer with source_of_truth = 'fallback' and pending_replay_at = occurred_at. Run periodically:

bin/console audit:drain-fallback --limit=1000

Replayed rows are marked source_of_truth = 'replayed' and pending_replay_at = NULL. Idempotent: the event_id (ULID) is the document id in ES, so replays upsert rather than duplicate.

Commands

Command	Purpose
`audit:install-elasticsearch-template`	Install/update the shipped ES index template. Only registered when ES is configured.
`audit:drain-fallback [--limit=N] [--dry-run]`	Replay rows from the Doctrine fallback into the primary writer.
`audit:migrate-legacy [--source-table=…] [--source-connection=…] [--batch=N] [--limit=N] [--restart] [--dry-run]`	Copy rows from a host-owned legacy audit table into the bundle's storage. Resumable via a progress file.
`audit:prune [--older-than-days=N] [--dry-run]`	Delete Doctrine rows older than the retention window. Does not touch Elasticsearch — use ILM there.

Multi-EM / cross-tenant setups

If the host's default connection is tenant-scoped but audit data should be cross-tenant, point the bundle at a global connection + EM:

audit:
    storage:
        doctrine:
            connection: superadmin
            entity_manager: superadmin

Run the bundle's migration on that EM:

bin/console doctrine:migrations:migrate --em=superadmin

The Doctrine listener attaches per-EM via doctrine.event_listener tags. If you want only specific EMs audited, split the listener wiring via a compiler pass.

Safety properties

No audit recursion. The bundle's AuditLog entity is hard-coded in AuditableRegistry::BUNDLE_CLASSES as never-audited, and DoctrineAuditWriter uses direct DBAL (not ORM) so audit writes never re-enter the UoW the listener is attached to.
No host transaction coupling. Capture happens in onFlush, actual writes happen in postFlush after the host transaction has committed. An audit write failure cannot roll back host data.
No credential leakage on failed login. SecurityAuditSubscriber never reads the passport or raw token; it records only the attempted identifier (username/email) and the exception class. The password is never touched.
No lazy-load cascade during capture. AuditSnapshotNormalizer stops at relations and emits {@ref, id} tuples instead of dereferencing, so full-mode snapshots don't trigger N+1 queries.
Session id is hashed. Raw session id never leaves ContextCollector; only the SHA-256 hash is stored, preserving correlation without the hijack vector if the audit store is compromised.

Known limitations (v0.1)

Soft-delete detection is out of scope. Gedmo-style soft-deletes look like UPDATEs to the listener and will be tagged ENTITY_UPDATE, not ENTITY_DELETE.
No built-in UI. Query the hexis_audit_log table directly or via your ES tooling of choice. A search/read UI is on the follow-up roadmap.
No ILM. Elasticsearch retention must be handled on the cluster side.

Development

cd packages/audit-bundle
../../vendor/bin/phpunit

Tests cover the writers (Doctrine + ES mock), the BufferedAuditWriter, ChainedAuditWriter, SecurityAuditSubscriber (each event type + credential-leak assertion), DoctrineAuditListener (insert/update/delete + full-mode pre/post images + recursion guard + ignore_fields), AuditSnapshotNormalizer (cycle-safe, relation caps), DefaultLegacyRowMapper, and DrainFallbackCommand.

License

MIT.

hexis / audit-bundle

Maintainers

Package info

Statistics

Security