minor #30551 [Workflow] Deprecate MultipleStateMarkingStore and Singl…

…eStateMarkingStore in favor of MethodMarkingStore (lyrixx)

This PR was merged into the 4.3-dev branch.

Discussion
----------

[Workflow] Deprecate MultipleStateMarkingStore and SingleStateMarkingStore in favor of MethodMarkingStore

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets |
| License       | MIT
| Doc PR        |

Commits
-------

4d58beb [Workflow] Deprecate MultipleStateMarkingStore and SingleStateMarkingStore in favor of MethodMarkingStore

UPGRADE-4.3.md

@@ -177,3 +177,46 @@ Workflow
        }
    }
    ```
+
+ * `MultipleStateMarkingStore` is deprecated. Use `MethodMarkingStore` instead.
+
+   Before:
+   ```yaml
+   framework:
+       workflows:
+           article:
+               marking_store:
+                   type: multiple
+   ```
+
+   After:
+   ```yaml
+   framework:
+       workflows:
+           article:
+               marking_store:
+                   type: method
+
+   ```
+
+ * `SingleStateMarkingStore` is deprecated. Use `MethodMarkingStore` instead.
+
+   Before:
+   ```yaml
+   framework:
+       workflows:
+           article:
+               marking_store:
+                   type: single
+   ```
+
+   After:
+   ```yaml
+   framework:
+       workflows:
+           article:
+               marking_store:
+                   type: method
+                   arguments:
+                       - true
+   ```

UPGRADE-5.0.md

@@ -369,6 +369,8 @@ Workflow
  * `ClassInstanceSupportStrategy` has been removed, use `InstanceOfSupportStrategy` instead.
  * `MarkingStoreInterface::setMarking()` has a third argument: `array $context = []`.
  * Removed support of `initial_place`. Use `initial_places` instead.
+ * `MultipleStateMarkingStore` has been removed.
+ * `SingleStateMarkingStore` has been removed.
 
 Yaml
 ----

src/Symfony/Bridge/Twig/Tests/Extension/WorkflowExtensionTest.php

@@ -14,6 +14,7 @@
 use PHPUnit\Framework\TestCase;
 use Symfony\Bridge\Twig\Extension\WorkflowExtension;
 use Symfony\Component\Workflow\Definition;
+use Symfony\Component\Workflow\MarkingStore\MethodMarkingStore;
 use Symfony\Component\Workflow\Metadata\InMemoryMetadataStore;
 use Symfony\Component\Workflow\Registry;
 use Symfony\Component\Workflow\SupportStrategy\ClassInstanceSupportStrategy;
@@ -49,30 +50,28 @@ protected function setUp()
             );
         }
         $definition = new Definition($places, $transitions, null, $metadataStore);
-        $workflow = new Workflow($definition);
+        $workflow = new Workflow($definition, new MethodMarkingStore());
 
         $registry = new Registry();
         $addWorkflow = method_exists($registry, 'addWorkflow') ? 'addWorkflow' : 'add';
         $supportStrategy = class_exists(InstanceOfSupportStrategy::class)
-            ? new InstanceOfSupportStrategy(\stdClass::class)
-            : new ClassInstanceSupportStrategy(\stdClass::class);
+            ? new InstanceOfSupportStrategy(Subject::class)
+            : new ClassInstanceSupportStrategy(Subject::class);
         $registry->$addWorkflow($workflow, $supportStrategy);
         $this->extension = new WorkflowExtension($registry);
     }
 
     public function testCanTransition()
     {
-        $subject = new \stdClass();
-        $subject->marking = [];
+        $subject = new Subject();
 
         $this->assertTrue($this->extension->canTransition($subject, 't1'));
         $this->assertFalse($this->extension->canTransition($subject, 't2'));
     }
 
     public function testGetEnabledTransitions()
     {
-        $subject = new \stdClass();
-        $subject->marking = [];
+        $subject = new Subject();
 
         $transitions = $this->extension->getEnabledTransitions($subject);
 
@@ -83,9 +82,7 @@ public function testGetEnabledTransitions()
 
     public function testHasMarkedPlace()
     {
-        $subject = new \stdClass();
-        $subject->marking = [];
-        $subject->marking = ['ordered' => 1, 'waiting_for_payment' => 1];
+        $subject = new Subject(['ordered' => 1, 'waiting_for_payment' => 1]);
 
         $this->assertTrue($this->extension->hasMarkedPlace($subject, 'ordered'));
         $this->assertTrue($this->extension->hasMarkedPlace($subject, 'waiting_for_payment'));
@@ -94,21 +91,18 @@ public function testHasMarkedPlace()
 
     public function testGetMarkedPlaces()
     {
-        $subject = new \stdClass();
-        $subject->marking = [];
-        $subject->marking = ['ordered' => 1, 'waiting_for_payment' => 1];
+        $subject = new Subject(['ordered' => 1, 'waiting_for_payment' => 1]);
 
         $this->assertSame(['ordered', 'waiting_for_payment'], $this->extension->getMarkedPlaces($subject));
-        $this->assertSame($subject->marking, $this->extension->getMarkedPlaces($subject, false));
+        $this->assertSame($subject->getMarking(), $this->extension->getMarkedPlaces($subject, false));
     }
 
     public function testGetMetadata()
     {
         if (!class_exists(InMemoryMetadataStore::class)) {
             $this->markTestSkipped('This test requires symfony/workflow:4.1.');
         }
-        $subject = new \stdClass();
-        $subject->marking = [];
+        $subject = new Subject();
 
         $this->assertSame('workflow title', $this->extension->getMetadata($subject, 'title'));
         $this->assertSame('ordered title', $this->extension->getMetadata($subject, 'title', 'orderer'));
@@ -117,3 +111,23 @@ public function testGetMetadata()
         $this->assertNull($this->extension->getMetadata($subject, 'not found', $this->t1));
     }
 }
+
+final class Subject
+{
+    private $marking;
+
+    public function __construct($marking = null)
+    {
+        $this->marking = $marking;
+    }
+
+    public function getMarking()
+    {
+        return $this->marking;
+    }
+
+    public function setMarking($marking)
+    {
+        $this->marking = $marking;
+    }
+}

src/Symfony/Bridge/Twig/composer.json

@@ -41,12 +41,13 @@
         "symfony/var-dumper": "~3.4|~4.0",
         "symfony/expression-language": "~3.4|~4.0",
         "symfony/web-link": "~3.4|~4.0",
-        "symfony/workflow": "~3.4|~4.0"
+        "symfony/workflow": "~4.3"
     },
     "conflict": {
         "symfony/console": "<3.4",
         "symfony/form": "<4.3",
-        "symfony/translation": "<4.2"
+        "symfony/translation": "<4.2",
+        "symfony/workflow": "<4.3"
     },
     "suggest": {
         "symfony/finder": "",

src/Symfony/Component/Workflow/CHANGELOG.md

@@ -4,7 +4,7 @@ CHANGELOG
 4.3.0
 -----
 
- * Trigger `entered` event for subject entering in the Workflow for the first time
+ * Trigger `entered` event for subject entering in the Workflow for the first time.
  * Added a context to `Workflow::apply()`. The `MethodMarkingStore` could be used to leverage this feature.
  * Add style to transitions by declaring metadata:
 
@@ -27,6 +27,8 @@ CHANGELOG
  * Dispatch `CompletedEvent` on `workflow.completed`
  * Dispatch `AnnounceEvent` on `workflow.announce`
  * Added support for many `initialPlaces`
+ * Deprecated the `MultipleStateMarkingStore` class, use the `MethodMarkingStore` instead.
+ * Deprecated the `SingleStateMarkingStore` class, use the `MethodMarkingStore` instead.
 
 4.1.0
 -----

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

@@ -19,6 +19,12 @@
  *
  * This store deals with a "single state" or "multiple state" Marking.
  *
+ * "single state" Marking means a subject can be in one and only one state at
+ * the same time. Use it with state machine or specific workflow.
+ *
+ * "multiple state" Marking means a subject can be in many states at the same
+ * time. Use it with workflow.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 final class MethodMarkingStore implements MarkingStoreInterface

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

@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\Workflow\MarkingStore;
 
+@trigger_error(sprintf('"%s" is deprecated since Symfony 4.3, use "%s" instead.', MultipleStateMarkingStore::class, MethodMarkingStore::class), E_USER_DEPRECATED);
+
 use Symfony\Component\PropertyAccess\PropertyAccess;
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
 use Symfony\Component\Workflow\Marking;
@@ -22,6 +24,8 @@
  * This store deals with a "multiple state" Marking. It means a subject can be
  * in many states at the same time.
  *
+ * @deprecated since Symfony 4.3, use MethodMarkingStore instead.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 class MultipleStateMarkingStore implements MarkingStoreInterface

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

@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\Workflow\MarkingStore;
 
+@trigger_error(sprintf('"%s" is deprecated since Symfony 4.3, use "%s" instead.', SingleStateMarkingStore::class, MethodMarkingStore::class), E_USER_DEPRECATED);
+
 use Symfony\Component\PropertyAccess\PropertyAccess;
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
 use Symfony\Component\Workflow\Marking;
@@ -21,6 +23,8 @@
  * This store deals with a "single state" Marking. It means a subject can be in
  * one and only one state at the same time.
  *
+ * @deprecated since Symfony 4.3, use MethodMarkingStore instead.
+ *
  * @author Grégoire Pineau <lyrixx@lyrixx.info>
  */
 class SingleStateMarkingStore implements MarkingStoreInterface

src/Symfony/Component/Workflow/Tests/EventListener/AuditTrailListenerTest.php

@@ -6,7 +6,8 @@
 use Psr\Log\AbstractLogger;
 use Symfony\Component\EventDispatcher\EventDispatcher;
 use Symfony\Component\Workflow\EventListener\AuditTrailListener;
-use Symfony\Component\Workflow\MarkingStore\MultipleStateMarkingStore;
+use Symfony\Component\Workflow\MarkingStore\MethodMarkingStore;
+use Symfony\Component\Workflow\Tests\Subject;
 use Symfony\Component\Workflow\Tests\WorkflowBuilderTrait;
 use Symfony\Component\Workflow\Workflow;
 
@@ -18,22 +19,21 @@ public function testItWorks()
     {
         $definition = $this->createSimpleWorkflowDefinition();
 
-        $object = new \stdClass();
-        $object->marking = null;
+        $object = new Subject();
 
         $logger = new Logger();
 
         $ed = new EventDispatcher();
         $ed->addSubscriber(new AuditTrailListener($logger));
 
-        $workflow = new Workflow($definition, new MultipleStateMarkingStore(), $ed);
+        $workflow = new Workflow($definition, new MethodMarkingStore(), $ed);
 
         $workflow->apply($object, 't1');
 
         $expected = [
-            'Leaving "a" for subject of class "stdClass" in workflow "unnamed".',
-            'Transition "t1" for subject of class "stdClass" in workflow "unnamed".',
-            'Entering "b" for subject of class "stdClass" in workflow "unnamed".',
+            'Leaving "a" for subject of class "Symfony\Component\Workflow\Tests\Subject" in workflow "unnamed".',
+            'Transition "t1" for subject of class "Symfony\Component\Workflow\Tests\Subject" in workflow "unnamed".',
+            'Entering "b" for subject of class "Symfony\Component\Workflow\Tests\Subject" in workflow "unnamed".',
         ];
 
         $this->assertSame($expected, $logger->logs);

src/Symfony/Component/Workflow/Tests/EventListener/GuardListenerTest.php

@@ -13,6 +13,7 @@
 use Symfony\Component\Workflow\EventListener\GuardExpression;
 use Symfony\Component\Workflow\EventListener\GuardListener;
 use Symfony\Component\Workflow\Marking;
+use Symfony\Component\Workflow\Tests\Subject;
 use Symfony\Component\Workflow\Transition;
 use Symfony\Component\Workflow\WorkflowInterface;
 
@@ -130,13 +131,12 @@ public function testGuardExpressionBlocks()
 
     private function createEvent(Transition $transition = null)
     {
-        $subject = new \stdClass();
-        $subject->marking = new Marking();
+        $subject = new Subject();
         $transition = $transition ?: new Transition('name', 'from', 'to');
 
         $workflow = $this->getMockBuilder(WorkflowInterface::class)->getMock();
 
-        return new GuardEvent($subject, $subject->marking, $transition, $workflow);
+        return new GuardEvent($subject, new Marking($subject->getMarking() ?? []), $transition, $workflow);
     }
 
     private function configureAuthenticationChecker($isUsed, $granted = true)

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

@@ -5,6 +5,7 @@
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Workflow\Marking;
 use Symfony\Component\Workflow\MarkingStore\MethodMarkingStore;
+use Symfony\Component\Workflow\Tests\Subject;
 
 class MethodMarkingStoreTest extends TestCase
 {
@@ -52,23 +53,3 @@ public function testGetSetMarkingWithSingleState()
         $this->assertEquals($marking, $marking2);
     }
 }
-
-final class Subject
-{
-    private $marking;
-
-    public function __construct($marking = null)
-    {
-        $this->marking = $marking;
-    }
-
-    public function getMarking()
-    {
-        return $this->marking;
-    }
-
-    public function setMarking($marking)
-    {
-        $this->marking = $marking;
-    }
-}

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

@@ -6,6 +6,7 @@
 use Symfony\Component\Workflow\Marking;
 use Symfony\Component\Workflow\MarkingStore\MultipleStateMarkingStore;
 
+/** @group legacy*/
 class MultipleStateMarkingStoreTest extends TestCase
 {
     public function testGetSetMarking()

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

@@ -6,6 +6,7 @@
 use Symfony\Component\Workflow\Marking;
 use Symfony\Component\Workflow\MarkingStore\SingleStateMarkingStore;
 
+/** @group legacy*/
 class SingleStateMarkingStoreTest extends TestCase
 {
     public function testGetSetMarking()