README

Logging of changes in Doctrine entities. Every change is stored as one change_log row with the change set serialized to JSON, so the log is readable straight from the database.

Installation

Install via composer:
```
composer require adt/doctrine-loggable
```

extensions:
    - ADT\DoctrineLoggable\DI\LoggableExtension

Do database migrations
Add attributes to entities you wish to log

<?php

use Doctrine\ORM\Mapping as ORM;
use ADT\DoctrineLoggable\Attributes as ADA;

#[ORM\Entity]
#[ADA\LoggableEntity]
class User
{
	#[ORM\Column(nullable: true)]
	#[ADA\LoggableProperty]
	protected ?string $firstname = null;

	#[ORM\ManyToMany(targetEntity: Role::class, inversedBy: 'users')]
	#[ADA\LoggableProperty]
	protected Collection $roles;
}

#[ORM\Entity]
#[ADA\LoggableIdentification(fields: ['name'])]
class Role
{
	#[ORM\Column]
	protected string $name;

	#[ORM\ManyToMany(targetEntity: User::class, mappedBy: 'roles')]
	protected Collection $users;
}

Stored format

The change_set column is a JSON column handled by the change_set DBAL type, which the extension registers for you. ChangeLog::getChangeSet() returns the usual ChangeSet object graph.

{
  "version": 1,
  "action": "edit",
  "entity": {
    "class": "App\\Model\\Entities\\Product",
    "id": "42",
    "identification": { "name": "Pivo 12°" }
  },
  "properties": {
    "name":  { "type": "scalar", "old": "Pivo", "new": "Pivo 12°" },
    "price": { "type": "scalar", "old": 39.0, "new": 45.0 },
    "validFrom": {
      "type": "scalar",
      "old": null,
      "new": { "@type": "datetime", "class": "DateTimeImmutable", "value": "2026-08-27T12:00:00+02:00" }
    },
    "category": {
      "type": "toOne",
      "old": { "class": "App\\Model\\Entities\\Category", "id": "3", "identification": { "name": "Nápoje" } },
      "new": { "class": "App\\Model\\Entities\\Category", "id": "7", "identification": { "name": "Pivo" } },
      "changeSet": null
    },
    "tags": {
      "type": "toMany",
      "added":   [ { "class": "App\\Model\\Entities\\Tag", "id": "9", "identification": { "name": "akce" } } ],
      "removed": [],
      "changeSets": []
    }
  }
}

A value position holds either a plain JSON scalar or an envelope object with the @type key. Arrays never appear raw in a value position, so @type is always an unambiguous marker. Built-in envelope types are datetime, enum, array, binary, float (for NAN and INF) and object as the last resort fallback.

The property type is a scalar/toOne/toMany discriminator rather than a class name, so the classes of this library can be moved or renamed without breaking existing logs.

The change set graph may contain cycles. A change set referenced more than once gets a $id and every further occurrence is written as {"$ref": id}. Change sets referenced just once, which is almost always the case, carry no ids at all.

Custom value types

Values coming from custom Doctrine types (money, uuid, embeddables) end up in the object envelope, which keeps their readable representation but does not restore the original object. Register a handler to make the round trip lossless:

use ADT\DoctrineLoggable\Serializer\ValueHandler;
use ADT\DoctrineLoggable\Serializer\ValueSerializer;

class MoneyHandler implements ValueHandler
{
	public function getType(): string
	{
		return 'money';
	}

	public function supports(mixed $value): bool
	{
		return $value instanceof Money;
	}

	public function encode(mixed $value, ValueSerializer $serializer): array
	{
		return ['amount' => $value->getAmount(), 'currency' => $value->getCurrency()];
	}

	public function decode(array $data, ValueSerializer $serializer): Money
	{
		return new Money($data['amount'], $data['currency']);
	}
}

doctrineLoggable:
    valueHandlers:
        - App\Log\MoneyHandler

Handlers registered this way are tried before the built-in ones, so they can override them.

Upgrading from 3.x

The change_set column changes from LONGBLOB holding a PHP serialize() payload to a JSON column. Convert the existing rows first, while the column is still a BLOB:

php bin/console doctrine-loggable:convert-legacy-change-sets --dry-run
php bin/console doctrine-loggable:convert-legacy-change-sets

The command reads and rewrites the rows with plain SQL, so the change_set DBAL type never sees a legacy payload. It commits per batch (--batch-size, 500 by default), recognises rows that already hold JSON and leaves them alone, so it is safe to run again. A row that fails to convert is reported and left untouched, and the command exits with a failure so you do not change the column type on top of data that did not make it.

Only when it reports no failures:

ALTER TABLE change_log MODIFY change_set JSON NOT NULL;

symfony/console is optional. Without it the command is not registered and you can drive ADT\DoctrineLoggable\Service\LegacyChangeSetConverter yourself.

Adt\DoctrineLoggable\ChangeSet\* is now declared as ADT\DoctrineLoggable\ChangeSet\*, which is what the PSR-4 prefix always said. The old casing keeps autoloading, PHP treats both as the same class.

Tests

composer install
vendor/bin/phpunit

adt / doctrine-loggable

Package info

Security

Statistics