Auditor Bundle

https://github.com/damienharper/auditor-bundle
Admin
Auditor Bundle is a Symfony bundle that integrates audit logging functionality to automatically...
Tokens:40,894
Snippets:408
Trust Score:8.4
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### Install assets for the audit viewer

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/getting-started/installation.md

Run this command to install the bundle's assets.

```bash
bin/console assets:install
```

--------------------------------

### Install auditor-bundle via Composer

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/getting-started/installation.md

Run this command to install the bundle and the auditor library.

```bash
composer require damienharper/auditor-bundle
```

--------------------------------

### Install dependencies for asset building

Source: https://github.com/damienharper/auditor-bundle/blob/master/CONTRIBUTING.md

Install dependencies including dev dependencies before building assets.

```bash
composer install
```

--------------------------------

### URL format example

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/viewer/index.md

Shows the URL format for entity namespaces, using dashes instead of backslashes.

```text
App\Entity\User → App-Entity-User
```

--------------------------------

### Complete dh_auditor.yaml example

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/index.md

A full configuration example for the Auditor Bundle, including enabled, timezone, provider settings, ignored columns, entity-specific roles and ignored columns, and viewer options. The viewer is enabled with a page_size of 100.

```yaml
# config/packages/dh_auditor.yaml
dh_auditor:
    enabled: true
    timezone: 'Europe/Paris'
    
    providers:
        doctrine:
            table_suffix: '_audit'
            
            ignored_columns:
                - createdAt
                - updatedAt
            
            entities:
                App\Entity\User:
                    roles:
                        view: [ROLE_ADMIN]
                
                App\Entity\Post:
                    ignored_columns:
                        - viewCount
                
                App\Entity\Comment: ~
            
            viewer:
                enabled: true
                page_size: 100

```

--------------------------------

### Preview and apply audit schema changes

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/upgrade/index.md

For fresh installations or existing v2 tables, preview the SQL changes with --dump-sql, then apply them with --force.

```bash
# Preview changes
bin/console audit:schema:update --dump-sql

# Apply changes
bin/console audit:schema:update --force
```

--------------------------------

### Quick Start Test Commands

Source: https://github.com/damienharper/auditor-bundle/blob/master/tests/README.md

Run the test suite with local PHP. Use 'composer test' for standard tests, 'composer test:coverage' for coverage, and 'composer testdox' for testdox output.

```bash
# Run tests with your local PHP
composer test

# Run tests with coverage
composer test:coverage

# Run tests with testdox output
composer testdox
```

--------------------------------

### Update dependencies, clear cache, and run tests

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/upgrade/index.md

Run these commands after reading the upgrade guide for your target version. Update the auditor packages, clear the cache, and run the test suite.

```bash
# Update dependencies
composer update damienharper/auditor damienharper/auditor-bundle

# Clear cache
bin/console cache:clear

# Run tests
bin/phpunit
```

--------------------------------

### Custom SecurityProvider

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/security-provider.md

Example custom provider that returns the client IP and a fixed context name 'my-app'.

```php
<?php

namespace App\Audit;

use DH\Auditor\Security\SecurityProviderInterface;
use Symfony\Component\HttpFoundation\RequestStack;

class CustomSecurityProvider implements SecurityProviderInterface
{
    public function __construct(
        private readonly RequestStack $requestStack,
    ) {}

    public function __invoke(): array
    {
        $request = $this->requestStack->getCurrentRequest();

        if (null === $request) {
            return [null, null];
        }

        return [
            $request->getClientIp(),
            'my-app',
        ];
    }
}
```

--------------------------------

### Install auditor-doctrine-provider for direct usage

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/upgrade/v8.md

Use this command in non-bundle projects that use DoctrineProvider directly. It installs version ^2.0 of the standalone package.

```bash
composer require damienharper/auditor-doctrine-provider:^2.0
```

--------------------------------

### Example diff with resolved labels

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/diff-label-resolvers.md

Shows the diff format after applying #[DiffLabel] resolvers, where each value includes both the raw value and a human-readable label.

```json
{
  "categoryId": {
    "old": {"value": 1, "label": "Books"},
    "new": {"value": 2, "label": "Electronics"}
  }
}
```

--------------------------------

### PHP test example for ViewerControllerTest

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/contributing.md

Example test class for the viewer controller, verifying audit list accessibility and authentication requirements. Place tests in the tests/ directory mirroring src/ structure.

```php
namespace DH\AuditorBundle\Tests\Controller;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

final class ViewerControllerTest extends WebTestCase
{
    public function testAuditListIsAccessible(): void
    {
        $client = static::createClient();
        $client->request('GET', '/audit');

        $this->assertResponseIsSuccessful();
    }

    public function testAuditListRequiresAuthentication(): void
    {
        // ...
    }
}
```

--------------------------------

### Install symfony/cache for activity graph caching

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/viewer/index.md

Required to enable caching for the activity graph. If not installed, the graph still works but without caching.

```bash
composer require symfony/cache
```

--------------------------------

### Quick Reference Configuration

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/index.md

Complete example of the dh_auditor configuration with all global options and provider settings. Shows defaults for enabled, timezone, user_provider, security_provider, role_checker, and provider-specific options like table_prefix, table_suffix, ignored_columns, entities, storage_services, auditing_services, storage_mapper, utf8_convert, and viewer.

