feat(shared) : add Timestampable + Blamable Shared pattern (Trait + Interfaces + Subscriber + test)

config/packages/doctrine.yaml

@@ -33,6 +33,10 @@ doctrine:
         # `App\Module\Sites\Domain\Entity\Site` dans User.php.
         resolve_target_entities:
             App\Shared\Domain\Contract\SiteInterface: App\Module\Sites\Domain\Entity\Site
+            # Cible des ManyToOne created_by / updated_by du TimestampableBlamableTrait.
+            # Permet a Shared de referencer UserInterface dans ses ORM mappings sans
+            # importer la classe concrete du module Core (cf. spec-back M0 § 2.8).
+            Symfony\Component\Security\Core\User\UserInterface: App\Module\Core\Domain\Entity\User
         mappings:
             Core:
                 type: attribute

src/Shared/Domain/Contract/BlamableInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Domain\Contract;
+
+use Symfony\Component\Security\Core\User\UserInterface;
+
+/**
+ * Contrat lu par le TimestampableBlamableSubscriber.
+ *
+ * Toute entite qui l'implemente voit ses colonnes `created_by` / `updated_by`
+ * remplies automatiquement avec l'utilisateur authentifie (ou laissees a null
+ * hors contexte HTTP : CLI, cron, migration).
+ *
+ * Le type-hint cible `Symfony\Component\Security\Core\User\UserInterface`
+ * (deja implementee par App\Module\Core\Domain\Entity\User) pour eviter de
+ * coupler Shared a Module/Core. La classe concrete est resolue par Doctrine
+ * via `resolve_target_entities` (cf. config/packages/doctrine.yaml).
+ */
+interface BlamableInterface
+{
+    public function getCreatedBy(): ?UserInterface;
+
+    public function setCreatedBy(?UserInterface $user): void;
+
+    public function getUpdatedBy(): ?UserInterface;
+
+    public function setUpdatedBy(?UserInterface $user): void;
+}

src/Shared/Domain/Contract/TimestampableInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Domain\Contract;
+
+use DateTimeImmutable;
+
+/**
+ * Contrat lu par le TimestampableBlamableSubscriber.
+ *
+ * Toute entite qui l'implemente voit ses colonnes `created_at` / `updated_at`
+ * remplies automatiquement au prePersist / preUpdate. Le porteur des colonnes
+ * et des accesseurs est le TimestampableBlamableTrait.
+ */
+interface TimestampableInterface
+{
+    public function getCreatedAt(): ?DateTimeImmutable;
+
+    public function setCreatedAt(DateTimeImmutable $createdAt): void;
+
+    public function getUpdatedAt(): ?DateTimeImmutable;
+
+    public function setUpdatedAt(DateTimeImmutable $updatedAt): void;
+}

src/Shared/Domain/Trait/TimestampableBlamableTrait.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Domain\Trait;
+
+use DateTimeImmutable;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Security\Core\User\UserInterface;
+use Symfony\Component\Serializer\Attribute\Groups;
+
+/**
+ * Trait Doctrine qui porte les 4 colonnes Timestampable + Blamable.
+ *
+ * Usage : `use TimestampableBlamableTrait;` dans l'entite, +
+ * `implements TimestampableInterface, BlamableInterface`. Le
+ * TimestampableBlamableSubscriber remplit les colonnes automatiquement
+ * au prePersist / preUpdate.
+ *
+ * Les Groups Serializer utilisent une convention `default:read` agregee :
+ * pour exposer les 4 colonnes dans une reponse API d'une entite X, ajouter
+ * `default:read` au normalizationContext aux cotes du groupe `x:read`.
+ */
+trait TimestampableBlamableTrait
+{
+    #[ORM\Column(name: 'created_at', type: 'datetime_immutable')]
+    #[Groups(['default:read'])]
+    private ?DateTimeImmutable $createdAt = null;
+
+    #[ORM\Column(name: 'updated_at', type: 'datetime_immutable')]
+    #[Groups(['default:read'])]
+    private ?DateTimeImmutable $updatedAt = null;
+
+    #[ORM\ManyToOne(targetEntity: UserInterface::class)]
+    #[ORM\JoinColumn(name: 'created_by', referencedColumnName: 'id', nullable: true, onDelete: 'SET NULL')]
+    #[Groups(['default:read'])]
+    private ?UserInterface $createdBy = null;
+
+    #[ORM\ManyToOne(targetEntity: UserInterface::class)]
+    #[ORM\JoinColumn(name: 'updated_by', referencedColumnName: 'id', nullable: true, onDelete: 'SET NULL')]
+    #[Groups(['default:read'])]
+    private ?UserInterface $updatedBy = null;
+
+    public function getCreatedAt(): ?DateTimeImmutable
+    {
+        return $this->createdAt;
+    }
+
+    public function setCreatedAt(DateTimeImmutable $createdAt): void
+    {
+        $this->createdAt = $createdAt;
+    }
+
+    public function getUpdatedAt(): ?DateTimeImmutable
+    {
+        return $this->updatedAt;
+    }
+
+    public function setUpdatedAt(DateTimeImmutable $updatedAt): void
+    {
+        $this->updatedAt = $updatedAt;
+    }
+
+    public function getCreatedBy(): ?UserInterface
+    {
+        return $this->createdBy;
+    }
+
+    public function setCreatedBy(?UserInterface $user): void
+    {
+        $this->createdBy = $user;
+    }
+
+    public function getUpdatedBy(): ?UserInterface
+    {
+        return $this->updatedBy;
+    }
+
+    public function setUpdatedBy(?UserInterface $user): void
+    {
+        $this->updatedBy = $user;
+    }
+}

