repository·master·Indexed 19 days ago
https://github.com/damienharper/auditor-bundleA Symfony bundle that automates the creation of audit logs for Doctrine ORM database changes. It tracks modifications to audited entities and supports configuration via YAML or PHP 8 attributes (#[Auditable], #[Ignore], #[Security], and #[DiffLabel]). The bundle supports single or multi-database storage setups, custom audit table naming, and an optional audit viewer UI.
auditor-bundle (formerly DoctrineAuditBundle) integrates the auditor library into Symfony applications to create audit logs for all Doctrine ORM database-related changes. Once installed and configured, any database change affecting audited entities is automatically logged. Additionally, running schema updates will automatically set up audit logs for every new auditable entity.auditor-bundle is a Symfony integration for the auditor library. It automates the process of creating audit logs for Doctrine ORM database changes within a Symfony application.
/audit route.dh_auditor.yaml.The auditor-bundle allows you to customize three core providers to control how audit entries are enriched and how access to them is managed. By default, the bundle uses the following services:
| Provider | Purpose | Default Service |
|---|---|---|
| User Provider | Returns current user information | dh_auditor.user_provider |
| Security Provider | Returns IP address and firewall name | dh_auditor.security_provider |
| Role Checker | Checks if user can view entity audits | dh_auditor.role_checker |
These providers interact with the audit lifecycle: the User Provider and Security Provider contribute data to the Audit Entry, while the Role Checker determines access for the Audit Viewer.
The bundle includes default implementations for its providers:
TokenStorage.getId() method (if available).getUserIdentifier().Request.FirewallMap.AuthorizationChecker.When using multiple storage services, you must implement a StorageMapper to route audits to the correct database. A StorageMapper is a callable that receives the audited entity's FQCN and an array of available StorageServiceInterface instances, returning the appropriate service.
In this example, specific high-security entities are routed to a secure_entity_manager, while all others go to the default_entity_manager.
<?php
namespace App\Audit;
use App\Entity\HighSecurityEntity;
use App\Entity\SensitiveData;
use DH\Auditor\Provider\Service\StorageServiceInterface;
class StorageMapper
{
private const SECURE_ENTITIES = [
HighSecurityEntity::class,
SensitiveData::class,
];
public function __invoke(string $entity, array $storageServices): StorageServiceInterface
{
if (in_array($entity, self::SECURE_ENTITIES, true)) {
return $storageServices['dh_auditor.provider.doctrine.storage_services.doctrine.orm.secure_entity_manager'];
}
return $storageServices['dh_auditor.provider.doctrine.storage_services.doctrine.orm.default_entity_manager'];
}
}Register your mapper class in config/packages/dh_auditor.yaml under the storage_mapper key:
dh_auditor:
providers:
doctrine:
storage_services:
- '@doctrine.orm.default_entity_manager'
- '@doctrine.orm.secure_entity_manager'
storage_mapper: 'App\Audit\StorageMapper'When running commands via the CLI, the bundle automatically switches to the ConsoleUserProvider via the ConsoleEventSubscriber. This requires no manual configuration.
In this mode, the audit entry is populated with:
app:import-users).This behavior allows you to filter audit entries by specific CLI commands within the audit viewer.
The bundle acts as a bridge between your Symfony application and the core auditor library. It provides several integration layers:
TokenStorage (via UserProvider), RequestStack and FirewallMap (via SecurityProvider), and the AuthorizationChecker (via RoleChecker).ViewerController that provides a web interface for browsing logs.ConsoleEventSubscriber that ensures changes made via CLI commands are tracked.| Component | Service ID | Description |
|---|---|---|
| UserProvider | dh_auditor.user_provider | Gets the current user from TokenStorage |
| SecurityProvider | dh_auditor.security_provider | Gets the IP address and firewall from the Request |
| RoleChecker | dh_auditor.role_checker | Checks access via the Symfony Security component |
| ConsoleUserProvider | (internal) | Tracks console commands as the user |
| ViewerController | (internal) | Web UI for audit logs |
| RoutingLoader | (internal) | Loads viewer routes |
Labels are resolved during the post-commit callback of the DBAL middleware. This occurs after the Doctrine transaction commits but before the audit rows are written to the database.
Data Flow:
flush() is called.#[DiffLabel] attribute on the property.{"old": {"value": x, "label": "y"}, "new": {"value": a, "label": "b"}}.Note on Data Access: The raw value is always preserved. When accessing $entry->getDiffs(), the field will return an array containing both value and label instead of a scalar.
In version 7.0, CLI commands now use the command name as the user identifier.
blame_id was set to "command".blame_id is set to the command name (e.g., "app:import-users").Note: Existing audit entries with blame_id = "command" will not be automatically migrated.
The extra_data feature allows you to attach arbitrary supplementary JSON data to audit entries. This is useful for capturing context that isn't part of the entity itself, such as route names, request IDs, or business-specific roles.
There are two ways to populate this data:
extra_data_provider (Global Scope): Best for request-level context (e.g., current route, tenant ID) that applies to all audit entries. It runs first.LifecycleEvent Listener (Per-entity Scope): Best for fine-grained, entity-specific data (e.g., a user's department). It runs after the provider and can enrich or override the existing data.Both can be used together. The provider returns a plain array, while the listener must provide a JSON-encoded string.
// The provider returns a plain array
public function __invoke(): ?array {
return ['route' => 'app_home'];
}
// The listener must return a JSON-encoded string
public function __invoke(LifecycleEvent $event): void {
$payload = $event->getPayload();
$payload['extra_data'] = json_encode(['dept' => 'IT'], JSON_THROW_ON_ERROR);
$event->setPayload($payload);
}A User Provider is an abstraction used to identify the current user in audit entries. It is responsible for returning information about who performed a database change.
To implement a provider, you must satisfy the UserProviderInterface, which requires an __invoke method. This method must return an object implementing UserInterface (containing a unique identifier and a username) or null if no user is identified.
namespace DH👤👤♂👤👤;
interface UserProviderInterface
{
public function __invoke(): ?UserInterface;
}
interface UserInterface
{
public function getIdentifier(): ?string;
public function getUsername(): ?string;
}