```yaml
dh_auditor:
    enabled: true                           # Enable/disable auditing globally
    timezone: 'UTC'                         # Timezone for audit timestamps
    user_provider: 'dh_auditor.user_provider'
    security_provider: 'dh_auditor.security_provider'
    role_checker: 'dh_auditor.role_checker'

    providers:
        doctrine:
            table_prefix: ''
            table_suffix: '_audit'
            ignored_columns: []
            entities: []
            storage_services: ['@doctrine.orm.default_entity_manager']
            auditing_services: ['@doctrine.orm.default_entity_manager']
            storage_mapper: ~
            utf8_convert: false             # Re-enable legacy UTF-8 conversion (opt-in)
            viewer: false
```

--------------------------------

### Configure entities to audit

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/index.md

Lists entities to audit with optional per-entity settings. The example shows a simple entity using all defaults and another with custom options like `enabled`, `ignored_columns`, and `roles.view`.

```yaml
dh_auditor:
    providers:
        doctrine:
            entities:
                # Simple: all defaults
                App\Entity\User: ~
                
                # With options
                App\Entity\Post:
                    enabled: true
                    ignored_columns:
                        - viewCount
                    roles:
                        view:
                            - ROLE_ADMIN
```

--------------------------------

### Testing Multiple PHP/Symfony Combinations

Source: https://github.com/damienharper/auditor-bundle/blob/master/tests/README.md

Run tests against multiple PHP and Symfony versions before submitting a PR. The example shows three combinations: PHP 8.4 with Symfony 7.3, PHP 8.4 with Symfony 8.0, and PHP 8.5 with Symfony 8.0.

```bash
make tests php=8.4 sf=7.3
make tests php=8.4 sf=8.0
make tests php=8.5 sf=8.0
```

--------------------------------

### JsonFilter operator examples

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/extra-data.md

Table of supported operators for JsonFilter with example usage for each: =, !=, LIKE, NOT LIKE, IN, NOT IN, IS NULL, IS NOT NULL.

```php
new JsonFilter('extra_data', 'dept', 'IT')
```

```php
new JsonFilter('extra_data', 'dept', 'IT', '!=')
```

```php
new JsonFilter('extra_data', 'dept', 'IT%', 'LIKE')
```

```php
new JsonFilter('extra_data', 'dept', '%temp%', 'NOT LIKE')
```

```php
new JsonFilter('extra_data', 'dept', ['IT', 'HR'], 'IN')
```

```php
new JsonFilter('extra_data', 'dept', ['IT'], 'NOT IN')
```

```php
new JsonFilter('extra_data', 'dept', null, 'IS NULL')
```

```php
new JsonFilter('extra_data', 'dept', null, 'IS NOT NULL')
```

--------------------------------

### Configure storage services for multi-database

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/storage.md

Configures storage_services to use the audit entity manager, auditing_services to use the default entity manager, and lists entities to audit. This is part of the multi-database setup.

```yaml
# config/packages/dh_auditor.yaml
dh_auditor:
    providers:
        doctrine:
            storage_services:
                - '@doctrine.orm.audit_entity_manager'
            
            auditing_services:
                - '@doctrine.orm.default_entity_manager'
            
            entities:
                App\Entity\User: ~
```

--------------------------------

### Configure auditing_services

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/index.md

Specifies the entity managers to monitor for changes. The example includes both the default and a secondary entity manager.

```yaml
dh_auditor:
    providers:
        doctrine:
            auditing_services:
                - '@doctrine.orm.default_entity_manager'
                - '@doctrine.orm.secondary_entity_manager'
```

--------------------------------

### Create a custom role checker

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/role-checker.md

Implement RoleCheckerInterface and define the __invoke method to control access. This example grants super admins full access, requires authentication, and checks for a specific role.

```php
<?php

namespace App\Audit;

use DH\Auditor\Security\RoleCheckerInterface;
use Symfony\Bundle\SecurityBundle\Security;

class CustomRoleChecker implements RoleCheckerInterface
{
    public function __construct(
        private readonly Security $security,
    ) {}

    public function __invoke(string $entity, string $scope): bool
    {
        // Super admins can view everything
        if ($this->security->isGranted('ROLE_SUPER_ADMIN')) {
            return true;
        }

        // Require authentication for all audits
        if (null === $this->security->getUser()) {
            return false;
        }

        return $this->security->isGranted('ROLE_AUDIT_VIEWER');
    }
}
```

--------------------------------

### Example diff with raw IDs

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/diff-label-resolvers.md

Shows the default audit diff format storing raw field values, e.g., an integer foreign key for categoryId.

```json
{"categoryId": {"old": 1, "new": 2}}
```

--------------------------------

### Complete example: resolver class, entity, and diff output

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/diff-label-resolvers.md

Shows a full resolver implementation, an entity using the DiffLabel attribute, and the resulting audit diff JSON. The resolver must implement DiffLabelResolverInterface and return a label or null. The entity uses the resolver class constant in the attribute. The diff output shows the label shape for both old and new values.

```php
<?php
// src/Audit/Resolver/ProductCategoryResolver.php

namespace App\Audit\Resolver;

use App\Repository\CategoryRepository;
use DH\Auditor\Contract\DiffLabelResolverInterface;

final class ProductCategoryResolver implements DiffLabelResolverInterface
{
    public function __construct(
        private readonly CategoryRepository $repository,
    ) {}

    public function __invoke(mixed $value): ?string
    {
        return $this->repository->find($value)?->getName();
    }
}
```