src/Shared/Infrastructure/Doctrine/TimestampableBlamableSubscriber.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Infrastructure\Doctrine;
+
+use App\Shared\Domain\Contract\BlamableInterface;
+use App\Shared\Domain\Contract\TimestampableInterface;
+use DateTimeImmutable;
+use Doctrine\Bundle\DoctrineBundle\Attribute\AsDoctrineListener;
+use Doctrine\ORM\Event\PrePersistEventArgs;
+use Doctrine\ORM\Event\PreUpdateEventArgs;
+use Doctrine\ORM\Events;
+use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\Security\Core\User\UserInterface;
+
+/**
+ * Listener Doctrine global qui remplit automatiquement les colonnes
+ * Timestampable + Blamable.
+ *
+ * Pattern aligne sur AuditListener (cf.
+ * src/Module/Core/Infrastructure/Doctrine/AuditListener.php) : declare via
+ * #[AsDoctrineListener], auto-wire par le DoctrineBundle.
+ *
+ * Regle Blamable : si aucun utilisateur n'est authentifie (CLI, cron,
+ * migration), les FK `created_by` / `updated_by` restent a null. L'affichage
+ * front gere le libelle « Systeme » pour null.
+ */
+#[AsDoctrineListener(event: Events::prePersist)]
+#[AsDoctrineListener(event: Events::preUpdate)]
+final class TimestampableBlamableSubscriber
+{
+    public function __construct(private readonly Security $security) {}
+
+    public function prePersist(PrePersistEventArgs $args): void
+    {
+        $entity = $args->getObject();
+        $now    = new DateTimeImmutable();
+        $user   = $this->security->getUser();
+
+        if ($entity instanceof TimestampableInterface) {
+            $entity->setCreatedAt($now);
+            $entity->setUpdatedAt($now);
+        }
+
+        if ($entity instanceof BlamableInterface && $user instanceof UserInterface) {
+            $entity->setCreatedBy($user);
+            $entity->setUpdatedBy($user);
+        }
+    }
+
+    public function preUpdate(PreUpdateEventArgs $args): void
+    {
+        $entity = $args->getObject();
+        $user   = $this->security->getUser();
+
+        if ($entity instanceof TimestampableInterface) {
+            $entity->setUpdatedAt(new DateTimeImmutable());
+        }
+
+        if ($entity instanceof BlamableInterface && $user instanceof UserInterface) {
+            $entity->setUpdatedBy($user);
+        }
+    }
+}

tests/Architecture/EntitiesAreTimestampableBlamableTest.php

