Nov 16, 2017 · Nov 14, 2017 · Nov 14, 2017 · Nov 15, 2017 · Nov 15, 2017 · Nov 16, 2017
diff --git a/workflow.rst b/workflow.rst
 logic is not mixed with the controllers, models or view. The order of the steps can be changed
 by changing the configuration only.

 Learn more
 ----------

 .. toctree::
   :maxdepth: 1
   :glob:

   workflow/*
   workflow/usage
   workflow/state-machines
   workflow/dumping-workflows

 .. _Petri nets: https://en.wikipedia.org/wiki/Petri_net
diff --git a/workflow/dumping-workflows.rst b/workflow/dumping-workflows.rst
 How to Dump Workflows
 =====================

 To help you debug your workflows, you can dump a representation of your workflow with
 the use of a ``DumperInterface``. Use the ``GraphvizDumper`` to create a
 To help you debug your workflows, you can dump a representation of your workflow
 withthe use of a ``DumperInterface``. Use the ``GraphvizDumper`` to create a
 PNG image of the workflow defined above::

    // dump-graph.php

 .. image:: /_images/components/workflow/blogpost.png

 If you have configured your workflow with theSymfonyframework, youmay dump the dot file
 with the ``WorkflowDumpCommand``:
 Inside aSymfonyapplication, youcan dump the dot file with the
 ``workflow:dump`` command:

 .. code-block:: terminal

diff --git a/workflow/state-machines.rst b/workflow/state-machines.rst

    .. code-block:: yaml

        #app/config/config.yml
        # config/packages/workflow.yaml
        framework:
            workflows:
                pull_request:

    .. code-block:: xml

        <!--app/config/config.xml -->
        <!-- config/packages/workflow.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"

    .. code-block:: php

        // app/config/config.php

        // # config/packages/workflow.php
        $container->loadFromExtension('framework', array(
            // ...
            'workflows' => array(
            ),
        ));

 You can now use this state machine by getting the ``state_machine.pull_request`` service::
 In a Symfony application using the
 :ref:`default services.yaml configuration <service-container-services-load-example>`,
 you can get this state machine by injecting the Workflow registry service::

    // ...
    use Symfony\Component\Workflow\Registry;

    class SomeService
    {
        private $workflows;

        public function __constructor(Registry $workflows)
        {
            $this->workflows = $workflows;
        }

        public function someMethod()
        {
            $stateMachine = $this->workflows->get('pull_request');
            // ...
        }

    $stateMachine = $this->container->get('state_machine.pull_request');
        // ...
    }

 .. _Petri net: https://en.wikipedia.org/wiki/Petri_net
diff --git a/workflow/usage.rst b/workflow/usage.rst
 .. index::
    single: Workflow; Usage

 How to Use the Workflow
 =======================
 How to Create and Use Workflows
 ===============================

 Before creating your first workflow, execute this command to install the
 :doc:`Workflow component </components/workflow>` in your application:

 .. code-block:: terminal

    $ composer require workflow

 A workflow is a process or a lifecycle that your objects go through. Each
 step or stage in the process is called a *place*. You do also define *transitions*
 a ``Definition`` and a way to write the states to the objects (i.e. an
 instance of a :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`.)

 Consider the following example for a blog post. A postcan have places:
 'draft', 'review', 'rejected', 'published'. You can define the workflow
 Consider the following example for a blog post thatcan have these places:
 ``draft``, ``review``, ``rejected``, ``published``. You can define the workflow
 like this:

 .. configuration-block::

    .. code-block:: yaml

        #app/config/config.yml
        # config/packages/workflow.yaml
        framework:
            workflows:
                blog_publishing:

    .. code-block:: xml

        <!--app/config/config.xml -->
        <!-- config/packages/workflow.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"

    .. code-block:: php

        //app/config/config.php
        // config/packages/workflow.php

        $container->loadFromExtension('framework', array(
            // ...

 .. tip::

    The ``type`` (default value ``single_state``) and ``arguments`` (default value ``marking``)
    attributes of the ``marking_store`` option are optional. If omitted, their default values
    will be used.
    The ``type`` (default value ``single_state``) and ``arguments`` (default
 value ``marking``)attributes of the ``marking_store`` option are optional.
 If omitted, their default valueswill be used.

 With this workflow named ``blog_publishing``, you can get help to decide
 what actions are allowed on a blog post::
 With this workflow named ``blog_publishing``, you can now decide what actions
 are allowed on a blog post. For example, inside a controller of an application
 using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
 you can get the workflow by injecting the Workflow registry service::

    $post = new \App\Entity\BlogPost();
    // ...
    use Symfony\Component\Workflow\Registry;
    use App\Entity\BlogPost;
    use Symfony\Bundle\FrameworkBundle\Controller\Controller;
    use Symfony\Component\Workflow\Exception\LogicException;

    $workflow = $this->container->get('workflow.blog_publishing');
    $workflow->can($post, 'publish'); // False
    $workflow->can($post, 'to_review'); // True
    class BlogController extends Controller
    {
        public function edit(Registry $workflows)
        {
            $post = new BlogPost();
            $workflow = $workflows->get($post);

    // Update the currentState on the post
    try {
        $workflow->apply($post, 'to_review');
    } catch (LogicException $e) {
        // ...
    }
            // if there are multiple workflows for the same class,
            // pass the workflow name as the second argument
            // $workflow = $workflows->get($post, 'blog_publishing');

    // See all the available transition for the post in the current state
    $transitions = $workflow->getEnabledTransitions($post);
            $workflow->can($post, 'publish'); // False
            $workflow->can($post, 'to_review'); // True

            // Update the currentState on the post
            try {
                $workflow->apply($post, 'to_review');
            } catch (LogicException $e) {
                // ... if the transition is not allowed
            }

            // See all the available transitions for the post in the current state
            $transitions = $workflow->getEnabledTransitions($post);
        }
    }

 Using Events
 ------------
    * ``workflow.[workflow name].announce``
    * ``workflow.[workflow name].announce.[transition name]``

 Here is an example how to enable logging for every time a the "blog_publishing" workflow leaves a place::
 Here is an example of how to enable logging for every time the ``blog_publishing``
 workflow leaves a place::

    use Psr\Log\LoggerInterface;
    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
Original file line number	Diff line number	Diff line change
Expand Up		@@ -41,10 +41,14 @@ By defining a workflow like this, there is an overview how the process looks lik
		logic is not mixed with the controllers, models or view. The order of the steps can be changed
		by changing the configuration only.

		Learn more
		----------

		.. toctree::
		:maxdepth: 1
		:glob:

		workflow/*
		workflow/usage
		workflow/state-machines
		workflow/dumping-workflows

		.. _Petri nets: https://en.wikipedia.org/wiki/Petri_net
Original file line number	Diff line number	Diff line change
Expand Up		@@ -4,8 +4,8 @@
		How to Dump Workflows
		=====================

		To help you debug your workflows, you can dump a representation of your workflow with
		the use of a ``DumperInterface``. Use the ``GraphvizDumper`` to create a
		To help you debug your workflows, you can dump a representation of your workflow
		withthe use of a ``DumperInterface``. Use the ``GraphvizDumper`` to create a
		PNG image of the workflow defined above::

		// dump-graph.php
Expand All		@@ -20,8 +20,8 @@ The result will look like this:

		.. image:: /_images/components/workflow/blogpost.png

		If you have configured your workflow with theSymfonyframework, youmay dump the dot file
		with the ``WorkflowDumpCommand``:
		Inside aSymfonyapplication, youcan dump the dot file with the
		``workflow:dump`` command:

		.. code-block:: terminal

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -28,7 +28,7 @@ Below is the configuration for the pull request state machine.

		.. code-block:: yaml

		#app/config/config.yml
		# config/packages/workflow.yaml
		framework:
		workflows:
		pull_request:
Expand DownExpand Up		@@ -67,7 +67,7 @@ Below is the configuration for the pull request state machine.

		.. code-block:: xml

		<!--app/config/config.xml -->
		<!-- config/packages/workflow.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"
Expand DownExpand Up		@@ -140,8 +140,7 @@ Below is the configuration for the pull request state machine.

		.. code-block:: php

		// app/config/config.php

		// # config/packages/workflow.php
		$container->loadFromExtension('framework', array(
		// ...
		'workflows' => array(
Expand DownExpand Up		@@ -190,8 +189,29 @@ Below is the configuration for the pull request state machine.
		),
		));

		You can now use this state machine by getting the ``state_machine.pull_request`` service::
		In a Symfony application using the
		:ref:`default services.yaml configuration <service-container-services-load-example>`,
		you can get this state machine by injecting the Workflow registry service::

		// ...
		use Symfony\Component\Workflow\Registry;

		class SomeService
		{
		private $workflows;

		public function __constructor(Registry $workflows)
		{
		$this->workflows = $workflows;
		}

		public function someMethod()
		{
		$stateMachine = $this->workflows->get('pull_request');
		// ...
		}

		$stateMachine = $this->container->get('state_machine.pull_request');
		// ...
		}

		.. _Petri net: https://en.wikipedia.org/wiki/Petri_net
Original file line number	Diff line number	Diff line change
		@@ -1,8 +1,15 @@
		.. index::
		single: Workflow; Usage

		How to Use the Workflow
		=======================
		How to Create and Use Workflows
		===============================

		Before creating your first workflow, execute this command to install the
		:doc:`Workflow component </components/workflow>` in your application:

		.. code-block:: terminal

		$ composer require workflow

		A workflow is a process or a lifecycle that your objects go through. Each
		step or stage in the process is called a place. You do also define transitions
Expand All		@@ -14,15 +21,15 @@ A set of places and transitions creates a definition. A workflow needs
		a ``Definition`` and a way to write the states to the objects (i.e. an
		instance of a :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`.)

		Consider the following example for a blog post. A postcan have places:
		'draft', 'review', 'rejected', 'published'. You can define the workflow
		Consider the following example for a blog post thatcan have these places:
		``draft``, ``review``, ``rejected``, ``published``. You can define the workflow
		like this:

		.. configuration-block::

		.. code-block:: yaml

		#app/config/config.yml
		# config/packages/workflow.yaml
		framework:
		workflows:
		blog_publishing:
Expand DownExpand Up		@@ -51,7 +58,7 @@ like this:

		.. code-block:: xml

		<!--app/config/config.xml -->
		<!-- config/packages/workflow.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"
Expand DownExpand Up		@@ -98,7 +105,7 @@ like this:

		.. code-block:: php

		//app/config/config.php
		// config/packages/workflow.php

		$container->loadFromExtension('framework', array(
		// ...
Expand DownExpand Up		@@ -152,28 +159,46 @@ like this:

		.. tip::

		The ``type`` (default value ``single_state``) and ``arguments`` (default value ``marking``)
		attributes of the ``marking_store`` option are optional. If omitted, their default values
		will be used.
		The ``type`` (default value ``single_state``) and ``arguments`` (default
		value ``marking``)attributes of the ``marking_store`` option are optional.
		If omitted, their default valueswill be used.

		With this workflow named ``blog_publishing``, you can get help to decide
		what actions are allowed on a blog post::
		With this workflow named ``blog_publishing``, you can now decide what actions
		are allowed on a blog post. For example, inside a controller of an application
		using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
		you can get the workflow by injecting the Workflow registry service::

		$post = new \App\Entity\BlogPost();
		// ...
		use Symfony\Component\Workflow\Registry;
		use App\Entity\BlogPost;
		use Symfony\Bundle\FrameworkBundle\Controller\Controller;
		use Symfony\Component\Workflow\Exception\LogicException;

		$workflow = $this->container->get('workflow.blog_publishing');
		$workflow->can($post, 'publish'); // False
		$workflow->can($post, 'to_review'); // True
		class BlogController extends Controller
		{
		public function edit(Registry $workflows)
		{
		$post = new BlogPost();
		$workflow = $workflows->get($post);

		// Update the currentState on the post
		try {
		$workflow->apply($post, 'to_review');
		} catch (LogicException $e) {
		// ...
		}
		// if there are multiple workflows for the same class,
		// pass the workflow name as the second argument
		// $workflow = $workflows->get($post, 'blog_publishing');

		// See all the available transition for the post in the current state
		$transitions = $workflow->getEnabledTransitions($post);
		$workflow->can($post, 'publish'); // False
		$workflow->can($post, 'to_review'); // True

		// Update the currentState on the post
		try {
		$workflow->apply($post, 'to_review');
		} catch (LogicException $e) {
		// ... if the transition is not allowed
		}

		// See all the available transitions for the post in the current state
		$transitions = $workflow->getEnabledTransitions($post);
		}
		}

		Using Events
		------------
Expand DownExpand Up		@@ -250,7 +275,8 @@ order:
		* ``workflow.[workflow name].announce``
		* ``workflow.[workflow name].announce.[transition name]``

		Here is an example how to enable logging for every time a the "blog_publishing" workflow leaves a place::
		Here is an example of how to enable logging for every time the ``blog_publishing``
		workflow leaves a place::

		use Psr\Log\LoggerInterface;
		use Symfony\Component\EventDispatcher\EventSubscriberInterface;
Expand Down