8000 [Workflow] improve Workflow component documentation by noniagriconomie · Pull Request #11835 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

[Workflow] improve Workflow component documentation #11835

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 18, 2019
Merged

[Workflow] improve Workflow component documentation #11835

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 21 additions & 19 deletions components/workflow.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,28 +32,30 @@ 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 post can have one of a number
of predefined statuses (`draft`, `review`, `rejected`, `published`). In a workflow,
of predefined statuses (`draft`, `reviewed`, `rejected`, `published`). In a workflow,
these statuses are called **places**. You can define the workflow like this::

8000
use Symfony\Component\Workflow\DefinitionBuilder;
use Symfony\Component\Workflow\MarkingStore\SingleStateMarkingStore;
use Symfony\Component\Workflow\MarkingStore\MethodMarkingStore;
use Symfony\Component\Workflow\Transition;
use Symfony\Component\Workflow\Workflow;

$definitionBuilder = new DefinitionBuilder();
$definition = $definitionBuilder->addPlaces(['draft', 'review', 'rejected', 'published'])
$definition = $definitionBuilder->addPlaces(['draft', 'reviewed', 'rejected', 'published'])
// Transitions are defined with a unique name, an origin place and a destination place
->addTransition(new Transition('to_review', 'draft', 'review'))
->addTransition(new Transition('publish', 'review', 'published'))
->addTransition(new Transition('reject', 'review', 'rejected'))
->addTransition(new Transition('to_review', 'draft', 'reviewed'))
->addTransition(new Transition('publish', 'reviewed', 'published'))
->addTransition(new Transition('reject', 'reviewed', 'rejected'))
->build()
;

$marking = new SingleStateMarkingStore('currentState');
$singleState = true; // true if the subject can be in only one state at a given time
$property = 'currentState' // subject property name where the state is stored
$marking = new MethodMarkingStore($singleState, $property);
$workflow = new Workflow($definition, $marking);

The ``Workflow`` can now help you to decide what actions are allowed
on a blog post depending on what *place* it is in. This will keep your domain
The ``Workflow`` can now help you to decide what *transitions* (actions) are allowed
on a blog post depending on what *place* (state) it is in. This will keep your domain
logic in one place and not spread all over your application.

When you define multiple workflows you should consider using a ``Registry``,
Expand All @@ -66,11 +68,11 @@ are trying to use it with::
use Symfony\Component\Workflow\Registry;
use Symfony\Component\Workflow\SupportStrategy\InstanceOfSupportStrategy;

$blogWorkflow = ...
$blogPostWorkflow = ...
$newsletterWorkflow = ...

$registry = new Registry();
$registry->addWorkflow($blogWorkflow, new InstanceOfSupportStrategy(BlogPost::class));
$registry->addWorkflow($blogPostWorkflow, new InstanceOfSupportStrategy(BlogPost::class));
$registry->addWorkflow($newsletterWorkflow, new InstanceOfSupportStrategy(Newsletter::class));

Usage
Expand All @@ -80,17 +82,17 @@ When you have configured a ``Registry`` with your workflows,
you can retrieve a workflow from it and use it as follows::

// ...
// Consider that $post is in state "draft" by default
$post = new BlogPost();
$workflow = $registry->get($post);
// Consider that $blogPost is in place "draft" by default
$blogPost = new BlogPost();
$workflow = $registry->get($blogPost);

$workflow->can($post, 'publish'); // False
$workflow->can($post, 'to_review'); // True
$workflow->can($blogPost, 'publish'); // False
$workflow->can($blogPost, 'to_review'); // True

$workflow->apply($post, 'to_review'); // $post is now in state "review"
$workflow->apply($blogPost, 'to_review'); // $blogPost is now in place "reviewed"

$workflow->can($post, 'publish'); // True
$workflow->getEnabledTransitions($post); // ['publish', 'reject']
$workflow->can($blogPost, 'publish'); // True
$workflow->getEnabledTransitions($blogPost); // $blogPost can perform transition "publish" or "reject"

Learn more
----------
Expand Down
0