@@ -0,0 +1,124 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Architecture;
+
+use App\Module\Core\Domain\Entity\Permission;
+use App\Module\Core\Domain\Entity\Role;
+use App\Module\Core\Domain\Entity\User;
+use App\Module\Sites\Domain\Entity\Site;
+use App\Shared\Domain\Contract\BlamableInterface;
+use App\Shared\Domain\Contract\TimestampableInterface;
+use Doctrine\ORM\Mapping\Entity;
+use PHPUnit\Framework\TestCase;
+use ReflectionClass;
+use Symfony\Component\Finder\Finder;
+
+use function in_array;
+
+/**
+ * Garde-fou architecture (niveau L3 de la spec § 2.8.bis).
+ *
+ * Scanne toutes les entites Doctrine sous `src/Module/<module>/Domain/Entity/`
+ * et verifie qu'elles implementent TimestampableInterface ET BlamableInterface
+ * (via TimestampableBlamableTrait). Empeche tout oubli du pattern sur une
+ * nouvelle entite metier : la CI passe au rouge.
+ *
+ * @internal
+ */
+final class EntitiesAreTimestampableBlamableTest extends TestCase
+{
+    /**
+     * Entites explicitement exemptees du pattern.
+     *
+     * Au M0, on whiteliste les 4 entites preexistantes du noyau (creees avant
+     * l'introduction du pattern) : leur retrofit est une decision archi a part
+     * entiere, hors scope ERP-52.
+     *
+     * - User : referentiel d'authentification, createdAt gere manuellement dans
+     *   le constructeur. Retrofit hors scope M0 (cf. HP-9) : impose de trancher
+     *   la recursion Blamable (un User cree par un User) + casse des tests
+     *   existants.
+     * - Role : referentiel RBAC synchronise via `app:sync-permissions`, pas de
+     *   tracabilite user-driven necessaire.
+     * - Permission : idem Role (synchronise, pas pilote utilisateur).
+     * - Site : referentiel admin-managed, a integrer dans un futur module Sites
+     *   v2 (cf. HP-10).
+     *
+     * Les futurs referentiels statiques (ex: CategoryType au ticket 0.2)
+     * s'ajoutent ici avec une justification.
+     */
+    private const EXCLUDED = [
+        User::class,
+        Role::class,
+        Permission::class,
+        Site::class,
+    ];
+
+    public function testAllBusinessEntitiesImplementBothInterfaces(): void
+    {
+        // Garde : chaque entree de la whitelist doit pointer sur une classe
+        // reelle. Empeche un FQCN errone de masquer silencieusement un oubli.
+        foreach (self::EXCLUDED as $excluded) {
+            self::assertTrue(class_exists($excluded), sprintf('Classe whitelistee inexistante : %s', $excluded));
+        }
+
+        $finder = new Finder()
+            ->files()
+            ->in(__DIR__.'/../../src/Module')
+            ->path('Domain/Entity')
+            ->name('*.php')
+        ;
+
+        // Garde : si le scan ne trouve rien, le chemin est casse — le test
+        // deviendrait un faux positif vert. On verifie qu'il a du grain a moudre.
+        self::assertNotEmpty(iterator_to_array($finder), 'Aucune entite scannee : chemin src/Module invalide ?');
+
+        foreach ($finder as $file) {
+            $fqcn = $this->extractFqcn($file->getRealPath());
+            if (null === $fqcn || in_array($fqcn, self::EXCLUDED, true)) {
+                continue;
+            }
+
+            $reflection = new ReflectionClass($fqcn);
+            // On ignore les classes abstraites et tout ce qui n'est pas une
+            // entite Doctrine (value objects, embeddables non mappes, etc.).
+            if ($reflection->isAbstract() || [] === $reflection->getAttributes(Entity::class)) {
+                continue;
+            }
+
+            self::assertTrue(
+                $reflection->implementsInterface(TimestampableInterface::class)
+                && $reflection->implementsInterface(BlamableInterface::class),
+                sprintf(
+                    'L\'entite %s doit implementer TimestampableInterface ET BlamableInterface '
+                    .'(utiliser TimestampableBlamableTrait). Si c\'est un referentiel statique '
+                    .'justifie, l\'ajouter dans EntitiesAreTimestampableBlamableTest::EXCLUDED.',
+                    $fqcn,
+                ),
+            );
+        }
+    }
+
+    /**
+     * Extrait le FQCN (namespace + classe) d'un fichier PHP par lecture du
+     * source, sans charger le fichier.
+     */
+    private function extractFqcn(string $path): ?string
+    {
+        $source = file_get_contents($path);
+        if (false === $source) {
+            return null;
+        }
+
+        if (
+            1 !== preg_match('/^namespace\s+([^;]+);/m', $source, $nsMatch)
+            || 1 !== preg_match('/^(?:final\s+|abstract\s+|readonly\s+)*class\s+(\w+)/m', $source, $classMatch)
+        ) {
+            return null;
+        }
+
+        return trim($nsMatch[1]).'\\'.$classMatch[1];
+    }
+}

tests/Shared/Infrastructure/Doctrine/TimestampableBlamableSubscriberTest.php

