feature symfony#19629 [Workflow] Make the Workflow support State Machines (Nyholm, lyrixx)

This PR was merged into the 3.2-dev branch.

Discussion
----------

[Workflow] Make the Workflow support State Machines

| Q | A |
| --- | --- |
| Branch? | "master" |
| Bug fix? | no |
| New feature? | yes |
| BC breaks? | yes, getEnabledTransistions does not return an assoc array. |
| Deprecations? | no |
| Tests pass? | yes |
| Fixed tickets | Fixes symfony#19605, Closes symfony#19607 |
| License | MIT |
| Doc PR | symfony/symfony-docs#6871 |

While researching for the docs of the component I've found that:
- A Workflow is a subclass of a Petri net
- A state machine is subclass of a Workflow
- A state machine must not be in many places simultaneously.

This PR adds a new interface to the marking store that allow us to validate the transition to true if ANY _input_ (froms) place matches the _tokens_ (marking). The default behavior is that ALL input places must match the tokens.

Commits
-------

9e49198 [Workflow] Made the code more robbust and ease on-boarding
bdd3f95 Make the Workflow support State Machines

Author: fabpot

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Compiler/ValidateWorkflowsPass.php

@@ -0,0 +1,77 @@
+<?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\Bundle\FrameworkBundle\DependencyInjection\Compiler;
+
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Exception\RuntimeException;
+use Symfony\Component\Workflow\Validator\DefinitionValidatorInterface;
+use Symfony\Component\Workflow\Validator\SinglePlaceWorkflowValidator;
+use Symfony\Component\Workflow\Validator\StateMachineValidator;
+use Symfony\Component\Workflow\Validator\WorkflowValidator;
+
+/**
+ * @author Tobias Nyholm <[email protected]>
+ */
+class ValidateWorkflowsPass implements CompilerPassInterface
+{
+    /**
+     * @var DefinitionValidatorInterface[]
+     */
+    private $validators = array();
+
+    public function process(ContainerBuilder $container)
+    {
+        $taggedServices = $container->findTaggedServiceIds('workflow.definition');
+        foreach ($taggedServices as $id => $tags) {
+            $definition = $container->get($id);
+            foreach ($tags as $tag) {
+                if (!array_key_exists('name', $tag)) {
+                    throw new RuntimeException(sprintf('The "name" for the tag "workflow.definition" of service "%s" must be set.', $id));
+                }
+                if (!array_key_exists('type', $tag)) {
+                    throw new RuntimeException(sprintf('The "type" for the tag "workflow.definition" of service "%s" must be set.', $id));
+                }
+                if (!array_key_exists('marking_store', $tag)) {
+                    throw new RuntimeException(sprintf('The "marking_store" for the tag "workflow.definition" of service "%s" must be set.', $id));
+                }
+
+                $this->getValidator($tag)->validate($definition, $tag['name']);
+            }
+        }
+    }
+
+    /**
+     * @param array $tag
+     *
+     * @return DefinitionValidatorInterface
+     */
+    private function getValidator($tag)
+    {
+        if ($tag['type'] === 'state_machine') {
+            $name = 'state_machine';
+            $class = StateMachineValidator::class;
+        } elseif ($tag['marking_store'] === 'scalar') {
+            $name = 'single_place';
+            $class = SinglePlaceWorkflowValidator::class;
+        } else {
+            $name = 'workflow';
+            $class = WorkflowValidator::class;
+        }
+
+        if (empty($this->validators[$name])) {
+            $this->validators[$name] = new $class();
+        }
+
+        return $this->validators[$name];
+    }
+}

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php

@@ -236,6 +236,10 @@ private function addWorkflowSection(ArrayNodeDefinition $rootNode)
                     ->useAttributeAsKey('name')
                     ->prototype('array')
                         ->children()
+                            ->enumNode('type')
+                                ->values(array('workflow', 'state_machine'))
+                                ->defaultValue('workflow')
+                            ->end()
                             ->arrayNode('marking_store')
                                 ->isRequired()
                                 ->children()

src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php

