DoctrineAuditBundle

This bundle creates audit logs for all Doctrine ORM database related changes:

• inserts and updates including their diffs and relation field diffs.
• many to many relation changes, association and dissociation actions.
• if there is an user in token storage, it is used to identify the user who made the changes.
• the audit entries are inserted within the same transaction during flush, if something fails the state remains clean.

Basically you can track any change from these log entries if they were managed through standard ORM operations.

NOTE: audit cannot track DQL or direct SQL updates or delete statement executions.

You can try this bundle by cloning its companion demo app. Follow instructions at doctrine-audit-bundle-demo.

This bundle is inspired by data-dog/audit-bundle and simplethings/entity-audit-bundle

A changelog is available here

Installation

Applications that use Symfony Flex

Open a command console, enter your project directory and execute:

composer require damienharper/doctrine-audit-bundle

Applications that don't use Symfony Flex

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

composer require damienharper/doctrine-audit-bundle

This command requires you to have Composer installed globally, as explained in the installation chapter of the Composer documentation.

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the app/AppKernel.php file of your project:

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new DH\DoctrineAuditBundle\DHDoctrineAuditBundle(),
            new WhiteOctober\PagerfantaBundle\WhiteOctoberPagerfantaBundle(), // only required if you plan to use included viewer/templates
        );

        // ...
    }

    // ...
}

Configuration

Audited entities and properties

By default, DoctrineAuditBundle won't audit any entity, you have to configure which entities have to be audited.

// app/config/config.yml (symfony < 3.4)
// config/packages/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    entities:
        MyBundle\Entity\MyAuditedEntity1: ~
        MyBundle\Entity\MyAuditedEntity2: ~

All MyAuditedEntity1 and MyAuditedEntity2 properties will be audited. Though it is possible to exclude some of them from the audit process.

// app/config/config.yml (symfony < 3.4)
// config/packages/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    entities:
        MyBundle\Entity\MyAuditedEntity1: ~   # all MyAuditedEntity1 properties are audited
        MyBundle\Entity\MyAuditedEntity2:
            ignored_columns:                  # properties ignored by the audit process
                - createdAt
                - updatedAt

It is also possible to specify properties that are globally ignored by the audit process.

// app/config/config.yml (symfony < 3.4)
// config/packages/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    ignored_columns:    # properties ignored by the audit process in any audited entity
        - createdAt
        - updatedAt

Audit tables naming format

Audit table names are composed of a prefix, the audited table name and a suffix. By default, the prefix is empty and the suffix is _audit. Though, they can be customized.

// app/config/config.yml (symfony < 3.4)
// config/packages/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    table_prefix: ''
    table_suffix: '_audit'

Timezone

You can configure the timezone the audit created_at is generated in. This by default is 'UTC'.

// app/config/config.yml (symfony < 3.4)
// config/packages/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    timezone: 'Europe/London'

Creating audit tables

Open a command console, enter your project directory and execute the following command to review the new audit tables in the update schema queue.

# symfony < 3.4
app/console doctrine:schema:update --dump-sql 

# symfony >= 3.4
bin/console doctrine:schema:update --dump-sql 

Notice: DoctrineAuditBundle currently only works with a DBAL Connection and EntityManager named "default".

Using Doctrine Migrations Bundle

# symfony < 3.4
app/console doctrine:migrations:diff
app/console doctrine:migrations:migrate

# symfony >= 3.4
bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

Using Doctrine Schema

# symfony < 3.4
app/console doctrine:schema:update --force

# symfony >= 3.4
bin/console doctrine:schema:update --force

Custom database for storage audit

Warning: Using custom database for storing audit breaks atomicity. Audited entity operation is performed into different transactions. It means that:

• if the current audited entity operation fails, audit data is still persisted to the separate database which is very bad (reference to entity data which doesn't exist in the main database or reference to entity data in main database which doesn't reflect changes logged in audit data)

• if the current audited entity operation succeed, audit data persistence in the separate database still can fail which is bad but can be acceptable in some use cases (depending on how critical audit data is for your application/business, missing audit data could be acceptable)

It is possible to save audits in a different database than the one where audited entities live. To do that you have change the last argument of dh_doctrine_audit.configuration service to set the entity manager binded to that second database.

// config/services.yaml (symfony >= 3.4)
dh_doctrine_audit.configuration:
    class: DH\DoctrineAuditBundle\AuditConfiguration
    arguments:
        - "%dh_doctrine_audit.configuration%"
        - "@dh_doctrine_audit.user_provider"
        - "@request_stack"
        - "@security.firewall.map"
        - "@doctrine.orm.your_custom_entity_manager"

Audit viewer

Add the following routes to the routing configuration to enable the included audits viewer.

// app/config/routing.yml (symfony < 3.4)
// config/routes.yaml (symfony >= 3.4)
dh_doctrine_audit:
    resource: "@DHDoctrineAuditBundle/Controller/"
    type: annotation

It is possible to filter results by event type by calling AuditReader::filterBy method before getting the results.

