isn't a Petri net instead ?

@mickaelandrieu a workflow is a subset of a petri net (and a state machine a subset of workflow). The component does not support all features necessary to implement a petri net

it's unclear to me right now, but it's not a problem in the docs: I just need to learn a little bit more about all of theses implementations ^^

Thank you @stof

The more I read this, the more I think we should rename - at least in docs - Workflow component to Workflow Engine component. Am I crazy ? /c @Nyholm

transitions to that describes ... -> transitions that describe ... ?

Missing closing parenthesis at the end of this line.

You should also the initial place with something like: If a definition has no explicit initial place, it uses the first place defined.

This -> A post can have places looks confusing to me because it uses workflow terminology without a more gentle introduction:

A post can have one of a number of predefined statuses (`draft`, `review`, `rejected`, `published`).
In a workflow, these statuses are called **places**.

Here I'd use workflow terminology:

// Transitions are defined with a unique name, an origin place and a destination place

what actions that are allowed -> what actions are allowed

It's not about domain logic, it's more about Workflow management logic, isn'it ?

I'd say instead "This will keep your Workflow logic in one place and not spread all over your applications.", what do you think ?

Interesting. I would always consider this the domain logic because the "workflow management logic" is a part of your domain.

The theory behind "Workflow management" is to put the Workflow management outside of your domain, if I've well understood. BlogPost entity shouldn't be modified every time the rules of publishing evolve, for instance.

I'm pretty noob of this field, so correct me if I'm wrong :)

BlogPost entity shouldn't be modified every time the rules of publishing evolve, for instance.

Correct, you just edit the workflow when the rules of publishing changes.

The theory behind "Workflow management" is to put the Workflow management outside of your domain, if I've well understood.

Outside the domain or outside your model? The way I see it there is only three places you can put code/config:

• In the framework
• In your domain
• The glue between your domain and the framework.

Can @lyrixx give some input?

I'm not sure to understand the question / debate here.
Basically, the the data are stored in the model, and you can put the places / transitions everywhere you want. I don't have a rule of thumb for that. IMHO, Simple things are always better than perfect code.

If you write an issue with a summary of your thoughts with pros and cons, I'll be happy to submit a PR for that issue.

I can't do it, because the primary purpose of this Workflow component is not obvious for me:

It would be nice to describe the purpose of the component more.

The component is designed as very generic thing, so in theory it probably may have some interesting applications. However, provided examples don't impress. Compare it with rich domain model:

final class Article
{
    private $id;
    private $title;
    private $approvedByJournalist;
    private $approvedBySpellchecker;
    private $published;

    public static function postDraft(int $articleId, ArticleTitle $title): Article
    {
        $draft = new self();
        $draft->apply(new DraftArticleWasPosted($articleId, $title));
        $draft->apply(new ArticleWasSentForApproval($this->id));

        return $draft;
    }

    private function __construct() {}

    public function approveByJournalist()
    {
        if ($this->approvedByJournalist) {
            return;
        }

        $this->apply(new ArticleWasApprovedByJournalist($this->id));
        $this->publishIfItIsReady();
    }

    public function approveBySpellchecker() 
    {
        if ($this->approvedBySpellchecker) {
            return;
        }

        $this->apply(new ArticleWasApprovedBySpellchecker($this->id));
        $this->publishIfItIsReady();
    }

    public function changeTitle(ArticleTitle $newTitle)
    {
        if ($this->title->equals($newTitle)) {
            return;
        }

        $this->apply(new ArticleTitleWasChanged($this->id, $newTitle));
        $this->apply(new ArticleWasSentForApproval($this->id));
    }

    private function publishIfItIsReady()
    {
        if ($this->approvedByJournalist && $this->approvedBySpellchecker) {
            $this->apply(new ArticleWasPublished($this->id));
        }
    }

    // ...

    private function onArticleWasApprovedByJournalist(ArticleWasApprovedByJournalist $event)
    {
        $this->approvedByJournalist = true;
    }

    private function onArticleWasSentForApproval(ArticleWasSentForApproval $event)
    {
        $this->approvedByJournalist = false;
        $this->approvedBySpellchecker = false;
        $this->published = false;
    }