```php
<?php
// src/Entity/Product.php

namespace App\Entity;

use App\Audit\Resolver\ProductCategoryResolver;
use DH\Auditor\Attribute\Auditable;
use DH\Auditor\Attribute\DiffLabel;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[Auditable]
class Product
{
    #[ORM\Column(type: Types::INTEGER)]
    #[DiffLabel(resolver: ProductCategoryResolver::class)]
    private int $categoryId;

    #[ORM\Column(type: Types::INTEGER)]
    #[DiffLabel(resolver: SupplierResolver::class)]
    private int $supplierId;

    // ...
}
```

```json
{
  "categoryId": {
    "old": {"value": 1, "label": "Books"},
    "new": {"value": 3, "label": "Software"}
  },
  "supplierId": {
    "old": {"value": 42, "label": "Acme Corp"},
    "new": {"value": 67, "label": "Globex Inc"}
  }
}
```

--------------------------------

### Annotate the entity property (Product)

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/diff-label-resolvers.md

Step 2 of the quick start: apply the #[DiffLabel] attribute to the categoryId property, referencing the resolver class. The entity must be auditable via #[Auditable].

```php
<?php

namespace App\Entity;

use App\Audit\Resolver\CategoryResolver;
use DH\Auditor\Attribute\Auditable;
use DH\Auditor\Attribute\DiffLabel;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[Auditable]
class Product
{
    #[ORM\Column(type: Types::INTEGER)]
    #[DiffLabel(resolver: CategoryResolver::class)]
    private int $categoryId;

    // ...
}
```

--------------------------------

### Configure storage_services

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/index.md

Defines the entity managers used for storing audit data. The example lists two entity managers, including a custom `audit_entity_manager`.

```yaml
dh_auditor:
    providers:
        doctrine:
            storage_services:
                - '@doctrine.orm.default_entity_manager'
                - '@doctrine.orm.audit_entity_manager'
```

--------------------------------

### URL parameters for entity stream filters

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/viewer/index.md

Example URLs for filtering the entity stream by action type and user. The entity class is URL-encoded (App-Entity-User).

```text
/audit/App-Entity-User?type=update&user=42
/audit/App-Entity-User?type=insert&user=__anonymous__
```

--------------------------------

### Providing a bundle: PHP extension registering ElasticsearchProvider

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/custom-provider.md

Wire the 'dh_auditor.provider' tag automatically in a Symfony extension for a distributable bundle. Users only need to install and enable the bundle; no service configuration is required.

```php
namespace Acme\AuditElasticBundle\DependencyInjection;

use Acme\AuditElasticBundle\Provider\ElasticsearchProvider;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Extension\Extension;
use Symfony\Component\DependencyInjection\Reference;

final class AcmeAuditElasticExtension extends Extension
{
    public function load(array $configs, ContainerBuilder $container): void
    {
        $container
            ->register(ElasticsearchProvider::class)
            ->addArgument(new Reference('elastic_client'))
            ->addTag('dh_auditor.provider')
        ;
    }
}
```

--------------------------------

### CategoryResolver using raw DBAL connection

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/diff-label-resolvers.md

Safe implementation of DiffLabelResolverInterface that uses a read-only DBAL connection to fetch a label. Avoids flushing or starting transactions on the same EntityManager.

```php
final class CategoryResolver implements DiffLabelResolverInterface
{
    public function __construct(
        private readonly Connection $connection,  // raw DBAL connection
    ) {}

    public function __invoke(mixed $value): ?string
    {
        $name = $this->connection->fetchOne(
            'SELECT name FROM category WHERE id = ?',
            [$value],
        );

        return $name !== false ? $name : null;
    }
}
```

--------------------------------

### External OAuth/SSO User Provider

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/user-provider.md

Implements UserProviderInterface for external OAuth/SSO. Uses RequestStack to get the current request and extracts user info from headers.

```php
<?php

namespace App\Audit;

use DH\Auditor\User\User;
use DH\Auditor\User\UserInterface;
use DH\Auditor\User\UserProviderInterface;
use Symfony\Component\HttpFoundation\RequestStack;

class OAuthUserProvider implements UserProviderInterface
{
    public function __construct(
        private readonly RequestStack $requestStack,
    ) {}

    public function __invoke(): ?UserInterface
    {
        $request = $this->requestStack->getCurrentRequest();

        if (null === $request) {
            return null;
        }

        // User info from OAuth headers
        $userId = $request->headers->get('X-User-Id');
        $userName = $request->headers->get('X-User-Email');

        if (null === $userId) {
            return null;
        }

        return new User($userId, $userName ?? 'unknown');
    }
}
```

--------------------------------

### Implement a resolver (CategoryResolver)

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/diff-label-resolvers.md

Step 1 of the quick start: implement DiffLabelResolverInterface to resolve a category ID to its name. Symfony autoconfiguration auto-tags the class with dh_auditor.diff_label_resolver, so no services.yaml entry is needed beyond standard autowiring.

```php
<?php

namespace App\Audit\Resolver;

use DH\Auditor\Contract\DiffLabelResolverInterface;

final class CategoryResolver implements DiffLabelResolverInterface
{
    public function __construct(
        private readonly CategoryRepository $repository,
    ) {}

    public function __invoke(mixed $value): ?string
    {
        $category = $this->repository->find($value);

        return $category?->getName();
    }
}
```

--------------------------------

### API Token Authentication User Provider

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/user-provider.md

Implements UserProviderInterface for API token authentication. Uses ApiTokenManager to get the current token and returns a User with client ID and name.

