Added docs for Workflow component

symfony · Nyholm · Aug 12, 2016 · Aug 12, 2016 · Aug 12, 2016 · Aug 12, 2016
commit d0701f04d48af12e0ce485609eab84bb4646e9a2
diff --git a/_images/workflow/blogpost.png b/_images/workflow/blogpost.png
diff --git a/_images/workflow/states_transactions.png b/_images/workflow/states_transactions.png
diff --git a/components/workflow.rst b/components/workflow.rst
@@ -21,4 +21,109 @@ You can install the component in 2 different ways:
 
 For more information, see the code in the Git Repository.
 
+Usage
+-----
+
+The workflow component gives you an object oriented way to work with state machines. A state machine lets you
+define *places* (or *states*) and *transactions*. A transaction describes the action to get from one place to another.
+
+.. image:: /_images/components/workflow/states_transactions.png
+
+A set of places and ``Transaction``s form a ``Definition``. A ``Workflow`` needs a ``Definition`` and a way to write
+the states to the objects, ie a ``MarkingStoreInterface``.
+
+Consider the following example for a blog post. A post can have places: 'draft', 'review', 'rejected', 'published'. You
+can define the workflow like this:
+
+    $states = ['draft', 'review', 'rejected', 'published'];
+    $transactions[] = new Transition('to_review', ['draft', 'rejected'], 'review');
+    $transactions[] = new Transition('publish', 'review', 'published');
+    $transactions[] = new Transition('reject', 'review', 'rejected');
+
+    $definition = new Definition($states, $transactions);
+    $definition->setInitialPlace('draft');
+
+    $marking = new ScalarMarkingStore('currentState');
+    $workflow = new Workflow($definition, $marking);
+
+The ``Workflow`` can now help you do decide what actions that are allowed on a blog post.
+
+
+    $post = new \stdClass();
+    $post->currentState = null;
+    $workflow->can($post, 'publish'); // False
+    $workflow->can($post, 'to_draft'); // True
+
+    // Update the currentState on the post
+    try {
+        $workflow->apply($post, 'to_review');
+    } catch (LogicException $e) {
+        // ...
+    }
+
+    // See all the available transaction for the post in the current state
+    $transactions = $workflow->getEnabledTransitions($post);
+
+
+
+Using events
+------------
+
+To make your workflows even more powerful you could construct the ``Workflow`` object with an ``EventDispatcher``. You
+can now create event listeners to block transactions ie depending on the data in the blog post. The following events
+are dispatched:
+
+* workflow.guard
+* workflow.[workflow name].guard
+* workflow.[workflow name].guard.[transaction name]
+
+See example to make sure no blog post without title is moved to "review"::
+
+    class BlogPostReviewListener implements EventSubscriberInterface
+    {
+        public function guardReview(GuardEvent $event)
+        {
+            $post = $event->getSubject();
+            $title = $post->getTitle();
+
+            if (empty($title)) {
+                // Posts with no title should not be allowed
+                $event->setBlocked(true);
+            }
+        }
+
+        public static function getSubscribedEvents()
+        {
+            return array(
+                'workflow.blogpost.guad.to_review' => array('guardReview'),
+            );
+        }
+    }
+
+With help from the ``EventDispatcher`` and the ``AuditTrailListener`` you could easily enable logging::
+
+    $logger = new PSR3Logger()
+    $subscriber = new AuditTrailListener($logger);
+    $dispatcher->addSubscriber($subscriber);
+
+Dumper
+------
+
+To help you debug you could dump a representation of your workflow with the use of a ``DumperInterface``. Use the
+``GraphvizDumper`` to create a PNG image of the workflow defined above::
+
+    // dump-graph.php
+    $dumper = new GraphvizDumper();
+    echo $dumper->dump($definition);
+
+.. code-block:: bash
+
+    $ php dump-graph-php > out.dot
+    $ dot -Tpng out.dot -o graph.png
+
+The result will look like this:
+
+.. image:: /_images/components/workflow/blogpost.png
+
+
 .. _Packagist: https://packagist.org/packages/symfony/workflow