@@ -0,0 +1,159 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Shared\Infrastructure\Doctrine;
+
+use App\Shared\Domain\Contract\BlamableInterface;
+use App\Shared\Domain\Contract\TimestampableInterface;
+use App\Shared\Domain\Trait\TimestampableBlamableTrait;
+use App\Shared\Infrastructure\Doctrine\TimestampableBlamableSubscriber;
+use DateTimeImmutable;
+use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\Event\PrePersistEventArgs;
+use Doctrine\ORM\Event\PreUpdateEventArgs;
+use PHPUnit\Framework\TestCase;
+use Symfony\Bundle\SecurityBundle\Security;
+use Symfony\Component\Security\Core\User\UserInterface;
+
+/**
+ * Tests unitaires du TimestampableBlamableSubscriber.
+ *
+ * On exerce directement prePersist / preUpdate avec un EntityManager et une
+ * Security stubbes — aucun boot de kernel, aucun acces BDD. Les entites de test
+ * sont des fixtures internes (cf. bas de fichier).
+ *
+ * @internal
+ */
+final class TimestampableBlamableSubscriberTest extends TestCase
+{
+    public function testPrePersistWithUser(): void
+    {
+        $user       = $this->createStub(UserInterface::class);
+        $subscriber = new TimestampableBlamableSubscriber($this->securityReturning($user));
+        $entity     = new FullAuditableFixture();
+
+        $subscriber->prePersist($this->prePersistArgs($entity));
+
+        // Les 4 colonnes sont remplies : dates posees, blame = user courant.
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getCreatedAt());
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getUpdatedAt());
+        self::assertSame($entity->getCreatedAt(), $entity->getUpdatedAt());
+        self::assertSame($user, $entity->getCreatedBy());
+        self::assertSame($user, $entity->getUpdatedBy());
+    }
+
+    public function testPrePersistWithoutUser(): void
+    {
+        $subscriber = new TimestampableBlamableSubscriber($this->securityReturning(null));
+        $entity     = new FullAuditableFixture();
+
+        $subscriber->prePersist($this->prePersistArgs($entity));
+
+        // Hors contexte HTTP (CLI / cron) : dates remplies, blame laisse a null.
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getCreatedAt());
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getUpdatedAt());
+        self::assertNull($entity->getCreatedBy());
+        self::assertNull($entity->getUpdatedBy());
+    }
+
+    public function testPreUpdate(): void
+    {
+        $user       = $this->createStub(UserInterface::class);
+        $subscriber = new TimestampableBlamableSubscriber($this->securityReturning($user));
+
+        // On simule une entite deja persistee : createdAt fige dans le passe,
+        // createdBy positionne par une creation anterieure.
+        $createdAt = new DateTimeImmutable('2020-01-01 10:00:00');
+        $entity    = new FullAuditableFixture();
+        $entity->setCreatedAt($createdAt);
+        $entity->setUpdatedAt($createdAt);
+
+        $subscriber->preUpdate($this->preUpdateArgs($entity));
+
+        // updatedAt avance, createdAt reste fige, updatedBy = user courant.
+        self::assertSame($createdAt, $entity->getCreatedAt());
+        self::assertGreaterThan($createdAt, $entity->getUpdatedAt());
+        self::assertSame($user, $entity->getUpdatedBy());
+    }
+
+    public function testPartialEntityTimestampableOnly(): void
+    {
+        $user       = $this->createStub(UserInterface::class);
+        $subscriber = new TimestampableBlamableSubscriber($this->securityReturning($user));
+        $entity     = new TimestampableOnlyFixture();
+
+        // Entite Timestampable mais NON Blamable : seules les dates sont posees,
+        // aucun appel de blame (et aucune erreur).
+        $subscriber->prePersist($this->prePersistArgs($entity));
+
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getCreatedAt());
+        self::assertInstanceOf(DateTimeImmutable::class, $entity->getUpdatedAt());
+    }
+
+    /**
+     * Security stubbee renvoyant l'utilisateur fourni (ou null).
+     */
+    private function securityReturning(?UserInterface $user): Security
+    {
+        $security = $this->createStub(Security::class);
+        $security->method('getUser')->willReturn($user);
+
+        return $security;
+    }
+
+    private function prePersistArgs(object $entity): PrePersistEventArgs
+    {
+        return new PrePersistEventArgs($entity, $this->createStub(EntityManagerInterface::class));
+    }
+
+    private function preUpdateArgs(object $entity): PreUpdateEventArgs
+    {
+        $changeSet = [];
+
+        return new PreUpdateEventArgs($entity, $this->createStub(EntityManagerInterface::class), $changeSet);
+    }
+}
+
+/**
+ * Fixture interne : entite metier complete (Timestampable + Blamable) via le
+ * Trait reel teste.
+ *
+ * @internal
+ */
+final class FullAuditableFixture implements TimestampableInterface, BlamableInterface
+{
+    use TimestampableBlamableTrait;
+}
+
+/**
+ * Fixture interne : entite Timestampable seule (sans Blamable), pour verifier
+ * la dissociation des deux contrats par le Subscriber.
+ *
+ * @internal
+ */
+final class TimestampableOnlyFixture implements TimestampableInterface
+{
+    private ?DateTimeImmutable $createdAt = null;
+    private ?DateTimeImmutable $updatedAt = null;
+
+    public function getCreatedAt(): ?DateTimeImmutable
+    {
+        return $this->createdAt;
+    }
+
+    public function setCreatedAt(DateTimeImmutable $createdAt): void
+    {
+        $this->createdAt = $createdAt;
+    }
+
+    public function getUpdatedAt(): ?DateTimeImmutable
+    {
+        return $this->updatedAt;
+    }
+
+    public function setUpdatedAt(DateTimeImmutable $updatedAt): void
+    {
+        $this->updatedAt = $updatedAt;
+    }
+}