    private function onArticleTitleWasChanged(ArticleTitleWasChanged $event)
    {
        $this->title = $event->getNewTitle();
    }
}

We see use-cases (postDraft, approveBySpellchecker, approveBySpellchecker, changeTitle), events (ArticleWasApprovedByJournalist, ..., ArticleTitleWasChanged) and it's not hard to understand lifecycle of the Article from this code. We lose this expressiveness.

Further, that sample project checks permissions with GuardEvent hook:

public function onTransitionJournalist(GuardEvent $event)
    {
        if (!$this->checker->isGranted('ROLE_JOURNALIST')) {
            $event->setBlocked(true);
        }
    }

... and how you can solve it with commands:

final class ApproveArticleByJournalistHandler
{
    /**
     * @acl_role ROLE_JOURNALIST
     */
    public function handle(ApproveArticleByJournalist $command)
    {
        $blogPost = $this->blogPostRepository->find($command->getArticleId());
        $blogPost->approveByJournalist();
        $this->blogPostRepository->save($blogPost);
    }
}

And again we lose expressiveness by generic GuardEvent hook. It's harder to find it in the project, your have to search for string "workflow.article.guard.journalist_approval" instead of typing class name "ApproveArticleByJournalis...".

I would like to know if I'm wrong.

IMHO, all this debate is totally out of the scope of this PR.

How is it possible to write docs for the component without clear applications, examples?

I did not said that. But you you are telling us the Workflow component is useless and it's better to write code like your example. It's really a matter of taste (I have a strong opinion on that ; but I let people making their own choices). So I'm juste saying: The component is here, and it's useless to discuss if it's better to use CQRS / ES over Workflow Component.

For the record, the discussion is about the following sentence:

The workflow will keep your domain logic in one place and not spread all over your application

IMHO, it's more important to document how the component works.

I like the @Nyholm's work ; so let's focus on what matter.

@unkind: I hear you. Your arguments are valid.
@mickaelandrieu: Your arguments are also valid.

This is, as Grégoire says, out of scope for this PR. @unkind, I've asked you to create an issue on the symfony/symfony repository. I am happy to make a PR to try to improve the Workflow component regarding your input. Let's work together on this, but not in this PR.

When you start defining multiple workflows you should consider putting them
in a ``Registry``.

-->

When you define multiple workflows you should consider using a ``Registry``,
which is an object that stores and provides access to different workflows.

please prefix the example with // ... to indicate things are left out (but shown above).

// ...
$post = new BlogPost();

Please remove this one. It kinda makes sense, but it'll ruin Sphinx's global toctree afaics.

An other -> Another

Such process are -> Such processes are

what actions (transitions) that are allowed -> what actions (transitions) are allowed

two blank lines

To help you debug you could dump a ... -> To help you debug your workflows, you can dump a ...

We recently switched to "terminal" for terminal examples.

is part of

please remove the double empty line

"[...] definition graph, but it [...]"

please add # app/config/config.yml

Instead of this directive -> .. code-block:: php in Symfony Docs we prefer to remove it and add two colons (::) at the end of the line immediately above the PHP code.

Unless the previous paragraph didn't end with a colon (which is the case here).

Although reSt allows us to do the object ahd to be in **both** places. ::, we're always using the long .. code-block:: php in those cases.

@wouterj another reason to stop using this ugly :: hack. I wish we could get rid of it 😄

I don't think :: is ugly. It's just very smart. And we can get rid of it, but it would make things pretty verbose (e.g. replacing :: with : + .. code-block:: php)

These extra blank lines can be removed

multiple blank lines should always be just one

Workflow component

Missing closing parenthesis at the end of this line.

please add the file comment + XML and PHP here as well

Done. Thank you

Would be nice to have the configuration references as well. Is the initial state automatically guessed from the first place in the list ?

BTW, the type of marking store can not be state_machine (see here)

Thanks. Fixed now.

What about

arguments:
    - 'status' # The name of property that holds the marking in the object

- drafted # By default the initial state is the first place
- to_review

while renaming the transition 'submit' ?

typo: should be a double colon

"[...] named blog_publishing, you can [...]"

shouldn't this be \AppBundle\Entity\BlogPost ?

"block transitions (i.e. depending on the data in the blog post)."

missing use statements (for the GuardEvent, EventSubscriberInterface