Hi,

I decided to give the workflow component a try, and I have a couple of questions and suggestions.

I have started out with this workflow. I used to do these type of jobs with https://github.com/yohang/Finite, but the new component looks awesome :)

Events

https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Workflow/Workflow.php#L129

The marking store is updated only after the enter event has been fired. This is not convenient, since I can't flush the entity manager in the listener.
The announce event is for the next transition as I gather, so listening to that for a flush is not the way to go.
All in all, I have to add $em->flush() in my controller, outside my other logic related to that event to store the markings.

Could we add an entered event to the mix ? :)

Transition parameters

It would be useful to have the ability to pass parameters to transitions. In my past projects with https://github.com/yohang/Finite, parameters were a necessity sooner or later. I can't provide my exact use cases, but in the example above the start_shipping method could have a tracking_number parameter. I could of course set it in the controller, but then half of the transition logic will be in my listener, and half in the controller. eg

if ($workflow->can($order, 'start_shipping')) {
    $order->setTrackingNumber('ASD123');
    $workflow->apply($order, 'start_shipping');
    $em->flush()
}

public function onStartShipping(Event $event)
{
    /** @var Order $order */
    $order = $event->getSubject();

    $this->orderMailer->send(/* ... */) // The mail contains the tracking code
}

With finite, I used the OptionsResolver in my listeners to validate the passed options. In finite, we have also added a built in resolver. (This may be a bit of overkill, especially because of the yaml configuration.)

I would like to submit a PR enabling this:

if ($workflow->can($order, 'start_shipping')) {
    $workflow->apply($order, 'start_shipping', ['tracking_number' => 'ASD123']);
}

Would that be okay?

One workflow, or multiple state machines?

The example could be implemented with 2 state machines. (orderStatus, paymentStatus and guards to validate)

In the documentation I read this:

It is also worth noting that a workflow does not commonly have cyclic path in the definition graph, but it is common for a state machine.

Would you recommend using a multi state workflow if there are cyclic paths (about 4-5) in a project?

Thanks!