[Workflow] Example on reacting to successful transitions #7416
Conversation
kix
force-pushed
the
document-workflow-events
branch
4 times, most recently
from
0635ccb to
4b94d3a
Compare
| * ``workflow.[workflow name].leave.[state name]``: a subject leaves a state. | ||
| * ``workflow.[workflow name].transition.[transition name]``: a transition is being applied. | ||
| * ``workflow.[workflow name].enter.[state name]``: a subject enters a state. | ||
| * ``workflow.[workflow name].announce.[transition name]``: a transition was applied to the subject. |
There was a problem hiding this comment.
Perhaps this deserves a note that a GuardEvent will be dispatched for guards instead of a base Workflow\Event.
| -------------------- | ||
|
|
||
| You can create Guard event listeners to block transitions (i.e. depending on the data in the blog | ||
| post). The following events are dispatched: |
There was a problem hiding this comment.
The events have already been listed in the previous section here. We could remove the list here, and add a note on GuardEvent instead.
| When a workflow subject's state is updated, the component dispatches several events that | ||
| enable you to alter the component's behaviour: | ||
|
|
||
| * ``workflow.[workflow name].guard.[transition name]``: dispatched before applying a transition. |
There was a problem hiding this comment.
Actually, this event is a bit special because it allows to "block" a transition with pure PHP code.
There was a problem hiding this comment.
I could reword this as:
workflow.[workflow name].guard.[transition name]: dispatched before applying a transition. Can be used to block transitions from listeners.
There was a problem hiding this comment.
I should only be use to block (or not). Not for something else ;) But as I'm not a native english speaker I can not tell what's the best way to say it.
There was a problem hiding this comment.
Not a native speaker as well, but let's maybe wait for @javiereguiluz's review? I guess he'll come up with something here :) Not quite sure about the best wording.
There was a problem hiding this comment.
Reworded as used to conditionally block a transition
| When a workflow subject's state is updated, the component dispatches several events that | ||
| enable you to alter the component's behaviour: | ||
|
|
||
| * ``workflow.[workflow name].guard.[transition name]``: dispatched before applying a transition. |
There was a problem hiding this comment.
Each time an "event" is dispatched, there are actually 3 events:
workflow.guardworkflow.[workflow name].guardworkflow.[workflow name].guard.[transition name]
cf https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Workflow/Workflow.php#L217-L219
The same comments applies to others event too.
There was a problem hiding this comment.
I know, but that's a thing that feels hard to explain if using the format given.
There was a problem hiding this comment.
Actually, I'm not sure what's the point of the generic workflow.guard/leave/transition etc. events. Logging of each and every update for all available workflows?
Same for events having a [workflow name] (e.g. workflow.blogpost.guard), the only use case I can see here is logging. Guarding every step in a workflow can only be useful for cases when the workflow can be started for a subject that's in an unacceptable state.
Hopefully, we can clarify this a bit?
| $message = \Swift_Message::newInstance('New blog post proposed'); | ||
| $message->setTo(['admin@acme.co' => 'Admin']); | ||
| $message->setBody('A post has been submitted to review'); | ||
| } |
There was a problem hiding this comment.
You forgot to really send the mail.
kix
force-pushed
the
document-workflow-events
branch
from
4b94d3a to
42428a4
Compare
| When a workflow subject's state is updated, the component dispatches several events that | ||
| enable you to alter the component's behaviour: | ||
|
|
||
| * ``workflow.[workflow name].guard.[transition name]``: used to conditionally block a transition. |
There was a problem hiding this comment.
I think we should reword these descriptions a bit. The essential thing to document about events is if they are notified before or after something happened (that's why it's recommended to name the events post_* and pre_*). For example, a transition is being applied could be: notified just before applying a transition
|
This is now documented, http://symfony.com/doc/current/workflow/usage.html. Shall we close? |
|
@xabbuh, looks good to me! Thanks! |
This PR broadens Workflow documentation, explaining which events are dispatched during workflow transitions. @lyrixx, can you clarify whether these events are a part of the component API? Reacting to a successful transition is a quite common scenario, IMHO.