The 'initial_marking' option seems to be optional as the first defined place will be used as the initial marking if 'initial_marking' is not defined. It therefore only seems useful when the initial_marking differs from the first marking defined in places.

It is therefore also impossible to have a blank marking after interacting with the workflow, even if the initial_marking is not set as it will be set to the first state automatically.

On top of this, the 'entered' event is not dispatched when the object moves to its initial marking as there is no transition.

We found this out the hard way when using workflow->getMarking($object) on a newly instantiated object to set its initial place and subscribing to the 'entered' event on the initial place.

Eventually we solved this as follows:

appointment:
    type: state_machine
    audit_trail:
        enabled: true
    marking_store:
        type: 'method'
        property: 'marking'
    supports:
        - Appointment
    initial_marking: UNKNOWN
    places:
        - UNKNOWN
        - SCHEDULED
        - RESCHEDULED
    transitions:
        TO_SCHEDULED:
            from: UNKNOWN
            to: SCHEDULED
        TO_RESCHEDULE:
            from: 
                - SCHEDULED
                - RESCHEDULED
            to: RESCHEDULED



// new object with blank state
$appointment = new Appointment();
$workflow = $this->workflowRegistry->get($appointment);
// set the marking to the initial state and transition to the correct state
$workflow->apply($appointment, 'TO_SCHEDULED');


public static function getSubscribedEvents(): array
{
    return [
        'workflow.patient_appointment.entered.SCHEDULED' => 'appointmentScheduled',
        'workflow.patient_appointment.entered.RESCHEDULED' => 'appointmentRescheduled'
    ];
}

My recommendations on how to update the documentation:

• explicitly mention that 'initial_marking' is optional and that the first defined place will be used as the initial place by default.
• explicitly mention that when entering the initial place, there is no 'entered' event dispatched
• perhaps have an example of how the setup the states when the initial state should have an event.