feature symfony#60114 [Workflow] Add support for BackedEnum in MethodMarkingStore (tucksaun)

This PR was merged into the 7.4 branch.

Discussion
----------

[Workflow] Add support for `BackedEnum` in `MethodMarkingStore`

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | Kind of relates to symfony#44211
| License       | MIT

<details>
<summary>Why supporting Backed Enums in Workflow can be useful</summary>

Supporting Enums in Workflow (and overall in Symfony) is a highly debated topic. While using Enums is not always a good choice, I personally found that Backed Enums are really suited for status and places because they ensure type safety in your model and naturally validate the set of allowed values. This is why I think supporting them in Workflow could be nice if not too complicated.
</details>

<details>
<summary>Reducing the supported scope to `MethodMarkingStore`</summary>

While trying to implementing BackedEnum support in my current project using custom code, I figured we could go with a really narrow scope to support them out-of-the-box (but only for Single State Machine): in such case only `MethodMarkingStore` has to support Enums. In my mind, the way the workflow uses strings internally in the `Marking` is an implementation detail and what really matters to users is being able to control the values stored in their objects. Also, I don’t believe supporting enums for transitions is necessary as they are mostly configuration and validating transitions is already part of the component’s job (and in such case I would recommend using constants anyway). </details>

Supporting BackedEnum currently requires some boilerplate in the user project (with dedicated getter and setter  for instance) or a complete implementation of a marking store. Therefore, I’m sharing what is in my mind a small patch that can greatly improve the situation for users, as it allows them to use Backed Enums in their model right away with their method or properties:
```php
class MyObject {
    // ...
    private ObjectStatus $status = ObjectStatus::Draft;

    public function getStatus(): ObjectStatus
    {
        return $this->status;
    }

    public function setStatus(ObjectStatus $status): static
    {
        $this->status = $status;

        return $this;
    }
}
```

Commits
-------

bde1977 [Workflow] Add support for `BackedEnum` in `MethodMarkingStore`

Author: nicolas-grekas

src/Symfony/Component/Workflow/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.4
+---
+
+ * Add support for `BackedEnum` in `MethodMarkingStore`
+
 7.3
 ---
 

src/Symfony/Component/Workflow/MarkingStore/MethodMarkingStore.php

