[Workflow] Add documentation for the Workflow Component

[lyrixx]

Hi!

symfony/symfony#11882 is finally merged.
So the next step is to document this component + the integration into the FrameworkBundle.

But I'm really not good enough to achieve this task BUT I'm 100% available for helping anyone with that.
I created this little app to show how it works in action and there is also this french presentation.

[Nyholm]

I can have a look at this at the beginning of August. If anyone is interested to start before that just write on this issue.

I will write a comment when I actually begin.

[Nyholm]

I've started on a PR now

[xabbuh]

#6871 is merged now. However, there is some late feedback we may want to talk about. That's why I decided not to close here.

[rmasclef]

Hi !

I noticed that there is no documentation about the the behavior of the workflow component when we do not set a marking_store.

When we take a look at @lyrixx demo (https://github.com/lyrixx/SFLive-Paris2016-Workflow), we can see that he do not set the type and the marking_store in his configuration. But there is a marking property in the supports object ...

Perhaps it will be good to add these default values in the doc ?

I noticed another thing concerning the behavior of the workflow component with the supports object:

If we take a look at this example:

config.yml

framework:
    workflows:
        request_for_operation:
            type: 'state_machine'
            marking_store:
                type: 'single_state'
                arguments:
                    - 'status'
            supports:
                - AppBundle\Entity\RequestForOperation
            places:
                - draft
                - pending_for_management
                - in_progress
                - finished
                - canceled
            transitions:
                save:
                    from: draft
                    to:   pending_for_management
                track:
                    from: pending_for_management
                    to:   in_progress
                close:
                    from: in_progress
                    to:   finished
                cancel:
                    from: [pending_for_management, in_progress]
                    to:   canceled

RequestForOperation.php

class RequestForOperation
{
    /**
     * @ORM\Column(name="status", type="string", nullable=true)
     */
    private $status;
    
    ...
}

The initial place seems to be draft.

On a RequestForOperation creation, is the status automatically set to draft ? or is this draft place not really "existing" (i.e status = null) ?

[lyrixx]

On a RequestForOperation creation, is the status automatically set to draft ? or is this draft place not really "existing" (i.e status = null) ?

If you do $r = new RequestForOperation the status will be null. You have to set it to draft yourself.
But if you don't, as soon as $r pass through the Workflow the value will be set to draft for your.

I.E: there is not magie in this component ;)

[rmasclef]

If you do $r = new RequestForOperation the status will be null. You have to set it to draft yourself.

Wouldn't it be silly to set the status to 'draft' in the RequestForOperation constructor ? (if I change the initial workflow place, I will need to change it also in the RequestForOperation object :(

But if you don't, as soon as $r pass through the Workflow the value will be set to draft for your.

So the question is : how do you manage to make $r pass through the workflow in order to set the status to draftas there is no transition to apply the draft place ?

[lyrixx]

Wouldn't it be silly to set the status to 'draft' in the RequestForOperation constructor ? (if I change the initial workflow place, I will need to change it also in the RequestForOperation object :(

No. You really do how you want.

So the question is : how do you manage to make $r pass through the workflow in order to set the status to draftas there is no transition to apply the draft place ?

If there is not transition you don't need the workflow...

Anyway, with Workflow::getMarking() for example. But it's not required at all.

[rmasclef]

If you take a look at the workflow config that I provided, you will see that there are transitions, but not for initial place (i.e draft) which is pretty much like your own example which starts with a draft place as initial place ...

If I take a look at your example, the Article::marking field has no default marking value, so I assume that an Article never has the draft marking value in the db. It goes from null to wait_for_journalist or wait_for_spellchecker (again, I'm talking about the db value).

[lyrixx]

@rmasclef in the GitHub repository we only discuss about Symfony bugs and new features. For this kind of questions about using Symfony, please use any of the support alternatives shown in http://symfony.com/support Thanks!

[rmasclef]

Sorry for that ... I will submit this question to the support as you suggested :)

[rmasclef]

Hi again,

I have take the time to give a closer look at the Workflow class and I noticed that there are much more events dispatched than the documentation talks about :) (By the way, I suggest you to launch a a little code-cs-fixer in order to have a much better documented code, but this is not the purpose of this discusion ...).

So I suggest to complete the documentation with the different available events.
The purpose would be to explain the user which events are triggered, when and what they can do with it.

At this time I have the following events:

• leave
• transition
• enter
• announce

I hope this can help you make a better documentation :D

[ihorsamusenko]

@lyrixx this is probably not an appropriate place for this discussion, but don't you think that event "enter" should go after setMarking?

The way it is:

$this->leave($subject, $transition, $marking);
$this->transition($subject, $transition, $marking);
$this->enter($subject, $transition, $marking);
$this->markingStore->setMarking($subject, $marking);

The way it seems to be more accurate:

$this->leave($subject, $transition, $marking);
$this->transition($subject, $transition, $marking);
$this->markingStore->setMarking($subject, $marking);
$this->enter($subject, $transition, $marking);

[lyrixx]

Hello @samusenkoiv

See this PR for the reason of this order.

[ihorsamusenko]

@lyrixx the PR is related to the announce event, which is triggered only in case there is some next transitions, but if there are not - the announce event will never be triggered.
What I talking about is enter event, in case the enter event goes after setMarking, you can listen to the enter event and do some actions right after the place was changed. Without it, it is impossible to make such a listener.
Doesn't it make sense?

[xabbuh]

@samusenkoiv As what you are talking about is not related to the documentation of the Workflow component please use the main Symfony repository to discuss possible code changes.

[javiereguiluz]

Closing it as fixed by #6871.