```php
<?php

namespace App\Audit;

use App\Security\ApiTokenManager;
use DH\Auditor\User\User;
use DH\Auditor\User\UserInterface;
use DH\Auditor\User\UserProviderInterface;

class ApiUserProvider implements UserProviderInterface
{
    public function __construct(
        private readonly ApiTokenManager $tokenManager,
    ) {}

    public function __invoke(): ?UserInterface
    {
        $token = $this->tokenManager->getCurrentToken();

        if (null === $token) {
            return null;
        }

        return new User(
            $token->getClientId(),
            sprintf('API: %s', $token->getClientName())
        );
    }
}
```

--------------------------------

### Migrate audit tables (preview and full migration)

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/upgrade/v8.md

First preview the SQL with --dump-sql, then run the full migration with --force --convert-all. The individual flags --convert-transaction-hash and --convert-diffs are also available for phased migration.

```bash
# Preview the SQL
bin/console audit:schema:migrate --dump-sql

# Run the full migration in one pass (DDL + transaction hash conversion + diffs conversion)
bin/console audit:schema:migrate --force --convert-all
```

--------------------------------

### Build CSS for production

Source: https://github.com/damienharper/auditor-bundle/blob/master/CONTRIBUTING.md

Build the CSS for production (minified) using Make.

```bash
make build-assets
```

--------------------------------

### Quick Migration Commands

Source: https://github.com/damienharper/auditor-bundle/blob/master/UPGRADE-7.0.md

Run these commands to update dependencies, clear the cache, and check the schema after upgrading to v7.0.

```bash
# 1. Update dependencies
composer require php:^8.4 symfony/framework-bundle:^8.0 \
    doctrine/dbal:^4.0 doctrine/orm:^3.2 doctrine/doctrine-bundle:^3.0 \
    damienharper/auditor:^4.0 damienharper/auditor-bundle:^7.0

# 2. Clear cache
bin/console cache:clear

# 3. Check schema
bin/console audit:schema:update --dump-sql
```

--------------------------------

### Clone the repository

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/contributing.md

Clone your forked repository and navigate into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/auditor-bundle.git
cd auditor-bundle
```

--------------------------------

### Test multiple PHP versions with Make

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/contributing.md

Run the test suite against different PHP versions to ensure compatibility.

```bash
# Test different PHP versions
make tests php=8.4
make tests php=8.5
```

--------------------------------

### Run code quality tools with Composer

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/contributing.md

Run all QA tools or individual ones using Composer scripts.

```bash
# Run all QA tools
composer qa

# Individual tools:
composer cs-check    # Check code style
composer cs-fix      # Fix code style
composer phpstan     # Static analysis
composer rector      # Automated refactoring suggestions
```

--------------------------------

### Create audit tables using Schema Tool

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/getting-started/installation.md

Run this command to update the database schema directly.

```bash
bin/console doctrine:schema:update --force
```

--------------------------------

### Implement a custom provider (ElasticsearchProvider)

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/custom-provider.md

Extend AbstractProvider and implement the required methods: supportsStorage, supportsAuditing, and persist. The persist method indexes audit data into Elasticsearch. Implementing ResetInterface is recommended for long-running processes like Messenger workers.

```php
namespace App\Audit;

use DH\Auditor\Event\LifecycleEvent;
use DH\Auditor\Provider\AbstractProvider;
use Symfony\Contracts\Service\ResetInterface;

final class ElasticsearchProvider extends AbstractProvider implements ResetInterface
{
    public function __construct(private readonly ElasticClient $client)
    {
        $this->configuration = new ElasticsearchConfiguration($client);
        $this->registerStorageService(new ElasticsearchStorageService('default', $client));
    }

    public function supportsStorage(): bool
    {
        return true;
    }

    public function supportsAuditing(): bool
    {
        // This provider only writes audit entries; DoctrineProvider handles change detection.
        return false;
    }

    public function persist(LifecycleEvent $event): void
    {
        $payload = $event->getPayload();

        $this->client->index([
            'index' => 'audit',
            'body'  => [
                'type'       => $payload['type'],
                'entity'     => $payload['entity'],   // FQCN — always present when DoctrineProvider is the auditing source
                'object_id'  => $payload['object_id'],
                'diffs'      => json_decode($payload['diffs'], true),
                'blame_user' => $payload['blame']['username'] ?? null,
                'created_at' => $payload['created_at']->format(\DateTimeInterface::ATOM),
            ],
        ]);
    }

    public function reset(): void
    {
        // Clear any request-scoped state for long-running processes (Messenger workers, etc.)
        $this->client->reset();
    }
}
```

--------------------------------

### Create audit tables using Doctrine Migrations

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/getting-started/installation.md

Run these commands to generate and apply a migration for the audit tables.

```bash
bin/console doctrine:migrations:diff
```

```bash
bin/console doctrine:migrations:migrate
```

--------------------------------

### Run schema update to add extra_data column

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/extra-data.md

Use these commands to preview and apply the schema update that adds the extra_data column. The --dump-sql flag shows the SQL without executing it, while --force applies the changes.

```bash
# Preview the SQL that will be executed
php bin/console audit:schema:update --dump-sql

# Apply the change
php bin/console audit:schema:update --force
```

--------------------------------

### Make targets for testing and quality

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/contributing.md

Use the Makefile to run tests and code quality tools with configurable PHP and Symfony versions.

```bash
# Show all available commands and options
make help

