Dec 8, 2018 · Apr 7, 2019 · Apr 7, 2019 · Apr 7, 2019 · Apr 7, 2019 · Apr 7, 2019
diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst

 The generated documentation is available in the ``_build/html`` directory.

 .. tip::

    You can also use `Docker`_ that wraps all this for you!

 Frequently Asked Questions
 --------------------------

 .. _`pip installation`: https://pip.pypa.io/en/stable/installing/
 .. _`Sphinx`: http://sphinx-doc.org/
 .. _`Sphinx Extensions for PHP and Symfony`: https://github.com/fabpot/sphinx-php
 .. _`Docker`: https://github.com/symfony/symfony-docs#docker
diff --git a/workflow.rst b/workflow.rst

 A **definition** of a workflow consist of places and actions to get from one
 place to another. The actions are called **transitions**. A workflow does also
 need to know each object's position in the workflow. That **marking store** writes
 to a property of the object to remember the current place.
 need to know each position an object can be in the workflow. This is the goal of the
 **marking store** that reads from and writes to a property of the object, or somewhere else, the current **place(s)**
 to remember.

 .. note::

diff --git a/workflow/state-machines.rst b/workflow/state-machines.rst
        public function someMethod($subject)
        {
            $stateMachine = $this->workflows->get($subject, 'pull_request');
            $stateMachine->apply($subject, 'wait_for_review');
            // ...
        }

        // ...
    }

 Symfony also creates automatically for you a service for each workflow (:class:`Symfony\\Component\\Workflow\\Workflow`) or state machine (:class:`Symfony\\Component\\Workflow\\StateMachine`) you have defined in your configuration.
 This means that you can use respectively ``workflow.pull_request`` or ``state_machine.pull_request`` in your service definition to have directly the proper service::

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

    class SomeService
    {
        private $stateMachine;

        public function __construct(StateMachine $stateMachine)
        {
            $this->stateMachine = $stateMachine;
        }

        public function someMethod($subject)
        {
            $this->stateMachine->apply($subject, 'wait_for_review', [
                'log_comment' => 'My logging comment for the wait for review transition.',
            ]);
            // ...
        }

diff --git a/workflow/usage.rst b/workflow/usage.rst
                    audit_trail:
                        enabled: true
                    marking_store:
                        type: 'multiple_state' # or 'single_state'
                        type: 'multiple_state' # or 'single_state', 'method' ('method' was added in 4.3)
                        arguments:
                            - 'currentPlace'
                    supports:
                        'enabled' => true
                    ],
                    'marking_store' => [
                        'type' => 'multiple_state', // or 'single_state'
                        'type' => 'multiple_state', // or 'single_state', 'method' ('method' was added in 4.3)
                        'arguments' => ['currentPlace'],
                    ],
                    'supports' => ['App\Entity\BlogPost'],

 .. note::

    The marking store type could be "multiple_state"or "single_state".
    The marking store type could be "multiple_state", "single_state"or "method".
    A single state marking store does not support a model being on multiple places
    at the same time.

                // ... if the transition is not allowed
            }

            // Update the currentState on the post passing some contextual data
            // to the whole workflow process
            try {
                $workflow->apply($post, 'publish', [
                    'log_comment' => 'My logging comment for the publish transition.',
                ]);
            } catch (TransitionException $exception) {
                // ... if the transition is not allowed
            }

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

 .. versionadded:: 4.1

    The :class:`Symfony\\Component\\Workflow\\Exception\\TransitionException`
    class was introduced in Symfony 4.1.

 .. versionadded:: 4.1

    The :method:`Symfony\\Component\\Workflow\\Registry::all` method was
    introduced in Symfony 4.1.

 .. versionadded:: 4.3

    The :method:`Symfony\\Component\\Workflow\\Workflow::apply` has now a new parameter ``$context``
    that is passed to the :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`
    :method:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface::setMarking` method.

 An example of usage with the ``$context`` parameter can be when you need,
 in addition of marking your object in its new place, to contextualize this change.

 .. tip::

    Configure the ``type`` as ``method`` of the ``marking_store`` option to use this feature
    without implementing your own marking store.

 You can also use this ``$context`` in your own marking store implementation.
 A simple implementation example is when you want to store the place as integer instead of string in your object.

 Lets say your object has a status property, stored as an integer in your storage, and you want to log an optional
 comment any time the status changes::

    // your own implementation class, to define in the configuration "marking_store"

    class ObjectMarkingStore implements MarkingStoreInterface
    {
        public function getMarking($subject)
        {
            $subject->getStatus();
            // ...
            // return a marking
        }

        public function setMarking($subject, Marking $marking, array $context);
        {
            // ...
            $subject->setStatus($newStatus, $context['log_comment'] ?? null);
        }
    }

    // and in your Object class

    public function getStatus()
    {
        return $this->status;
    }

    public function setStatus(int $status, ?string $comment = null)
    {
        $this->status = $status;
        $this->addStatusLogRecord(new StatusLog($this, $comment));

        return $this;
    }

    // the StatusLog class can have a createdAt, a username,
    // the new status, and finally your optional comment retrieved from the workflow context.

 Using Events
 ------------
Original file line number	Diff line number	Diff line change
Expand Up		@@ -270,6 +270,10 @@ purposes following these steps:

		The generated documentation is available in the ``_build/html`` directory.

		.. tip::

		You can also use `Docker`_ that wraps all this for you!

		Frequently Asked Questions
		--------------------------