/**
 * @Route("/audit/details/{entity}/{id}", name="dh_doctrine_audit_show_audit_entry", methods={"GET"})
 */
public function showAuditEntryAction(string $entity, int $id)
{
    $reader = $this->container->get('dh_doctrine_audit.reader');
    
    $data = $reader
         ->filterBy(AuditReader::UPDATE)   // add this to only get `update` entries.
         ->getAudit($entity, $id)
     ;

    return $this->render('@DHDoctrineAudit/Audit/entity_audit_details.html.twig', [
        'entity' => $entity,
        'entry' => $data[0],
    ]);
}

Available constants are:

AuditReader::UPDATE
AuditReader::ASSOCIATE
AuditReader::DISSOCIATE
AuditReader::INSERT
AuditReader::REMOVE

Custom user provider

If you don't use Symfony's TokenStorage to save your current user, you can configure a custom user provider. You just need to implement the UserProviderInterface and configure it as a service named dh_doctrine_audit.user_provider.

use DH\DoctrineAuditBundle\User\User;
use DH\DoctrineAuditBundle\User\UserInterface;
use DH\DoctrineAuditBundle\User\UserProviderInterface;

class CustomUserProvider implements UserProviderInterface
{
    public function getUser(): ?UserInterface
    {
        // Your logic goes here...
        return new User($yourUserId, $yourUsername);
    }
}

Then add this to your services.yaml file:

services:
    dh_doctrine_audit.user_provider:
        class: App\CustomUserProvider

Enabling and disabling the auditing of entities

You can enable or disable the auditing of entities globally, per entity and at runtime. By default, it is enabled globally.

Globally enable/disable

Global enabling/disabling is done in the configuration file.

• When enabled globally, all entities configured under the entities section of the configuration file are audited unless explicitly disabled in their audit configuration (cf. Per entity enabling/disabling).
• When disabled globally, nothing is audited.

// app/config/config.yml (symfony < 3.4)
// config/packages/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    enabled: true

Per entity enable/disable

Per entity enabling/disabling is done in the configuration file.

This lets you disable audit logging for an entity by default and only enable auditing when needed for example. To do so, add this to your configuration file:

// app/config/config.yml (symfony < 3.4)
// config/packages/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    enabled: true                               # auditing is globally enabled
    entities:
        MyBundle\Entity\MyAuditedEntity1:
            enabled: false                      # auditing of this entity is disabled
        MyBundle\Entity\MyAuditedEntity2: ~     # auditing of this entity is enabled

In the above example, an audit table will be created for MyAuditedEntity1, but audit entries will only be saved when auditing is explicitly enabled at runtime.

At runtime enable/disable

Warning: disabling audit logging for an entity will make its audit logs incomplete/partial (no change applied to specified entity is logged in the relevant audit table while audit logging is disabled for that entity).

You can disable audit logging at runtime by calling AuditConfiguration::disableAuditFor(string $entity) This will prevent the system from logging changes applied to $entity objects.

You can then re-enable audit logging at runtime by calling AuditConfiguration::enableAuditFor(string $entity)

To disable auditing for an entity, you first have to inject the dh_doctrine_audit.configuration service in your class, then use:

$auditConfiguration->disableAuditFor(MyAuditedEntity1::class);

To enable auditing afterwards, use:

$auditConfiguration->enableAuditFor(MyAuditedEntity1::class);

Usage

audit entities will be mapped automatically if you run schema update or similar. And all the database changes will be reflected in the audit logs afterwards.

Audits cleanup

Notice: symfony/lock is required, to install it use composer require symfony/lock

DoctrineAuditBundle provides a convenient command that helps you cleaning audit tables. Open a command console, enter your project directory and execute:

# symfony < 3.4
app/console audit:clean

# symfony >= 3.4
bin/console audit:clean

By default it cleans audit entries older than 12 months. You can override this by providing the number of months you want to keep in the audit tables. For example, to keep 18 months:

# symfony < 3.4
app/console audit:clean 18

# symfony >= 3.4
bin/console audit:clean 18

It is also possible to bypass the confirmation and make the command non-interactive if you plan to schedule it (ie. cron)

# symfony < 3.4
app/console audit:clean --no-confirm

# symfony >= 3.4
bin/console audit:clean --no-confirm

FAQ:

I've added an new entity in the config file but it's not audited.

First check its namespace, then clear your cache and re-run doctrine:schema:update or doctrine:migrations:migrate.

I don't use Symfony's TokenStorage to manage my users, how do I proceed?

Check the Custom user provider section.

Contributing

DoctrineAuditBundle is an open source project. Contributions made by the community are welcome. Send us your ideas, code reviews, pull requests and feature requests to help us improve this project.

Do not forget to provide unit tests when contributing to this project. To do so, follow instructions in this dedicated README

Supported DB

• MySQL
• MariaDB
• PostgreSQL
• SQLite

This bundle should work with any other database supported by Doctrine. Though, we can only really support the ones we can test with Travis-CI.

License

DoctrineAuditBundle is free to use and is licensed under the MIT license