# Run tests with defaults (PHP 8.5, Symfony 8.0)
make tests

# Run tests with specific PHP version
make tests php=8.4

# Run specific test class
make tests args='--filter=ViewerControllerTest'

# Run tests with coverage
make tests args='--coverage-html=coverage'
```

--------------------------------

### Run code quality tools with Make

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/contributing.md

Use Make targets to run PHP-CS-Fixer and PHPStan, optionally with specific PHP versions or arguments.

```bash
# Run PHP-CS-Fixer
make cs-fix

# Run PHPStan
make phpstan

# With specific PHP version
make phpstan php=8.4

# With custom arguments
make cs-fix args='fix --dry-run'
```

--------------------------------

### Environment-specific viewer configuration (dev and prod)

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/index.md

Shows separate configurations for dev and prod environments. The dev config enables the viewer with a simple true, while the prod config enables it with a page_size of 50.

```yaml
# config/packages/dev/dh_auditor.yaml
dh_auditor:
    providers:
        doctrine:
            viewer: true

# config/packages/prod/dh_auditor.yaml
dh_auditor:
    providers:
        doctrine:
            viewer:
                enabled: true
                page_size: 50

```

--------------------------------

### Create a feature branch

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/contributing.md

Create a new branch for your changes.

```bash
git checkout -b feature/my-new-feature
```

--------------------------------

### Configure activity graph in YAML

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/viewer/index.md

Enables the activity graph and sets display options. The 'days' option is capped at 30, and the layout can be 'bottom' (default) or 'inline'. Caching is enabled by default with a TTL of 300 seconds.

```yaml
dh_auditor:
    providers:
        doctrine:
            viewer:
                enabled: true
                activity_graph:
                    enabled: true       # Show/hide the graph (default: true)
                    days: 30            # Number of days to display (default: 30, max: 30)
                    layout: 'bottom'    # Graph layout: 'bottom' or 'inline' (default: 'bottom')
                    cache:
                        enabled: true   # Enable caching (default: true)
                        pool: 'cache.app'  # Cache pool service ID
                        ttl: 300        # Cache TTL in seconds (default: 300)
```

--------------------------------

### Run tests with Composer

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/contributing.md

Run the test suite locally using Composer scripts, including coverage and testdox options.

```bash
# Run all tests
composer test

# Run tests with coverage
composer test:coverage

# Run tests with testdox output
composer testdox
```

--------------------------------

### Basic configuration for dh_auditor.yaml

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/getting-started/installation.md

Create config/packages/dh_auditor.yaml with this minimal configuration to enable auditing for User and Post entities.

```yaml
dh_auditor:
    providers:
        doctrine:
            entities:
                App\Entity\User: ~
                App\Entity\Post: ~
```

--------------------------------

### Makefile Test Commands

Source: https://github.com/damienharper/auditor-bundle/blob/master/tests/README.md

Use the Makefile to run tests with Docker. Defaults to PHP 8.5 and Symfony 8.0. Override with 'php' and 'sf' variables. Use 'args' to pass arguments like '--filter=ViewerControllerTest'.

```bash
# Show help
make help

# Run tests (defaults: PHP 8.5, Symfony 8.0)
make tests

# Run tests with specific PHP version
make tests php=8.4

# Run tests with specific Symfony version
make tests sf=7.3

# Run tests with specific PHP and Symfony versions
make tests php=8.4 sf=7.3

# Run a specific test
make tests args='--filter=ViewerControllerTest'
```

--------------------------------

### Combining attributes with YAML configuration

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/attributes.md

Shows how attributes provide fine-grained control while YAML handles global settings. The entity uses #[Ignore] for password, while createdAt and updatedAt are ignored via YAML.

```php
// Entity uses attributes for fine-grained control
#[ORM\Entity]
#[Auditable]
#[Security(view: ['ROLE_ADMIN'])]
class User
{
    #[Ignore]
    private ?string $password = null;
    
    // createdAt and updatedAt are automatically ignored via YAML
}
```

--------------------------------

### Use UrlHelper to convert namespaces

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/viewer/index.md

PHP code demonstrating UrlHelper::namespaceToParam and paramToNamespace methods for converting between entity namespaces and URL parameters.

```php
use DH\AuditorBundle\Helper\UrlHelper;

// Namespace to URL parameter
$param = UrlHelper::namespaceToParam('App\Entity\User');
// Returns: 'App-Entity-User'

// URL parameter to namespace
$namespace = UrlHelper::paramToNamespace('App-Entity-User');
// Returns: 'App\Entity\User'
```

--------------------------------

### Verify schema with audit:schema:update --dump-sql

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/upgrade/v8.md

Use this command to preview the SQL that would be executed for schema updates. It helps verify the new schema before applying changes.

```bash
bin/console audit:schema:update --dump-sql
```

--------------------------------

### Watch for CSS changes during development

Source: https://github.com/damienharper/auditor-bundle/blob/master/CONTRIBUTING.md

Watch for changes during development using Make.

```bash
make watch-assets
```

--------------------------------

### Code Quality Tool Commands

Source: https://github.com/damienharper/auditor-bundle/blob/master/tests/README.md

Run code quality tools. Use 'make cs-fix' for PHP-CS-Fixer and 'make phpstan' for PHPStan.

```bash
# Run PHP-CS-Fixer
make cs-fix

