Developed with love by KnpLabs Hire us for your project!
31

DoctrineAuditBundle

by DamienHarper

This bundle creates audit logs for all doctrine ORM database related changes.

DoctrineAuditBundle

GitHub license
release-version-badge
php-version-badge

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.

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

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(),
        );

        // ...
    }

    // ...
}

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/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/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/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/dh_doctrine_audit.yaml (symfony >= 3.4)
dh_doctrine_audit:
    table_prefix: ''
    table_suffix: '_audit'

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

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

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

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 un-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

License

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

<!-- Badges -->

MIT License

Copyright 2018 Damien Harper

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
  • Fix listener on embedded field (#17)
    By DamienHarper, 3 months ago
  • Use native Twig references for templates (#16)
    By DamienHarper, 3 months ago
  • Allow singe table inheritance (#15)
    By DamienHarper, 3 months ago
  • Changed type conversion again. Should be better with non default Doctrine types.
    By DamienHarper, 3 months ago
  • Fix for #11
    By DamienHarper, 3 months ago
  • Use of camelcase to name properties (more common practice)
    By DamienHarper, 4 months ago
  • PHP-CS-Fixer
    By DamienHarper, 4 months ago
  • Changed the way values are type converted and compared (should fix #7)
    By DamienHarper, 4 months ago
  • Refactoring
    By DamienHarper, 6 months ago
  • Merge branch 'master' of https://github.com/DamienHarper/DoctrineAuditBundle
    By DamienHarper, 6 months ago
  • Removed unused import
    By DamienHarper, 6 months ago
  • Strict comparisons (#6)
    By DamienHarper, 6 months ago
  • Remove deprecated call to getEntityManager()
    By DamienHarper, 6 months ago
  • Process inserts before updates in the onFlush subscriber and log associations for both OneToMany and ManyToMany associations
    By DamienHarper, 7 months ago
  • Doc fix
    By DamienHarper, 7 months ago
  • Fixed an issue (#3) related to using a table prefix and explicitly specifying a schema name.
    By DamienHarper, 7 months ago
  • Merge pull request #2 from nnmer/diff-method-use-leters
    By web-flow, 8 months ago
  • update entity_audit_details file for old|new vs -|+
    By nnmer, 8 months ago
  • Merge pull request #1 from nnmer/fix-command-compatible-symfony3.3
    By web-flow, 8 months ago
  • AuditSubscriber diff method use old|new vs -|+
    By web-flow, 8 months ago
  • Set command name to support symfony 3.3
    By web-flow, 8 months ago
  • Clean command lazy loaded.
    By DamienHarper, 8 months ago
  • Fixed license.
    By DamienHarper, 9 months ago
  • Get real class name for proxy objects.
    By DamienHarper, 9 months ago
  • Refactoring and doc
    By DamienHarper, 9 months ago
  • Updated README
    By DamienHarper, 9 months ago
  • Refactoring and coding standards
    By DamienHarper, 9 months ago
  • Add a command to clean audit logs.
    By DamienHarper, 9 months ago
  • Add a command to clean audit logs.
    By DamienHarper, 9 months ago
  • Add ability to ignore columns from audit process globally and at entity level.
    By DamienHarper, 9 months ago