Using Wizard

Wizard is used in a Controller; it uses a single action that all steps use to render and submit forms, greatly simplifying routing - there is only one route for a Wizard.

    class MyController
    {
        private const WIZARD_STEPS = ['step_1', 'step_2', 'step_3'];

        public function wizard(
            ServerRequestInterface $request,
            WizardInterface $wizard
        ): ResponseInterface
        {
            return $wizard
                ->withEvents([
                    [$this, 'afterWizardHandler'],
                    [$this, 'stepHandler'],
                ])
                ->withForwardOnly(Wizard::FORWARD_ONLY)
                ->withSteps(self::WIZARD_STEPS)
                ->step($request)
            ;
        }

        public function afterWizardHandler(AfterWizard $event)
        {
            // Handle AfterWizard event
        }

        public function stepHandler(Step $event)
        {
            // Handle AfterWizard event
        }
    }
    

The above example does the following:

Declares the steps WIZARD_STEPS. There can be as many steps as needed and this array also defines branch options when Plot Branching Navigation (PBN) is used (more on PBN later).
Declares an action (the wizard() method in this example). Like any other action, it's route must be defined in the router.
The action sets the Wizard options, declares the events and their handlers, then calls Wizard::step() with the request.
Declares the AfterWizard and Step event handlers.

Required Settings

Events

public function withEvents(array $events)

Defines the event handlers for Wizard.

The array keys are the FQCN of the event, and the value is a callable to the event handler; see the example below.

                    [
                        AfterWizard::class => [$this, 'afterWizardEventHandler'],
                        BeforeWizard::class => [$this, 'beforeWizardEventHandler'],
                        Step::class => [$this, 'stepEventHandler'],
                        StepExpired::class => [$this, 'stepExpiredEventHandler'],
                    ]
                

The AfterWizard and Step event handlers must be given,
the StepExpired handler must be given if a step timeout has been specified,
the BeforeWizard handler is optional.

Steps

public function withSteps(array $steps)

The steps array.

At its simplest, the steps array is a list of steps for Wizard to process. Wizard supports Plot Branching Navigation, enabling Wizard to process different steps in the steps array depending on user input; in this case the steps array becomes a bit more complex.

Wizard Options

Auto Advance

public function withAutoAdvance(bool $autoAdvance)

Determines what the next step will be if the user has returned to an earlier step

true (default): The first unprocessed step.

false: The next step in the steps array.

Default Branch

public function withDefaultBranch(bool $defaultBranch)

Determines whether Wizard will process the default - first - branch in a branch group or a branch group is skipped unless a branch is specifically enabled.

true (default): The default - first - branch in a branch group is processed.

false: A branch group is skipped unless a branch is specifically enabled.

Forward Only

public function withForwardOnly(bool $forwardOnly)

Whether the user csn return to earlier steps.

true : Disallow returning to earlier steps. Repeating the current step is allowed.

false (default): Allow returning to earlier steps.

Session Key

public function withSessionKey(string $sessionKey)

Sets the session key for the Wizard instance; defailt "__wizard".

The session key only needs to be changed if the default key is used by something else.

Step Parameter

public function withStepParameter(string $stepParameter)

Sets the step parameter as defined in the Route; default "" (empty string)

Using the default, URLs will be of the form "https::example.com/wizard".

If the parameter is set, URLs include the step name: "https::example.com/wizard/step_1", "https::example.com/wizard/step_2", "https::example.com/wizard/step_3", etc.

Step Timeout

public function withStepTimeout(int $stepTimeout)

Sets a step timeout in seconds; default 0 (no timeout). If a step is not processed within the timeout period a StepExpired event is raised.

This option must be set before setting the event handlers.

Last modified: 27 January 2025