# Run PHPStan
make phpstan
```

--------------------------------

### Single Database Schema Management with Doctrine

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/storage.md

Use standard Doctrine tools to manage schema for a single database. With migrations (recommended), run doctrine:migrations:diff and doctrine:migrations:migrate. Alternatively, use the schema tool with doctrine:schema:update --force.

```bash
# With migrations (recommended)
bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

# Or schema tool
bin/console doctrine:schema:update --force
```

--------------------------------

### Return array structure

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/security-provider.md

Shows the expected return array with two elements: client IP and firewall name.

```php
return [
    $clientIp,      // string|null - Client IP address
    $firewallName,  // string|null - Firewall or context name
];
```

--------------------------------

### Manual route configuration for dh_auditor.yaml

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/getting-started/installation.md

Create config/routes/dh_auditor.yaml with this content to manually configure routes.

```yaml
dh_auditor:
    resource: "@DHAuditorBundle/Controller/"
    type: auditor
```

--------------------------------

### Commands to run tests with filter and coverage

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/contributing.md

Commands to run only new tests using a filter and to run tests with coverage. Use 'make tests' with the 'args' parameter and 'composer test:coverage' for coverage.

```bash
# Run only your new tests
make tests args='--filter=ViewerControllerTest'

# Run with coverage to ensure good test coverage
composer test:coverage
```

--------------------------------

### Update auditor-bundle to ^8.0

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/upgrade/v8.md

Run this command to update auditor-bundle to version 8.0. It automatically pulls in auditor:^5.0 and auditor-doctrine-provider:^2.0.

```bash
composer require damienharper/auditor-bundle:^8.0
```

--------------------------------

### ConsoleUserProvider implementation

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/user-provider.md

Provider for CLI commands that uses the current command name as both ID and username. Returns null if no command is running.

```php
public function __invoke(): ?UserInterface
{
    if (null === $this->currentCommand) {
        return null;
    }

    // Command name is used as both ID and username
    return new User(
        $this->currentCommand,  // e.g., 'app:import-users'
        $this->currentCommand
    );
}
```

--------------------------------

### ConsoleAwareSecurityProvider - HTTP and Console Context

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/security-provider.md

Implements SecurityProviderInterface that detects whether the request is in an HTTP or console context. For HTTP, returns the client IP and 'http' context; for console, returns '127.0.0.1' and a configurable context (defaults to 'console'). Provides a setter for the console context.

```php
<?php

namespace App\Audit;

use DH\Auditor\Security\SecurityProviderInterface;
use Symfony\Component\HttpFoundation\RequestStack;

class ConsoleAwareSecurityProvider implements SecurityProviderInterface
{
    private ?string $consoleContext = null;

    public function __construct(
        private readonly RequestStack $requestStack,
    ) {}

    public function __invoke(): array
    {
        $request = $this->requestStack->getCurrentRequest();

        // HTTP context
        if (null !== $request) {
            return [$request->getClientIp(), 'http'];
        }

        // Console context
        return ['127.0.0.1', $this->consoleContext ?? 'console'];
    }

    public function setConsoleContext(?string $context): void
    {
        $this->consoleContext = $context;
    }
}
```

--------------------------------

### Imports for DoctrineProvider (works in 4.x and 5.x)

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/upgrade/v8.md

These imports work in both auditor 4.x (from core) and 5.x (from auditor-doctrine-provider). The namespace remains unchanged.

```php
// Works in both 4.x (from auditor core) and 5.x (from auditor-doctrine-provider)
use DH\Auditor\Provider\Doctrine\DoctrineProvider;
use DH\Auditor\Provider\Doctrine\Configuration;
use DH\Auditor\Provider\Doctrine\Persistence\Reader\Reader;
// ...
```

--------------------------------

### Enable viewer with custom page size

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/viewer/index.md

Configuration to enable the audit viewer with a custom page size of 50 entries per page.

```yaml
dh_auditor:
    providers:
        doctrine:
            viewer:
                enabled: true
                page_size: 50
```

--------------------------------

### Enable viewer with simple and option-based YAML

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/index.md

Shows two ways to enable the audit viewer in the dh_auditor configuration: a simple boolean true and an options array with enabled and page_size. The page_size default is 50.

```yaml
# Simple enable
dh_auditor:
    providers:
        doctrine:
            viewer: true

# With options
dh_auditor:
    providers:
        doctrine:
            viewer:
                enabled: true
                page_size: 50

```

--------------------------------

### Enable the viewer in configuration

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/getting-started/installation.md

Add the viewer: true option to your dh_auditor configuration to enable the audit viewer.

```yaml
dh_auditor:
    providers:
        doctrine:
            viewer: true
            entities:
                App\Entity\User: ~
```

--------------------------------

### SecurityProviderInterface

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/security-provider.md

Defines the contract for a security provider. It must implement __invoke() returning an array with client IP and firewall name.

```php
namespace DH\Auditor\Security;

interface SecurityProviderInterface
{
    public function __invoke(): array;
}
```

--------------------------------

### Run code quality checks with Composer

Source: https://github.com/damienharper/auditor-bundle/blob/master/CONTRIBUTING.md

Run these commands before submitting a pull request. `composer cs-fix` fixes code style, `composer phpstan` runs static analysis, and `composer qa` runs everything at once.

```bash
composer cs-fix      # fix code style (PHP CS Fixer)
composer phpstan     # static analysis
# or run everything at once:
composer qa
```

--------------------------------

### Disable auditing by default with #[Auditable(enabled: false)]

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/attributes.md

Creates an audit table but does not log until enabled at runtime. The 'enabled' parameter defaults to false, so auditing is off by default.

```php
#[ORM\Entity]
#[Auditable(enabled: false)]
class User
{
    // Auditing is OFF by default
    // Can be enabled at runtime
}
```

--------------------------------

### Basic Custom User Provider Implementation

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/user-provider.md

Implements UserProviderInterface with a constructor injecting MyAuthService. The __invoke method returns a User object from the authenticated user or null if no user is found.

```php
<?php

