Zhortein Doctrine Lifecycle Bundle

Reusable Doctrine lifecycle features for Symfony entities.

This bundle provides a clean and focused foundation for common entity lifecycle concerns in Symfony applications using Doctrine ORM.

It currently includes:

• Timestampable support
• Blameable support
• Doctrine lifecycle listeners based on attributes
• UTC-based lifecycle timestamps

The bundle is designed to stay small, explicit and reusable.

---

Features

Timestampable

Automatic handling of:

• createdAt
• updatedAt

Blameable

Automatic handling of:

• createdByIdentifier
• updatedByIdentifier

Blameable values are stored as scalar identifiers, which keeps the bundle generic and independent from any application-specific User entity.

Doctrine integration

The bundle uses Doctrine listeners to update lifecycle fields automatically on:

• prePersist
• preUpdate

UTC timestamps

Lifecycle dates are generated in UTC to provide predictable and consistent storage across applications.

---

Current Scope

This bundle focuses only on entity lifecycle metadata.

It does not try to handle:

• audit trail history
• workflow/state machines
• publication systems
• translations
• business-specific ownership models

If you need full audit logging, use a dedicated audit bundle alongside this one.

---

Requirements

• PHP 8.4+
• Symfony 7.4 or 8.0
• Doctrine Bundle
• Doctrine ORM

---

Installation

Composer

composer require zhortein/doctrine-lifecycle-bundle

Bundle registration

If Symfony Flex does not register the bundle automatically, add it manually in config/bundles.php:

<?php

return [
    // ...
    Zhortein\DoctrineLifecycleBundle\ZhorteinDoctrineLifecycleBundle::class => ['all' => true],
];

---

Default Behavior

Timestampable

On prePersist:

• createdAt is set if it is currently null
• updatedAt is always set

On preUpdate:

• updatedAt is updated

Blameable

On prePersist:

• createdByIdentifier is set if it is currently null
• updatedByIdentifier is always set

On preUpdate:

• updatedByIdentifier is updated

If no actor can be resolved, blameable fields remain unchanged.

---

Usage

Timestampable

1. Implement the interface and use the trait

<?php

declare(strict_types=1);

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Zhortein\DoctrineLifecycleBundle\Contract\TimestampableInterface;
use Zhortein\DoctrineLifecycleBundle\Trait\TimestampableTrait;

#[ORM\Entity]
final class Destination implements TimestampableInterface
{
    use TimestampableTrait;

    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private string $name;

    public function __construct(string $name)
    {
        $this->name = $name;
    }
}

2. Result

The bundle will automatically maintain:

• createdAt
• updatedAt

---

Blameable

1. Implement the interface and use the trait

<?php

declare(strict_types=1);

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Zhortein\DoctrineLifecycleBundle\Contract\BlameableInterface;
use Zhortein\DoctrineLifecycleBundle\Trait\BlameableTrait;

#[ORM\Entity]
final class Article implements BlameableInterface
{
    use BlameableTrait;

    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private string $title;

    public function __construct(string $title)
    {
        $this->title = $title;
    }
}

2. Result

The bundle will automatically maintain:

• createdByIdentifier
• updatedByIdentifier

These values are provided by an ActorResolverInterface.

---

Timestampable + Blameable together

A single entity can use both features:

<?php

declare(strict_types=1);

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Zhortein\DoctrineLifecycleBundle\Contract\BlameableInterface;
use Zhortein\DoctrineLifecycleBundle\Contract\TimestampableInterface;
use Zhortein\DoctrineLifecycleBundle\Trait\BlameableTrait;
use Zhortein\DoctrineLifecycleBundle\Trait\TimestampableTrait;

#[ORM\Entity]
final class ExpertProfile implements TimestampableInterface, BlameableInterface
{
    use TimestampableTrait;
    use BlameableTrait;

    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    private string $displayName;

    public function __construct(string $displayName)
    {
        $this->displayName = $displayName;
    }
}

---

Actor Resolver

The bundle relies on the following contract:

<?php

declare(strict_types=1);

namespace Zhortein\DoctrineLifecycleBundle\Resolver;

interface ActorResolverInterface
{
    public function resolveActorIdentifier(): ?string;
}

By default, the bundle provides a null resolver, which means blameable fields remain null unless you override the service.

---

Using Symfony Security as actor resolver

In most applications, you will want to resolve the actor identifier from the authenticated user.

Example:

<?php

declare(strict_types=1);

namespace App\Security;

use Symfony\Bundle\SecurityBundle\Security;
use Zhortein\DoctrineLifecycleBundle\Resolver\ActorResolverInterface;

final class SecurityActorResolver implements ActorResolverInterface
{
    public function __construct(
        private readonly Security $security,
    ) {
    }

    public function resolveActorIdentifier(): ?string
    {
        $user = $this->security->getUser();

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

        if (!method_exists($user, 'getUserIdentifier')) {
            return null;
        }

        return $user->getUserIdentifier();
    }
}

Then override the resolver binding in your application:

services:
    App\Security\SecurityActorResolver: ~

    Zhortein\DoctrineLifecycleBundle\Resolver\ActorResolverInterface:
        alias: App\Security\SecurityActorResolver

---

Notes about timestamps

This bundle stores lifecycle timestamps as:

• \DateTimeImmutable
• Doctrine datetime_immutable
• generated in UTC

This is intentional.

The bundle handles technical lifecycle timestamps, not application-level timezone presentation.
If your application needs to display dates in a specific timezone, convert them at application level.

Example:

$localDate = $entity->getUpdatedAt()?->setTimezone(new \DateTimeZone('Europe/Paris'));

---

Philosophy

This bundle intentionally follows a few rules:

• keep the scope narrow
• avoid application-specific assumptions
• stay independent from the host application's User entity
• prefer predictable behavior over excessive magic
• make integration simple in real Symfony projects

---

Development Status

The bundle is already usable for:

• timestampable metadata
• blameable metadata
• real integration into Symfony applications

Additional lifecycle helpers may come later, but only if they remain aligned with the bundle's narrow scope.

---

Roadmap

Possible future additions:

• soft delete metadata support
• optional configuration improvements
• additional integration tests
• more documentation and recipes

---

Quality Assurance

This bundle includes:

• PHPUnit tests
• PHPStan configuration
• PHP-CS-Fixer configuration
• CI workflow

Typical local commands:

make csfixer
make phpstan
make test

---

Testing locally with a path repository

When developing the bundle alongside a Symfony project, you can use a Composer path repository in the host application:

{
  "repositories": [
    {
      "type": "path",
      "url": "../doctrine-lifecycle-bundle",
      "options": {
        "symlink": true
      }
    }
  ],
  "require": {
    "zhortein/doctrine-lifecycle-bundle": "*@dev"
  }
}

This allows you to test the bundle directly in a real application without publishing it first.

---

License

This bundle is released under the MIT License.