@@ -404,28 +404,48 @@ private function registerWorkflowConfiguration(array $workflows, ContainerBuilde
         $registryDefinition = $container->getDefinition('workflow.registry');
 
         foreach ($workflows as $name => $workflow) {
+            $type = $workflow['type'];
+
             $definitionDefinition = new Definition(Workflow\Definition::class);
             $definitionDefinition->addMethodCall('addPlaces', array($workflow['places']));
             foreach ($workflow['transitions'] as $transitionName => $transition) {
-                $definitionDefinition->addMethodCall('addTransition', array(new Definition(Workflow\Transition::class, array($transitionName, $transition['from'], $transition['to']))));
+                if ($type === 'workflow') {
+                    $definitionDefinition->addMethodCall('addTransition', array(new Definition(Workflow\Transition::class, array($transitionName, $transition['from'], $transition['to']))));
+                } elseif ($type === 'state_machine') {
+                    foreach ($transition['from'] as $from) {
+                        foreach ($transition['to'] as $to) {
+                            $definitionDefinition->addMethodCall('addTransition', array(new Definition(Workflow\Transition::class, array($transitionName, $from, $to))));
+                        }
+                    }
+                }
             }
 
             if (isset($workflow['marking_store']['type'])) {
                 $markingStoreDefinition = new DefinitionDecorator('workflow.marking_store.'.$workflow['marking_store']['type']);
                 foreach ($workflow['marking_store']['arguments'] as $argument) {
                     $markingStoreDefinition->addArgument($argument);
                 }
-            } else {
+            } elseif (isset($workflow['marking_store']['service'])) {
                 $markingStoreDefinition = new Reference($workflow['marking_store']['service']);
             }
 
-            $workflowDefinition = new DefinitionDecorator('workflow.abstract');
+            $definitionDefinition->addTag('workflow.definition', array(
+                'name' => $name,
+                'type' => $type,
+                'marking_store' => isset($workflow['marking_store']['type']) ? $workflow['marking_store']['type'] : null,
+            ));
+            $definitionDefinition->setPublic(false);
+
+            $workflowDefinition = new DefinitionDecorator(sprintf('%s.abstract', $type));
             $workflowDefinition->replaceArgument(0, $definitionDefinition);
-            $workflowDefinition->replaceArgument(1, $markingStoreDefinition);
+            if (isset($markingStoreDefinition)) {
+                $workflowDefinition->replaceArgument(1, $markingStoreDefinition);
+            }
             $workflowDefinition->replaceArgument(3, $name);
 
-            $workflowId = 'workflow.'.$name;
+            $workflowId = sprintf('%s.%s', $type, $name);
 
+            $container->setDefinition(sprintf('%s.definition', $workflowId), $definitionDefinition);
             $container->setDefinition($workflowId, $workflowDefinition);
 
             foreach ($workflow['supports'] as $supportedClass) {

src/Symfony/Bundle/FrameworkBundle/FrameworkBundle.php

@@ -35,6 +35,7 @@
 use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\SerializerPass;
 use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\UnusedTagsPass;
 use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\ConfigCachePass;
+use Symfony\Bundle\FrameworkBundle\DependencyInjection\Compiler\ValidateWorkflowsPass;
 use Symfony\Component\Debug\ErrorHandler;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\DependencyInjection\Compiler\PassConfig;
@@ -93,6 +94,7 @@ public function build(ContainerBuilder $container)
         $container->addCompilerPass(new PropertyInfoPass());
         $container->addCompilerPass(new ControllerArgumentValueResolverPass());
         $container->addCompilerPass(new CachePoolPass());
+        $container->addCompilerPass(new ValidateWorkflowsPass());
         $container->addCompilerPass(new CachePoolClearerPass(), PassConfig::TYPE_AFTER_REMOVING);
 
         if ($container->getParameter('kernel.debug')) {

src/Symfony/Bundle/FrameworkBundle/Resources/config/workflow.xml

@@ -7,7 +7,13 @@
     <services>
         <service id="workflow.abstract" class="Symfony\Component\Workflow\Workflow" abstract="true">
             <argument /> <!-- workflow definition -->
-            <argument /> <!-- marking store -->
+            <argument type="constant">null</argument> <!-- marking store -->
+            <argument type="service" id="event_dispatcher" on-invalid="ignore" />
+            <argument /> <!-- name -->
+        </service>
+        <service id="state_machine.abstract" class="Symfony\Component\Workflow\StateMachine" abstract="true">
+            <argument /> <!-- workflow definition -->
+            <argument type="constant">null</argument> <!-- marking store -->
             <argument type="service" id="event_dispatcher" on-invalid="ignore" />
             <argument /> <!-- name -->
         </service>

src/Symfony/Component/Workflow/Definition.php

@@ -46,6 +46,9 @@ public function getPlaces()
         return $this->places;
     }
 
+    /**
+     * @return Transition[]
+     */
     public function getTransitions()
     {
         return $this->transitions;
@@ -103,6 +106,6 @@ public function addTransition(Transition $transition)
             }
         }
 
-        $this->transitions[$name] = $transition;
+        $this->transitions[] = $transition;
     }
 }

src/Symfony/Component/Workflow/Dumper/GraphvizDumper.php

@@ -83,9 +83,10 @@ private function findTransitions(Definition $definition)
     {
         $transitions = array();
 
-        foreach ($definition->getTransitions() as $name => $transition) {
-            $transitions[$name] = array(
+        foreach ($definition->getTransitions() as $transition) {
+            $transitions[] = array(
                 'attributes' => array('shape' => 'box', 'regular' => true),
+                'name' => $transition->getName(),
             );
         }
 
@@ -111,10 +112,10 @@ private function addTransitions(array $transitions)
     {
         $code = '';
 
-        foreach ($transitions as $id => $place) {
+        foreach ($transitions as $place) {
             $code .= sprintf("  transition_%s [label=\"%s\", shape=box%s];\n",
-                $this->dotize($id),
-                $id,
+                $this->dotize($place['name']),
+                $place['name'],
                 $this->addAttributes($place['attributes'])
             );
         }

src/Symfony/Component/Workflow/Exception/InvalidDefinitionException.php

@@ -0,0 +1,21 @@
+<?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\Exception;
+
+/**
+ * Thrown by the DefinitionValidatorInterface when the definition is invalid.
+ *
+ * @author Tobias Nyholm <[email protected]>
+ */
+class InvalidDefinitionException extends \LogicException implements ExceptionInterface
+{
+}

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

@@ -20,7 +20,7 @@
  *
  * @author Grégoire Pineau <[email protected]>
  */
-class ScalarMarkingStore implements MarkingStoreInterface, UniqueTransitionOutputInterface
+class ScalarMarkingStore implements MarkingStoreInterface
 {
     private $property;
     private $propertyAccessor;