Attribute support, drop PHP<8.3 support

.github/workflows/main.yaml

@@ -8,7 +8,7 @@ jobs:
 
         strategy:
             matrix:
-                php-versions: ['7.3', '7.4', '8.0']
+                php-versions: ['8.3', '8.4']
         name: PHP ${{ matrix.php-versions }}
         steps:
             -   uses: actions/checkout@v2

composer.json

@@ -4,15 +4,15 @@
     "license":           "MIT",
     "minimum-stability": "stable",
     "require": {
-        "php":                              "^7.3||^8.0",
+        "php":                              "^8.3",
         "doctrine/orm":                     "^2.7.4",
-        "hostnet/entity-tracker-component": "^2.0.1"
+        "hostnet/entity-tracker-component": "^2.3.0"
     },
     "require-dev": {
         "hostnet/database-test-lib": "^2.0.2",
         "hostnet/phpcs-tool":        "^9.1.0",
         "phpunit/phpunit":           "^9.5.6",
-        "symfony/cache":             "^5.3"
+        "symfony/cache":             "^6.4|^7.4"
     },
     "autoload": {
         "psr-4": {

src/Attributes/Mutation.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * @copyright 2026-present Hostnet B.V.
+ */
+declare(strict_types=1);
+
+namespace Hostnet\Component\EntityMutation\Attributes;
+
+use Hostnet\Component\EntityTracker\Attributes\Tracked;
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+class Mutation extends Tracked
+{
+    public function __construct(
+        public string $strategy = self::STRATEGY_COPY_PREVIOUS,
+    ) {
+    }
+        /**
+         * The Previous values will be stored in the mutation table. This is the
+         * default strategy.
+         */
+    public const string STRATEGY_COPY_PREVIOUS = 'previous';
+
+    /**
+     * The current values will be stored in the mutation table. And the
+     * mutation will also be added on creation of the entity.
+     */
+    public const string STRATEGY_COPY_CURRENT = 'current';
+
+    /**
+     * Get the strategy for storing the mutation data.
+     *
+     * @return Mutation::STRATEGY_COPY_PREVIOUS|Mutation::STRATEGY_COPY_CURRENT
+     */
+    public function getStrategy(): string
+    {
+        if (!in_array($this->strategy, [self::STRATEGY_COPY_PREVIOUS, self::STRATEGY_COPY_CURRENT], true)) {
+            throw new \RuntimeException(
+                sprintf("Unknown strategy '%s' for class %s.", $this->strategy, get_class($this))
+            );
+        }
+
+        return $this->strategy;
+    }
+}

src/Listener/MutationListener.php

@@ -6,35 +6,34 @@
 
 namespace Hostnet\Component\EntityMutation\Listener;
 
-use Hostnet\Component\EntityMutation\Mutation;
+use Hostnet\Component\EntityMutation\Attributes\Mutation;
 use Hostnet\Component\EntityMutation\MutationAwareInterface;
 use Hostnet\Component\EntityMutation\Resolver\MutationResolverInterface;
 use Hostnet\Component\EntityTracker\Event\EntityChangedEvent;
+use Psr\Cache\CacheItemInterface;
+use Psr\Cache\CacheItemPoolInterface;
+use Symfony\Component\Cache\Adapter\ArrayAdapter;
 
 class MutationListener
 {
-    /**
-     * @var MutationResolverInterface
-     */
-    private $resolver;
-
     /**
      * @param MutationResolverInterface $resolver
      */
-    public function __construct(MutationResolverInterface $resolver)
-    {
-        $this->resolver = $resolver;
+    public function __construct(
+        private MutationResolverInterface $resolver,
+        private CacheItemPoolInterface $is_mutation_cache = new ArrayAdapter()
+    ) {
     }
 
     /**
      * @param EntityChangedEvent $event
      */
-    public function entityChanged(EntityChangedEvent $event)
+    public function entityChanged(EntityChangedEvent $event): void
     {
         $em     = $event->getEntityManager();
         $entity = $event->getCurrentEntity();
 
-        if (null === ($annotation = $this->resolver->getMutationAnnotation($em, $entity))) {
+        if (false === $strategy = $this->getMutationStrategy($em, $entity)) {
             return;
         }
 
@@ -44,8 +43,6 @@ public function entityChanged(EntityChangedEvent $event)
             return;
         }
 
-        $strategy = $annotation->getStrategy();
-
         if ($strategy === Mutation::STRATEGY_COPY_PREVIOUS && null === $event->getOriginalEntity()) {
             return;
         }
@@ -72,4 +69,32 @@ public function entityChanged(EntityChangedEvent $event)
             $entity->addMutation($mutation);
         }
     }
+
+    private function getMutationStrategy($em, $entity): false|string
+    {
+        $cache_key   = base64_encode('MUTATION-' . get_class($entity));
+        $cached_item = $this->is_mutation_cache->getItem($cache_key);
+
+        if ($cached_item->isHit()) {
+            return $cached_item->get();
+        }
+
+        if (null !== $attribute = $this->resolver->getMutationAttribute($em, $entity)) {
+            return $this->save($cached_item, $attribute->getStrategy());
+        }
+
+        if (null !== $annotation = $this->resolver->getMutationAnnotation($em, $entity)) {
+            return $this->save($cached_item, $annotation->getStrategy());
+        }
+
+        return $this->save($cached_item, false);
+    }
+
+    private function save(CacheItemInterface $item, false|string $value): false|string
+    {
+        $item->set($value);
+        $this->is_mutation_cache->save($item);
+
+        return $value;
+    }
 }

src/Mutation.php

@@ -11,21 +11,26 @@
 /**
  * @Annotation
  * @Target({"CLASS"})
+ *
+ * @deprecated Please use the attribute instead.
  */
 class Mutation extends Tracked
 {
     /**
      * The Previous values will be stored in the mutation table. This is the
      * default strategy.
      */
-    public const STRATEGY_COPY_PREVIOUS = 'previous';
+    public const string STRATEGY_COPY_PREVIOUS = 'previous';
 
     /**
      * The Previous values will be stored in the mutation table. And the
      * mutation will also be added on creation of the entity.
      */
-    public const STRATEGY_COPY_CURRENT = 'current';
+    public const string STRATEGY_COPY_CURRENT = 'current';
 
+    /**
+     * @deprecated Not supported by the attribute
+     */
     public $class = '';
 
     /**
@@ -37,6 +42,8 @@ class Mutation extends Tracked
      * Get the strategy for storing the mutation data.
      *
      * @return Mutation::STRATEGY_COPY_PREVIOUS|Mutation::STRATEGY_COPY_CURRENT
+     *
+     * @deprecated Please use the attribute instead.
      */
     public function getStrategy()
     {

src/MutationAwareInterface.php

@@ -6,6 +6,9 @@
 
 namespace Hostnet\Component\EntityMutation;
 
+/**
+ * TODO: add typehints on next BC break, removing doctrine/annotations
+ */
 interface MutationAwareInterface
 {
     /**

src/Resolver/MutationResolver.php

@@ -7,44 +7,43 @@
 namespace Hostnet\Component\EntityMutation\Resolver;
 
 use Doctrine\ORM\EntityManagerInterface;
-use Hostnet\Component\EntityMutation\Mutation;
-use Hostnet\Component\EntityTracker\Provider\EntityAnnotationMetadataProvider;
+use Hostnet\Component\EntityMutation\Attributes\Mutation;
+use Hostnet\Component\EntityMutation\Mutation as MutationAnnotation;
+use Hostnet\Component\EntityTracker\Provider\EntityMetadataProvider;
 
 class MutationResolver implements MutationResolverInterface
 {
     /**
      * @var string
      */
-    private $annotation = Mutation::class;
+    private $annotation = MutationAnnotation::class;
 
-    /**
-     * @var EntityAnnotationMetadataProvider
-     */
-    private $provider;
-
-    /**
-     * @param EntityAnnotationMetadataProvider $provider
-     */
-    public function __construct(EntityAnnotationMetadataProvider $provider)
+    public function __construct(private EntityMetadataProvider $provider)
     {
-        $this->provider = $provider;
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getMutationAnnotation(EntityManagerInterface $em, $entity)
+    public function getMutationAnnotation(EntityManagerInterface $em, $entity): ?MutationAnnotation
     {
         return $this->provider->getAnnotationFromEntity($em, $entity, $this->annotation);
     }
 
+    public function getMutationAttribute(EntityManagerInterface $em, $entity): ?Mutation
+    {
+        return $this->provider->getAttributeFromEntity(Mutation::class, $em, $entity);
+    }
+
     /**
      * {@inheritdoc}
      */
-    public function getMutationClassName(EntityManagerInterface $em, $entity)
+    public function getMutationClassName(EntityManagerInterface $em, $entity): string
     {
-        if (null === ($annotation = $this->getMutationAnnotation($em, $entity))) {
-            return null;
+        $annotation = $this->getMutationAnnotation($em, $entity);
+        // If $annotation is null, we must be using the attribute, otherwise this code would not get hit.
+        if (null === $annotation) {
+            return get_class($entity) . 'Mutation';
         }
 
         return !empty($annotation->class) ? $annotation->class : get_class($entity) . 'Mutation';
@@ -53,7 +52,7 @@ public function getMutationClassName(EntityManagerInterface $em, $entity)
     /**
      * {@inheritdoc}
      */
-    public function getMutatableFields(EntityManagerInterface $em, $entity)
+    public function getMutatableFields(EntityManagerInterface $em, $entity): array
     {
         $mutation_class = $this->getMutationClassName($em, $entity);
         $metadata       = $em->getClassMetadata(get_class($entity));

src/Resolver/MutationResolverInterface.php

@@ -7,28 +7,30 @@
 namespace Hostnet\Component\EntityMutation\Resolver;
 
 use Doctrine\ORM\EntityManagerInterface;
-use Hostnet\Component\EntityMutation\Mutation;
+use Hostnet\Component\EntityMutation\Attributes\Mutation;
+use Hostnet\Component\EntityMutation\Mutation as MutationAnnotation;
 
 interface MutationResolverInterface
 {
     /**
      * Return the mutation annotation
      *
-     * @return Mutation
+     *
+     * @deprecated Please use the attribute instead.
      */
-    public function getMutationAnnotation(EntityManagerInterface $em, $entity);
+    public function getMutationAnnotation(EntityManagerInterface $em, $entity): ?MutationAnnotation;
+
+    public function getMutationAttribute(EntityManagerInterface $em, $entity): ?Mutation;
 
     /**
      * Return the mutation class name
-     *
-     * @return string
      */
-    public function getMutationClassName(EntityManagerInterface $em, $entity);
+    public function getMutationClassName(EntityManagerInterface $em, $entity): string;
 
     /**
      * Return list of mutatable fields
      *
      * @return string[]
      */
-    public function getMutatableFields(EntityManagerInterface $em, $entity);
+    public function getMutatableFields(EntityManagerInterface $em, $entity): array;
 }

test/Attributes/MutationTest.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * @copyright 2014-present Hostnet B.V.
+ */
+declare(strict_types=1);
+
+namespace Hostnet\Component\EntityMutation\Attributes;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @covers \Hostnet\Component\EntityMutation\Attributes\Mutation
+ */
+class MutationTest extends TestCase
+{
+    public function testGetStrategy(): void
+    {
+        $mutation = new Mutation();
+        $this->assertEquals(Mutation::STRATEGY_COPY_PREVIOUS, $mutation->getStrategy());
+        $mutation->strategy = Mutation::STRATEGY_COPY_CURRENT;
+        $this->assertEquals(Mutation::STRATEGY_COPY_CURRENT, $mutation->getStrategy());
+    }
+
+    /**
+     * @dataProvider getStrategyExceptionProvider
+     * @param mixed $strategy
+     */
+    public function testGetStrategyException($strategy): void
+    {
+        $mutation           = new Mutation();
+        $mutation->strategy = $strategy;
+        $this->expectException(\RuntimeException::class);
+        $mutation->getStrategy();
+    }
+
+    public function getStrategyExceptionProvider(): iterable
+    {
+        return [
+            [''],
+            ['test'],
+            ['last'],
+            ['before'],
+        ];
+    }
+}