Updated accoding to feedback

symfony · Nyholm · Aug 12, 2016 · Aug 12, 2016 · Aug 12, 2016 · Aug 12, 2016
commit c681283feb0af4fc0726c41beb64af4da7f86908
diff --git a/components/workflow.rst b/components/workflow.rst
@@ -80,8 +80,9 @@ are trying to use it with::
 Usage
 -----
 
-When you have configured a ``Registry`` with your workflows you may use it as follows::
+When you have configured a ``Registry`` with your workflows, you may use it as follows::
 
+    // ...
     $post = new BlogPost();
     $workflow = $registry->get($post);
 
@@ -92,15 +93,13 @@ When you have configured a ``Registry`` with your workflows you may use it as fo
     $workflow->can($post, 'publish'); // True
     $workflow->getEnabledTransitions($post); // ['publish', 'reject']
 
-
 Learn more
 ----------
 
 .. toctree::
     :maxdepth: 1
     :glob:
 
-    /workflow
     /workflow/*
 
 .. _Packagist: https://packagist.org/packages/symfony/workflow
diff --git a/workflow.rst b/workflow.rst
@@ -6,19 +6,19 @@ of how a blog post goes from draft, review and publish. Another example is when
 a user submits a series of different forms to complete a task. Such processes are
 best kept away from your models and should be defined in configuration.
 
-A **definition** of a workflow consist of places and actions how to get from one
+A **definition** of a workflow consist of places and actions to get from one
 place to another. The actions are called **transistions**. A workflow does also
 need to know each object's position in the workflow. That **marking store** writes
-to a property of object to remember the current place.
+to a property of the object to remember the current place.
 
 .. note::
 
     The terminology above is commonly used when discussing workflows and
     `Petri nets`_
 
-The workflow component does also support state machines. A state machine is a subset
+The Workflow component does also support state machines. A state machine is a subset
 of a workflow and its purpose is to hold a state of your model. Read more about the
-differences and specific features of state machine in :doc:`/workflow/state-machines`
+differences and specific features of state machine in :doc:`/workflow/state-machines`.
 
 Examples
 --------
@@ -34,12 +34,12 @@ workflow below descirbes the process to fill in a job application.
 
 When you fill in a job application in this examplethere are 4 to 7 steps depending
 on the what job you are applying for. Some jobs requires personality test, logic tests
-and/or formal requirements to be answered by the user. Some jobs don't. We use the
-``GuardEvent`` to decide what next steps that are allowed for a specific application.
+and/or formal requirements to be answered by the user. Some jobs don't. The
+``GuardEvent`` is used to decide what next steps are allowed for a specific application.
 
-By defining a workflow like this we have an over view how the process looks like. We
-do not have any of the process logic in our controllers, models or view. We can change
-the order of the steps by changing configuration only.
+By defining a workflow like this, there is an overview how the process looks like. The process
+logic is not mixed with the controllers, models or view. The order of the steps can be changed
+by changing the configuration only.
 
 
 .. toctree::

diff --git a/workflow/dumping-workflows.rst b/workflow/dumping-workflows.rst
@@ -12,7 +12,7 @@ PNG image of the workflow defined above::
     $dumper = new GraphvizDumper();
     echo $dumper->dump($definition);
 
-.. code-block:: bash
+.. code-block:: terminal
 
     $ php dump-graph.php > out.dot
     $ dot -Tpng out.dot -o graph.png
@@ -21,10 +21,10 @@ The result will look like this:
 
 .. image:: /_images/components/workflow/blogpost.png
 
-If you have configured your workflow with the Symfony framwork you may dump the dot file
-with the ``WorkflowDumpCommand``.
+If you have configured your workflow with the Symfony framework, you may dump the dot file
+with the ``WorkflowDumpCommand``:
 
-.. code-block:: bash
+.. code-block:: terminal
 
     $ php bin/console workflow:dump name > out.dot
     $ dot -Tpng out.dot -o graph.png
@@ -34,5 +34,4 @@ with the ``WorkflowDumpCommand``.
     The ``dot`` command is a part of Graphviz. You can download it and read
     more about it on `Graphviz.org`_.
 
-
 .. _Graphviz.org: http://www.graphviz.org
diff --git a/workflow/state-machines.rst b/workflow/state-machines.rst
@@ -8,16 +8,17 @@ The workflow component is modelled after a *Workflow net* which is a subclass
 of a `Petri net`_. By adding further restrictions you can get a state machine.
 The most important one being that a state machine cannot be in more than
 one place simultaneously. It is also worth noting that a workflow does not
-commonly have cyclic path in the definition graph but it is common for a state
+commonly have cyclic path in the definition graph, but it is common for a state
 machine.
 
-Example of state machine
+Example of State Machine
 ------------------------
 
-Consider the states a GitHub pull request may have. We have an initial "start"
-state, a state for running tests on "travis", then we have the "review" state
-where we can require changes, reject or accept the pull request. At anytime we
-could also "update" the pull request which will result in another "travis" run.
+A pull request starts in an intial "start" state, a state for e.g. running
+tests on Travis. When this is finished, the pull request is in the "review"
+state, where contributors can require changes, reject or accept the
+pull request. At any time, you can also "update" the pull request, which
+will result in another Travis run.
 
 .. image:: /_images/components/workflow/pull_request.png
 
@@ -27,6 +28,7 @@ Below is the configuration for the pull request state machine.
 
     .. code-block:: yaml
 
+        # app/config/config.yml
         framework:
             workflows:
                 pull_request:
@@ -65,6 +67,78 @@ Below is the configuration for the pull request state machine.
                             from: closed
                             to: review
 
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="utf-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
+        >
+
+            <framework:config>
+                <framework:workflow name="pull_request" type="state_machine">
+                    <framework:marking-store type="scalar"/>
+
+                    <framework:support>AppBundle\Entity\PullRequest</framework:support>
+
+                    <framework:place>start</framework:place>
+                    <framework:place>coding</framework:place>
+                    <framework:place>travis</framework:place>
+                    <framework:place>review</framework:place>
+                    <framework:place>merged</framework:place>
+                    <framework:place>closed</framework:place>
+
+                    <framework:transition name="submit">
+                        <framework:from>start</framework:from>
+
+                        <framework:to>travis</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="update">
+                        <framework:from>coding</framework:from>
+                        <framework:from>travis</framework:from>
+                        <framework:from>review</framework:from>
+
+                        <framework:to>travis</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="wait_for_review">
+                        <framework:from>travis</framework:from>
+
+                        <framework:to>review</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="change_needed">
+                        <framework:from>review</framework:from>
+
+                        <framework:to>coding</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="accepted">
+                        <framework:from>review</framework:from>
+
+                        <framework:to>merged</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="rejected">
+                        <framework:from>review</framework:from>
+
+                        <framework:to>closed</framework:to>
+                    </framework:transition>
+
+                    <framework:transition name="reopened">
+                        <framework:from>closed</framework:from>
+
+                        <framework:to>review</framework:to>
+                    </framework:transition>
+
+                </framework:workflow>
+
+            </framework:config>
+        </container>
 
 You can now use this state machine by getting the ``state_machine.pull_request`` service::
 

diff --git a/workflow/usage.rst b/workflow/usage.rst
@@ -4,7 +4,7 @@
 How to Use the Workflow
 =======================
 
-Using the workflow component will help you to keep your domain logic as
+Using the Workflow component will help you to keep your domain logic as
 configuration. Having domain logic in one place gives you a better overview
 and it is easier to maintain whenever the domain requirement changes since
 you do not have to edit all your controllers, twig templates and services.
@@ -32,7 +32,7 @@ like this:
                 blog_publishing:
                     type: 'workflow' # or 'state_machine'
                     marking_store:
-                        type: 'property_accessor' # or 'scalar' or 'state_machine'
+                        type: 'property_accessor' # or 'scalar'
                         arguments:
                             - 'currentPlace'
                     supports:
@@ -54,7 +54,7 @@ like this:
                             to:   rejected
 
 
-.. code-block: php
+.. code-block:: php
 
     class BlogPost
     {
@@ -69,10 +69,10 @@ like this:
     The marking store type could be "property_accessor" or "scalar".
     A scalar marking type does not support a model being on multiple places.
 
-With this workflow named ``blog_publishing`` you can get help to decide
+With this workflow named ``blog_publishing``, you can get help to decide
 what actions that are allowed on a blog post. ::
 
-    $post = new \BlogPost();
+    $post = new \AppBundle\Entity\BlogPost();
 
     $workflow = $this->container->get('workflow.blog_publishing');
     $workflow->can($post, 'publish'); // False
@@ -93,7 +93,7 @@ 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 transitions ie depending on the data in the blog post. The following
+block transitions (i.e. depending on the data in the blog post). The following
 events are dispatched:
 
 * ``workflow.guard``
@@ -102,6 +102,9 @@ events are dispatched:
 
 See example to make sure no blog post without title is moved to "review"::
 
+    use Symfony\Component\Workflow\Event\GuardEvent;
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
     class BlogPostReviewListener implements EventSubscriberInterface
     {
         public function guardReview(GuardEvent $event)
@@ -127,16 +130,18 @@ See example to make sure no blog post without title is moved to "review"::
 With help from the ``EventDispatcher`` and the ``AuditTrailListener`` you
 could easily enable logging::
 
-    $logger = new PSR3Logger();
+    use Symfony\Component\Workflow\EventListener\AuditTrailListener;
+
+    $logger = new AnyPsr3Logger();
     $subscriber = new AuditTrailListener($logger);
     $dispatcher->addSubscriber($subscriber);
 
 Usage in Twig
 -------------
 
 Using your workflow in your Twig templates reduces the need of domain logic
-in the view layer. Consider this example of the control panel for our blog's
-edit page. The links below will only be displayed when the action is allowed:
+in the view layer. Consider this example of the control panel of the blog.
+The links below will only be displayed when the action is allowed:
 
 .. code-block:: twig