Expand DownExpand Up		@@ -332,3 +336,4 @@ definitely don't want you to waste your time!
		.. _`pip installation`: https://pip.pypa.io/en/stable/installing/
		.. _`Sphinx`: http://sphinx-doc.org/
		.. _`Sphinx Extensions for PHP and Symfony`: https://github.com/fabpot/sphinx-php
		.. _`Docker`: https://github.com/symfony/symfony-docs#docker
Original file line number	Diff line number	Diff line change
Expand Up		@@ -8,8 +8,9 @@ best kept away from your models and should be defined in configuration.

		A definition of a workflow consist of places and actions to get from one
		place to another. The actions are called transitions. A workflow does also
		need to know each object's position in the workflow. That marking store writes
		to a property of the object to remember the current place.
		need to know each position an object can be in the workflow. This is the goal of the
		marking store that reads from and writes to a property of the object, or somewhere else, the current place(s)
		to remember.

		.. note::

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -209,6 +209,33 @@ you can get this state machine by injecting the Workflow registry service::
		public function someMethod($subject)
		{
		$stateMachine = $this->workflows->get($subject, 'pull_request');
		$stateMachine->apply($subject, 'wait_for_review');
		// ...
		}

		// ...
		}

		Symfony also creates automatically for you a service for each workflow (:class:`Symfony\\Component\\Workflow\\Workflow`) or state machine (:class:`Symfony\\Component\\Workflow\\StateMachine`) you have defined in your configuration.
Copy link Contributor OskarStarkApr 7, 2019 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I would reword it: Symfony creates a service for you automatically.... Copy link Member xabbuhApr 7, 2019 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. see`e1e4efc` :) OskarStark reacted with laugh emoji Copy link Contributor OskarStarkApr 7, 2019 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Thanks
		This means that you can use respectively ``workflow.pull_request`` or ``state_machine.pull_request`` in your service definition to have directly the proper service::

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

		class SomeService
		{
		private $stateMachine;

		public function __construct(StateMachine $stateMachine)
		{
		$this->stateMachine = $stateMachine;
		}

		public function someMethod($subject)
		{
		$this->stateMachine->apply($subject, 'wait_for_review', [
		'log_comment' => 'My logging comment for the wait for review transition.',
		]);
		// ...
		}

Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -43,7 +43,7 @@ like this:
		audit_trail:
		enabled: true
		marking_store:
		type: 'multiple_state' # or 'single_state'
		type: 'multiple_state' # or 'single_state', 'method' ('method' was added in 4.3)
		arguments:
		- 'currentPlace'
		supports:
Expand DownExpand Up		@@ -127,7 +127,7 @@ like this:
		'enabled' => true
		],
		'marking_store' => [
		'type' => 'multiple_state', // or 'single_state'
		'type' => 'multiple_state', // or 'single_state', 'method' ('method' was added in 4.3)
		'arguments' => ['currentPlace'],
		],
		'supports' => ['App\Entity\BlogPost'],
Expand DownExpand Up		@@ -167,7 +167,7 @@ As configured, the following property is used by the marking store::

		.. note::

		The marking store type could be "multiple_state"or "single_state".
		The marking store type could be "multiple_state", "single_state"or "method".
		A single state marking store does not support a model being on multiple places
		at the same time.

Expand DownExpand Up		@@ -221,11 +221,87 @@ you can get the workflow by injecting the Workflow registry service::
		// ... if the transition is not allowed
		}

		// Update the currentState on the post passing some contextual data
		// to the whole workflow process
		try {
		$workflow->apply($post, 'publish', [
		'log_comment' => 'My logging comment for the publish transition.',
		]);
		} catch (TransitionException $exception) {
		// ... if the transition is not allowed
		}

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

		.. versionadded:: 4.1

		The :class:`Symfony\\Component\\Workflow\\Exception\\TransitionException`
Copy link Contributor OskarStarkApr 7, 2019 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Do we Need this versionadded ? @symfony/team-symfony-docs
		class was introduced in Symfony 4.1.

		.. versionadded:: 4.1

		The :method:`Symfony\\Component\\Workflow\\Registry::all` method was
Copy link Contributor OskarStarkApr 7, 2019 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Do we Need this versionadded ? @symfony/team-symfony-docs
		introduced in Symfony 4.1.

		.. versionadded:: 4.3

		The :method:`Symfony\\Component\\Workflow\\Workflow::apply` has now a new parameter ``$context``
		that is passed to the :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`
		:method:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface::setMarking` method.

		An example of usage with the ``$context`` parameter can be when you need,
		in addition of marking your object in its new place, to contextualize this change.

		.. tip::

		Configure the ``type`` as ``method`` of the ``marking_store`` option to use this feature
		without implementing your own marking store.

		You can also use this ``$context`` in your own marking store implementation.
		A simple implementation example is when you want to store the place as integer instead of string in your object.

		Lets say your object has a status property, stored as an integer in your storage, and you want to log an optional
		comment any time the status changes::

		// your own implementation class, to define in the configuration "marking_store"

		class ObjectMarkingStore implements MarkingStoreInterface
		{
		public function getMarking($subject)
		{
		$subject->getStatus();
		// ...
		// return a marking
		}

		public function setMarking($subject, Marking $marking, array $context);
		{
		// ...
		$subject->setStatus($newStatus, $context['log_comment'] ?? null);
		}
		}

		// and in your Object class

		public function getStatus()
		{
		return $this->status;
		}

		public function setStatus(int $status, ?string $comment = null)
		{
		$this->status = $status;
		$this->addStatusLogRecord(new StatusLog($this, $comment));

		return $this;
		}

		// the StatusLog class can have a createdAt, a username,
		// the new status, and finally your optional comment retrieved from the workflow context.

		Using Events
		------------

Expand Down