Wizard

Wizard is the class that manages multistep forms.

It should be injected into the controller or action.

Namespace	BeastBytes\Wizard

Public Constants

Name	Type	Value	Description
AUTO_ADVANCE	bool	true	Wizard will go to the first unprocessed step when going forward in the steps array
BRANCH_DISABLED	int	-1	Disable a branch
BRANCH_ENABLED	int	1	Enable a branch
DIRECTION_BACKWARD	int	-1	Go one step backward in the steps array to get the next step
DIRECTION_FORWARD	int	1	Go forward in the step array to get the next step
DIRECTION_REPEAT	int	0	Repeat the current step
DEFAULT_BRANCH	bool	true	Use the default (first) branch
FORWARD_ONLY	bool	true	Wizard only goes forward in the step array
STEP_PARAMETER	string	'step'	The step parameter in the route for the Wizard action

Methods

Name	Description
getCurrentStep()	Returns the name of the current step
getData()	Returns data for a step or all processed steps
getSteps()	Returns a list of steps that have been and are to be processed
pause()	Returns a string - serialision of the Wizard instance - that can be used with Wizard::resume()
resume()	Resumes a Wizard instance
reset()	Resets the Wizard instance
step()	Processes a Wizard step
withAutoAdvance()	Whether the Wizard moves to the first unprocessed step or the next step in the steps array
withDefaultBranch()	Whether the default (first) branch in a group is used by default or the group is skipped
withEvents()	Sets the events and their handlers for the Wizard instance
withForwardOnly()	Sets whether Wizard must move to the next valid step or can return to an earlier step
withSessionKey()	Sets the session key for the Wizard instance
withSteps()	Sets the steps for the Wizard
withStepParameter()	Sets the step parameter as defined in the Route
withStepTimeout()	Sets the step timeout in seconds

Method Details

getCurrentStep()

Returns the name of the current step.

See also:

Wizard::getSteps()

public function getCurrentStep(): string

Return	string	The name of the current step

getData()

Returns data for a step or all processed steps.

public function getData(?string $step = null): mixed

Parameter	Type	Default	Description
$step	?string	null	The name of the step

Return	mixed	Stored data for the specified step, or a map containing data for all processed steps indexed by step name

getSteps()

Returns a list of steps that have been and are to be processed.

The list may change as steps are processed due to Plot Branching.

See also:

Wizard::getCurrentStep()
Wizard::withSteps()

public function getSteps(): array

Return	array	List of steps

pause()

Returns a string - serialision of the Wizard instance - that can be used with Wizard::resume().

See also:

Wizard::resume()

public function pause(): string

Return	string	Serialised Wizard data

resume()

Resumes a Wizard instance.

See also:

Wizard::pause()

public function resume(string $data): void

Parameter	Type	Default	Description
$data	string	Required	The serialised Wizard data from Wizard::pause().

reset()

Resets the Wizard instance.

All Session and step data are cleared, and Wizard options set to default values.

public function reset(): void

step()

Processes a Wizard step.

public function step(ServerRequestInterface $request): ?ResponseInterface

Parameter	Type	Default	Description
$request	ServerRequestInterface	Required	The HTTP request

Return	ResponseInterface	The HTTP response

withAutoAdvance()

Whether the Wizard moves to the first unprocessed step or the next step in the steps array.

Given the steps array: ['step1', 'step2', 'step3', 'step4'], if 'step1', 'step2', and 'step3' have been processed, and the user has returned to 'step2'

If $autoAdvance === true the next step will be 'step4'.

If $autoAdvance === false the next step will be 'step3'.

public function withAutoAdvance(bool $autoAdvance): self

Parameter	Type	Default	Description
$autoAdvance	bool	true	Whether Wizard moves to the first unprocessed step or the next step true: The Wizard moves to the first unprocessed step in the steps array false: The Wizard moves to the next step in the steps array

Parameter

Type

Default

Description

$autoAdvance

bool

true

Whether Wizard moves to the first unprocessed step or the next step

true: The Wizard moves to the first unprocessed step in the steps array

false: The Wizard moves to the next step in the steps array

Return	Wizard (new instance)

withDefaultBranch()

Whether the default (first) branch in a group is used by default or the group is skipped.

public function withDefaultBranch(bool $defaultBranch): self

Parameter	Type	Default	Description
$defaultBranch	bool	true	Whether the default (first) branch in a group is used by default or the group is skipped true: The default (first) branch in a group is used false: The group is skipped

Parameter

Type

Default

Description

$defaultBranch

bool

true

Whether the default (first) branch in a group is used by default or the group is skipped

true: The default (first) branch in a group is used

false: The group is skipped

Return	Wizard (new instance)

withEvents()

Sets the events for the Wizard instance.

The AfterWizard and Step events must be defined.

The StepExpired event must be defined if a step timeout is set.

The BeforeWizard event is optional.

See also:

Wizard::resume()
Wizard::withStepTimeout()

public function withEvents(array $events): self

Parameter	Type	Default	Description
$events	non-empty-array[string, callable]	Required	Map of events for the Wizard instance. Keys are the event FQCN, values are callables defining the event handler.

Parameter

Type

Default

Description

$events

non-empty-array[string, callable]

Required

Map of events for the Wizard instance.

Keys are the event FQCN, values are callables defining the event handler.

Return	Wizard (new instance)

withForwardOnly()

Sets whether Wizard must move to the next valid step or can return to an earlier step.

public function withForwardOnly(bool $forwardOnly): self

Parameter	Type	Default	Description
$forwardOnly	bool	true	Whether Wizard must move to the next valid step or can return to an earlier step. true: Wizard must move to the next valid step false: Wizard can return to an earlier step

Parameter

Type

Default

Description

$forwardOnly

bool

true

Whether Wizard must move to the next valid step or can return to an earlier step.

true: Wizard must move to the next valid step

false: Wizard can return to an earlier step

Return	Wizard (new instance)

withSessionKey()

Sets the session key for the Wizard instance.

public function withSessionKey(string $sessionKey): self

Parameter	Type	Default	Description
$sessionKey	string	'__wizard'	Set the session key for the Wizard instance

Return	Wizard (new instance)

withSteps()

Sets the steps for the Wizard.

public function withSteps(array $steps): self

Parameter	Type	Default	Description
$steps	array	Required	The steps to process

Return	Wizard (new instance)

withStepParameter()

Sets the step parameter as defined in the Route.

The step parameter is replaced with the step name in the URI. It provides a visual representation in the URI of the Wizard's progress; it has no other purpose.

public function withStepParameter(string $stepParameter): self

Parameter	Type	Default	Description
$stepParameter	string	''	Name of the step parameter in route definition.

Return	Wizard (new instance)

withStepTimeout()

Sets the step timeout in seconds; 0 means no timeout.

If a step is not processed within the step timeout period a StepExpired event is raised.

If used, this method must be called before Wizard::withEvents()

See also:

Wizard::withEvents()

public function withStepTimeout(int $stepTimeout): self

Parameter	Type	Default	Description
$stepParameter	int	0	Step timeout in seconds

Return	Wizard (new instance)

Last modified: 27 January 2025