Events

A number of events are raised as the wizard runs:

• BeforeWizard - Raised before any steps are processed.
• Step - Raised at least twice for each step
• AfterWizard - Raised after all steps are completed
• StepExpired - Raised if a step has expired

The event handlers are usually methods in the controller using the wizard.

If the application uses more than one wizard, event handlers should ensure that they are the one to handle the event by checking the wizard id:

$wizardId = $event->getWizard()->getId();

All Wizard events implement the StoppableEventInterface, so if an event handler did handle the event it should stop propagation of the event:

$event->stopPropagation();

BeforeWizard

Raised before the wizard processes any steps. The event handler can prevent the wizard from running with

$event->stopWizard();

Step

Raised when processing a step. This event is raised at least twice for each step. In many ways the event handler for this event is like an action: the first time the event is raised the event handler should render the form for the step saving the response to the event, then for the second and subsequent times the event is raised the form has been submitted and the event handler validates the form and then either saves the submitted data to the event if validation passes or renders the form again if validation fails.

The event handler can determine which step the event is being raised for from the currentStep value:

$currentStep = $event->getWizard()->getCurrentStep();

One technique to keep things tidy and make step event handling more like actions is for the event handler to call methods for each individual step.

TIP: Use StepHandlerTrait in the controller; it both checks the Wizard ID and calls methods named for each step.

Methods that render then validate a step's form will look something like:

public function step1Handler(StepEvent $event): void
{
    $formModel = new Step1Form(); // Step1Form is the form model for step1

    if ($this->formHydrator->populateFromPostAndValidate($formModel, $event->getRequest())) {
        $data = $formModel->getData(); // typically an array of data fields <fieldName => fieldValue> 
        $event->setData($data);        
        return; // the wizard creates the response
    }

    $response = $this->viewRenderer->render('step1', ['formModel' => $formModel]);
    $event->setResponse($response); // set the response in the event, do not return it
}

TIP: See the examples for more complex usage: repeated steps, branching, etc.

AfterWizard

Raised after the wizard has finished. The event handler for this event is responsible for retrieving data from the wizard and acting on it, e.g. persisting to a database

Data is retrieved from the wizard using:

$event->getWizard()->getData();

If only the data for a specific step is required:

$event->getWizard()->getData('stepName');

The event handler must also render the view indication completion of the wizard and set the response in the event.

The event handler will look something like:

public function wizardCompletedHandler(StepEvent $event): void
{
    $data = $event->getWizard()->getData();
    
    // Save data to database
    // Raise any application events

    $response = $this->viewRenderer->render('wizardCompleted');
    $event->setResponse($response); // set the response in the event, do not return it
}

StepExpired

Raised when processing a step has expired. If this event is raised, the data for all processed steps - including the one that expired - will be stored in the Wizard. The event handler should as a minimum render a view and set the response in the event; it may also persist data.

The event handler will look something like:

public function stepExpiredHandler(StepEvent $event): void
{
    $data = $event->getWizard()->getData();
    $expiredStep = $event->getWizard()->getCurrentStep();
    
    // Do something with the data
    // Raise any application events

    $response = $this->viewRenderer->render('stepExpired', ['expiredStep' => $expiredStep]);
    $event->setResponse($response); // set the response in the event, do not return it
}