namespace App\Audit;

use DH\Auditor\User\User;
use DH\Auditor\User\UserInterface;
use DH\Auditor\User\UserProviderInterface;

class CustomUserProvider implements UserProviderInterface
{
    public function __construct(
        private readonly MyAuthService $authService,
    ) {}

    public function __invoke(): ?UserInterface
    {
        $user = $this->authService->getCurrentUser();

        if (null === $user) {
            return null;
        }

        return new User(
            (string) $user->getId(),
            $user->getEmail()
        );
    }
}
```

--------------------------------

### Built-in SecurityProvider

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/security-provider.md

The default provider retrieves the current request and returns the client IP and firewall config name, or nulls if no request.

```php
public function __invoke(): array
{
    $request = $this->requestStack->getCurrentRequest();

    if (!$request instanceof Request) {
        return [null, null];
    }

    $firewallConfig = $this->firewallMap->getFirewallConfig($request);

    return [
        $request->getClientIp(),
        $firewallConfig?->getName(),
    ];
}
```

--------------------------------

### Routing by entity - StorageMapper

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/storage.md

Routes audits to different storage services based on the entity. Entities in SECURE_ENTITIES use the secure entity manager, others use the default entity manager.

```php
<?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'];
    }
}
```

--------------------------------

### Enable viewer with default options

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/viewer/index.md

Configuration to enable the audit viewer for the doctrine provider. Place in config/packages/dh_auditor.yaml.

```yaml
# config/packages/dh_auditor.yaml
dh_auditor:
    providers:
        doctrine:
            viewer: true
```

--------------------------------

### Migrate legacy audit tables and apply schema changes

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/upgrade/index.md

When upgrading from auditor-bundle 7.x or earlier, run audit:schema:migrate first to preserve data, then apply remaining schema changes. audit:schema:update refuses to run if legacy v1 tables exist.

```bash
# Migrate legacy audit tables to v2 (preserves all data)
bin/console audit:schema:migrate --force --convert-all

# Then apply any remaining schema changes
bin/console audit:schema:update --force
```

--------------------------------

### AwsSecurityProvider - AWS ALB/API Gateway

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/security-provider.md

Implements SecurityProviderInterface for AWS ALB or API Gateway. Parses X-Forwarded-For header to extract the original client IP, uses the X-Amzn-Api-Gateway-Stage header as context (defaults to 'unknown'), and falls back to the direct IP if no header is present.

```php
<?php

namespace App\Audit;

use DH\Auditor\Security\SecurityProviderInterface;
use Symfony\Component\HttpFoundation\RequestStack;

class AwsSecurityProvider implements SecurityProviderInterface
{
    public function __construct(
        private readonly RequestStack $requestStack,
    ) {}

    public function __invoke(): array
    {
        $request = $this->requestStack->getCurrentRequest();

        if (null === $request) {
            return [null, null];
        }

        // AWS ALB/API Gateway headers
        $clientIp = $request->headers->get('X-Forwarded-For');
        if (null !== $clientIp && str_contains($clientIp, ',')) {
            // First IP is the original client
            $clientIp = trim(explode(',', $clientIp)[0]);
        }

        // Use API Gateway stage as context
        $context = $request->headers->get('X-Amzn-Api-Gateway-Stage', 'unknown');

        return [$clientIp ?? $request->getClientIp(), $context];
    }
}
```

--------------------------------

### Custom extra_data_provider service in PHP

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/extra-data.md

Defines a custom provider that returns an array with route, request ID, and user agent from the current request. Returns null when no request is available.

```php
<?php

namespace App\Audit;

use Symfony\Component\HttpFoundation\RequestStack;
use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;

final readonly class MyExtraDataProvider
{
    public function __construct(
        private RequestStack $requestStack,
        private TokenStorageInterface $tokenStorage,
    ) {}

    public function __invoke(): ?array
    {
        $request = $this->requestStack->getCurrentRequest();
        if (null === $request) {
            return null;
        }

        return [
            'route'      => $request->attributes->get('_route'),
            'request_id' => $request->headers->get('X-Request-ID'),
            'user_agent' => $request->headers->get('User-Agent'),
        ];
    }
}
```

--------------------------------

### Storage mapper class

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/storage.md

PHP class that routes audits to the correct storage service. All audits go to the audit database by returning the audit entity manager service.

```php
<?php

namespace App\Audit;

use DH\Auditor\Provider\Service\StorageServiceInterface;

class StorageMapper
{
    /**
     * @param string $entity The audited entity FQCN
     * @param array<string, StorageServiceInterface> $storageServices
     */
    public function __invoke(string $entity, array $storageServices): StorageServiceInterface
    {
        // All audits go to the audit database
        return $storageServices['dh_auditor.provider.doctrine.storage_services.doctrine.orm.audit_entity_manager'];
    }
}
```

--------------------------------

### ProxyAwareSecurityProvider - Proxy/Load Balancer IP Detection

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/security-provider.md

Implements SecurityProviderInterface to resolve the client IP when behind a proxy or load balancer. Checks X-Real-IP and X-Forwarded-For headers, handling comma-separated multiple IPs, and returns the firewall config name as context. Requires access to RequestStack and FirewallMap.

```php
<?php

