EntityAuditBundle

If you are not using Symfony, you must manually configure the AuditConfiguration, AuditManager, and register the event listeners with the Doctrine EventManager.

use Doctrine\ORM\Configuration;
use Doctrine\ORM\EntityManager;
use Doctrine\Common\EventManager;
use SimpleThings\EntityAudit\AuditConfiguration;
use SimpleThings\EntityAudit\AuditManager;

$auditConfig = new AuditConfiguration();
$auditConfig->setAuditedEntityClasses([ArticleAudit::class, UserAudit::class]);
$auditConfig->setGlobalIgnoreColumns(['created_at', 'updated_at']);

$eventManager = new EventManager();
$auditManager = new AuditManager($auditConfig);
$auditManager->registerEvents($eventManager);

$config = new Configuration();
// ... configure $config and $connection ...
$entityManager = EntityManager::create($connection, $config, $eventManager);

use Doctrine\ORM\Configuration;
use Doctrine\ORM\EntityManager;
use Doctrine\Common\EventManager;
use SimpleThings\EntityAudit\AuditConfiguration;
use SimpleThings\EntityAudit\AuditManager;
use SimpleThings\EntityAudit\Tests\ArticleAudit;
use SimpleThings\EntityAudit\Tests\UserAudit;

$auditConfig = new AuditConfiguration();
$auditConfig->setAuditedEntityClasses([ArticleAudit::class, UserAudit::class]);
$auditConfig->setGlobalIgnoreColumns(['created_at', 'updated_at']);

$eventManager = new EventManager();
$auditManager = new AuditManager($auditConfig);
$auditManager->registerEvents($eventManager);

$config = new Configuration();
// $config ...
$connection = [];
$entityManager = EntityManager::create($connection, $config, $eventManager);

Configure the bundle by loading the simple_things_entity_audit extension. You must specify which entities should be audited.

Basic Configuration

Specify the list of audited entity classes under audited_entities:

# config/packages/entity_audit.yaml

simple_things_entity_audit:
    audited_entities:
        - MyBundle\Entity\MyEntity
        - MyBundle\Entity\MyEntity2

Advanced Configuration Options

• global_ignore_columns: List of entity properties that should not trigger a revision when changed (e.g., timestamps).
• connection: Specify a custom Doctrine connection name if not using default.
• entity_manager: Specify a custom Doctrine entity manager name if not using default.
• disable_foreign_keys: Set to true to discard inferred foreign keys from audited entities.
• service.username_callable: Define a service ID for a custom callable that resolves the current username.

# config/packages/entity_audit.yaml

simple_things_entity_audit:
    audited_entities:
        - MyBundle\Entity\MyEntity
    global_ignore_columns:
        - created_at
        - updated_at
    connection: custom
    entity_manager: custom
    disable_foreign_keys: true

AuditedCollection is a specialized implementation of the Doctrine Collection interface used to represent a collection of entities as they existed at a specific point in time (a specific revision).

Key Characteristics

• Read-Only: You cannot add, remove, or modify elements in an AuditedCollection. Attempting to use add(), remove(), removeElement(), set(), or offsetSet() will throw an AuditedCollectionException.
• Lazy Loading: The collection initially contains only metadata (identifiers and revision information). Actual entity objects are loaded from the audit tables only when you attempt to access them (e.g., via get(), current(), toArray(), or iterating over the collection).
• Historical Accuracy: It uses the AuditReader to resolve identifiers into the actual state of the entity at the requested revision, ensuring that the collection reflects the database state at that specific time.

Common Operations

Since it implements Collection, you can use standard methods to inspect the historical data:

• count(): Returns the number of entities in the collection.
• toArray(): Returns an array of the loaded entity objects.
• filter(\Closure $p): Returns a new collection containing elements that satisfy the predicate.
• first() / last(): Retrieves the first or last entity in the collection.
• get($key): Retrieves a specific entity by its key (if indexBy was configured).

Use the SimpleThings\EntityAudit\AuditReader to retrieve historical data. In Symfony, this is available via dependency injection. In standalone apps, create it from the AuditManager.

Find entity state at a specific revision

Returns the state of an entity at a specific revision number. Note: Instances returned by find() are not managed by the EntityManager's UnitOfWork; you must merge() them if you intend to continue working with them in the current persistence context.

$articleAudit = $auditReader->find(
    SimpleThings\EntityAudit\Tests\ArticleAudit::class,
    $id = 1,
    $rev = 10
);

Find revision history of an entity

Returns a list of all revisions associated with a specific entity ID.

$revisions = $auditReader->findRevisions(
    SimpleThings\EntityAudit\Tests\ArticleAudit::class,
    $id = 1
);

Each Revision object provides:

• getRev(): The revision ID.
• getTimestamp(): The time of change.
• getUsername(): The user who made the change.

Find entities changed at a specific revision

Returns a list of all ChangedEntity objects modified during a specific global revision.

$changedEntities = $auditReader->findEntitiesChangedAtRevision(10);

Each ChangedEntity provides:

• getClassName()
• getId()
• getRevisionType()
• getEntity()

Find current revision of an entity

$revision = $auditReader->getCurrentRevision(
    'SimpleThings\EntityAudit\Tests\ArticleAudit',
    $id = 3
);

use SimpleThings
EntityAudit
AuditReader;

// In a Symfony Controller
public function indexAction(AuditReader $auditReader)
{
    // Find entity state at revision 10
    $articleAudit = $auditReader->find(
        SimpleThings\EntityAudit\Tests\ArticleAudit::class,
        1,
        10
    );

    // Find revisions for an entity
    $revisions = $auditReader->findRevisions(
        SimpleThings\EntityAudit\Tests\ArticleAudit::class,
        1
    );
}