@@ -37,21 +37,21 @@ final class MethodMarkingStore implements MarkingStoreInterface
     private array $setters = [];
 
     /**
-     * @param string $property Used to determine methods or property to call
-     *                         The `getMarking` method will use `$subject->getProperty()` or `$subject->property`
-     *                         The `setMarking` method will use `$subject->setProperty(string|array $places, array $context = [])` or `$subject->property = string|array $places`
+     * @param string $property Used to determine the accessor methods or the property to call
+     *                         `getMarking()` will use `$subject->getProperty()` or `$subject->$property`
+     *                         `setMarking()` will use `$subject->setProperty(string|array|\BackedEnum $places, array $context = [])` or `$subject->$property = string|array|\BackedEnum $places`
      */
     public function __construct(
-        private bool $singleState = false,
-        private string $property = 'marking',
+        private readonly bool $singleState = false,
+        private readonly string $property = 'marking',
     ) {
     }
 
     public function getMarking(object $subject): Marking
     {
         $marking = null;
         try {
-            $marking = ($this->getGetter($subject))();
+            $marking = ($this->getters[$subject::class] ??= $this->getGetter($subject))();
         } catch (\Error $e) {
             $unInitializedPropertyMessage = \sprintf('Typed property %s::$%s must not be accessed before initialization', get_debug_type($subject), $this->property);
             if ($e->getMessage() !== $unInitializedPropertyMessage) {
@@ -64,6 +64,10 @@ public function getMarking(object $subject): Marking
         }
 
         if ($this->singleState) {
+            if ($marking instanceof \BackedEnum) {
+                $marking = $marking->value;
+            }
+
             $marking = [(string) $marking => 1];
         } elseif (!\is_array($marking)) {
             throw new LogicException(\sprintf('The marking stored in "%s::$%s" is not an array and the Workflow\'s Marking store is instantiated with $singleState=false.', get_debug_type($subject), $this->property));
@@ -80,15 +84,15 @@ public function setMarking(object $subject, Marking $marking, array $context = [
             $marking = key($marking);
         }
 
-        ($this->getSetter($subject))($marking, $context);
+        ($this->setters[$subject::class] ??= $this->getSetter($subject))($marking, $context);
     }
 
     private function getGetter(object $subject): callable
     {
         $property = $this->property;
         $method = 'get'.ucfirst($property);
 
-        return match ($this->getters[$subject::class] ??= self::getType($subject, $property, $method)) {
+        return match (self::getType($subject, $property, $method)) {
             MarkingStoreMethod::METHOD => $subject->{$method}(...),
             MarkingStoreMethod::PROPERTY => static fn () => $subject->{$property},
         };
@@ -99,26 +103,34 @@ private function getSetter(object $subject): callable
         $property = $this->property;
         $method = 'set'.ucfirst($property);
 
-        return match ($this->setters[$subject::class] ??= self::getType($subject, $property, $method)) {
-            MarkingStoreMethod::METHOD => $subject->{$method}(...),
-            MarkingStoreMethod::PROPERTY => static fn ($marking) => $subject->{$property} = $marking,
+        return match (self::getType($subject, $property, $method, $type)) {
+            MarkingStoreMethod::METHOD => $type ? static fn ($marking, $context) => $subject->{$method}($type::from($marking), $context) : $subject->{$method}(...),
+            MarkingStoreMethod::PROPERTY => $type ? static fn ($marking) => $subject->{$property} = $type::from($marking) : static fn ($marking) => $subject->{$property} = $marking,
         };
     }
 
-    private static function getType(object $subject, string $property, string $method): MarkingStoreMethod
+    private static function getType(object $subject, string $property, string $method, ?string &$type = null): MarkingStoreMethod
     {
-        if (method_exists($subject, $method) && (new \ReflectionMethod($subject, $method))->isPublic()) {
-            return MarkingStoreMethod::METHOD;
-        }
-
         try {
-            if ((new \ReflectionProperty($subject, $property))->isPublic()) {
-                return MarkingStoreMethod::PROPERTY;
+            if (method_exists($subject, $method) && ($r = new \ReflectionMethod($subject, $method))->isPublic()) {
+                $type = 0 < $r->getNumberOfRequiredParameters() ? $r->getParameters()[0]->getType() : null;
+
+                return MarkingStoreMethod::METHOD;
             }
-        } catch (\ReflectionException) {
-        }
 
-        throw new LogicException(\sprintf('Cannot store marking: class "%s" should have either a public method named "%s()" or a public property named "$%s"; none found.', get_debug_type($subject), $method, $property));
+            try {
+                if (($r = new \ReflectionProperty($subject, $property))->isPublic()) {
+                    $type = $r->getType();
+
+                    return MarkingStoreMethod::PROPERTY;
+                }
+            } catch (\ReflectionException) {
+            }
+
+            throw new LogicException(\sprintf('Cannot store marking: class "%s" should have either a public method named "%s()" or a public property named "$%s"; none found.', get_debug_type($subject), $method, $property));
+        } finally {
+            $type = $type instanceof \ReflectionNamedType && is_subclass_of($type->getName(), \BackedEnum::class) ? $type->getName() : null;
+        }
     }
 }
 

src/Symfony/Component/Workflow/Tests/MarkingStore/MethodMarkingStoreTest.php

@@ -84,6 +84,24 @@ public function testGetMarkingWithValueObject()
         $this->assertSame('first_place', (string) $subject->getMarking());
     }
 
+    public function testGetMarkingWithBackedEnum()
+    {
+        $subject = new SubjectWithEnum(TestEnum::Foo);
+
+        $markingStore = new MethodMarkingStore(true);
+
+        $marking = $markingStore->getMarking($subject);
+
+        $this->assertCount(1, $marking->getPlaces());
+        $this->assertSame(['foo' => 1], $marking->getPlaces());
+
+        $marking->mark('bar');
+        $marking->unmark('foo');
+        $markingStore->setMarking($subject, $marking);
+
+        $this->assertSame(TestEnum::Bar, $subject->getMarking());
+    }
+
     public function testGetMarkingWithUninitializedProperty()
     {
         $subject = new SubjectWithType();

src/Symfony/Component/Workflow/Tests/MarkingStore/SubjectWithEnum.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Workflow\Tests\MarkingStore;
+
+class SubjectWithEnum
+{
+    public function __construct(
+        private ?TestEnum $marking = null,
+        private array $context = [],
+    ) {
+    }
+
+    public function getMarking(): ?TestEnum
+    {
+        return $this->marking;
+    }
+
+    public function setMarking(TestEnum $marking, array $context = []): void
+    {
+        $this->marking = $marking;
+        $this->context = $context;
+    }
+
+    public function getContext(): array
+    {
+        return $this->context;
+    }
+}

src/Symfony/Component/Workflow/Tests/MarkingStore/TestEnum.php

@@ -0,0 +1,18 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Workflow\Tests\MarkingStore;
+
+enum TestEnum: string
+{
+    case Foo = 'foo';
+    case Bar = 'bar';
+}