namespace App\Audit;

use DH\Auditor\Security\SecurityProviderInterface;
use Symfony\Bundle\SecurityBundle\Security\FirewallMap;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\RequestStack;

class ProxyAwareSecurityProvider implements SecurityProviderInterface
{
    public function __construct(
        private readonly RequestStack $requestStack,
        private readonly FirewallMap $firewallMap,
    ) {}

    public function __invoke(): array
    {
        $request = $this->requestStack->getCurrentRequest();

        if (!$request instanceof Request) {
            return [null, null];
        }

        // Check proxy headers in order of preference
        $clientIp = $request->headers->get('X-Real-IP')
            ?? $request->headers->get('X-Forwarded-For')
            ?? $request->getClientIp();

        // Handle X-Forwarded-For with multiple IPs
        if (str_contains($clientIp ?? '', ',')) {
            $clientIp = trim(explode(',', $clientIp)[0]);
        }

        $firewallConfig = $this->firewallMap->getFirewallConfig($request);

        return [$clientIp, $firewallConfig?->getName()];
    }
}
```

--------------------------------

### Built-in UserProvider implementation

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/user-provider.md

The default provider that extracts the user from the token and tracks impersonation. It returns null if no identifier or username is found.

```php
public function __invoke(): ?UserInterface
{
    $tokenUser = $this->getTokenUser();
    $impersonatorUser = $this->getImpersonatorUser();

    // Get identifier if getId() method exists
    $identifier = null;
    if ($tokenUser instanceof SymfonyUserInterface) {
        if (method_exists($tokenUser, 'getId')) {
            $identifier = $tokenUser->getId();
        }
        $username = $tokenUser->getUserIdentifier();
    }

    // Track impersonation
    if ($impersonatorUser instanceof SymfonyUserInterface) {
        $username .= '[impersonator '.$impersonatorUser->getUserIdentifier().']';
    }

    if (null === $identifier && null === $username) {
        return null;
    }

    return new User((string) $identifier, $username);
}
```

--------------------------------

### Basic LifecycleEvent Listener with AsEventListener

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/customization/extra-data.md

Registers a listener for LifecycleEvent with priority 10. Filters by entity class and attaches extra data as a JSON string. Uses JSON_THROW_ON_ERROR for encoding.

```php
<?php

namespace App\EventListener;

use App\Entity\User;
use DH\Auditor\Event\LifecycleEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener(event: LifecycleEvent::class, priority: 10)]
final class AuditExtraDataListener
{
    public function __invoke(LifecycleEvent $event): void
    {
        $payload = $event->getPayload();

        // Filter by entity class
        if ($payload['entity'] !== User::class || null === $event->entity) {
            return;
        }

        // Attach extra data as a JSON string
        $payload['extra_data'] = json_encode([
            'department' => $event->entity->getDepartment(),
            'role'       => $event->entity->getRole(),
        ], JSON_THROW_ON_ERROR);

        $event->setPayload($payload);
    }
}
```

--------------------------------

### Configure auditor with environment variables

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/index.md

Use environment variables to set the enabled flag and timezone for the auditor bundle. The enabled variable is cast to boolean, and the timezone is set as a string.

```yaml
dh_auditor:
    enabled: '%env(bool:AUDITOR_ENABLED)%'
    timezone: '%env(AUDITOR_TIMEZONE)%'
```

--------------------------------

### Separate Database Architecture Diagram

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/storage.md

Mermaid flowchart showing entity tables in a main database and audit tables in a separate audit database, with different transactions potentially causing inconsistency.

```mermaid
flowchart LR
    subgraph MAIN["Main Database"]
        direction TB
        users
        posts
    end
    
    subgraph AUDIT["Audit Database"]
        direction TB
        users_audit
        posts_audit
    end
    
    MAIN -.->|Different transactions| AUDIT
    
    style MAIN fill:#e3f2fd
    style AUDIT fill:#fff3e0
```

--------------------------------

### Manually register bundle in config/bundles.php

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/getting-started/installation.md

Add this PHP code to config/bundles.php to register the bundle when not using Symfony Flex.

```php
<?php

return [
    // ...
    DH\AuditorBundle\DHAuditorBundle::class => ['all' => true],
];
```

--------------------------------

### Single Database Architecture Diagram

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/storage.md

Mermaid flowchart showing entity tables and audit tables in the same database, with same-transaction writes ensuring data integrity.

```mermaid
flowchart TB
    subgraph DB["Main Database"]
        direction TB
        subgraph ENTITIES["Entity Tables"]
            users
            posts
            comments
        end
        subgraph AUDITS["Audit Tables"]
            users_audit
            posts_audit
            comments_audit
        end
    end
    
    ENTITIES -.->|Same transaction| AUDITS
    
    style DB fill:#e8f5e9
```

--------------------------------

### Multiple roles with OR logic in #[Security]

Source: https://github.com/damienharper/auditor-bundle/blob/master/docs/configuration/attributes.md

Allows users with either ROLE_ADMIN or ROLE_AUDITOR to view audits. The roles array uses OR logic.

```php
#[Security(view: ['ROLE_ADMIN', 'ROLE_AUDITOR'])]
class User
{
    // Users with ROLE_ADMIN OR ROLE_AUDITOR can view
}
```
Tokens:
Raw