beastbytes/wizard

Multi-part form handler

v2.0.0 2023-09-03 21:30 UTC

Requires

• php: ^8.0
• httpsoft/http-message: ^1.0
• psr/event-dispatcher: ^1.0
• yiisoft/arrays: ^3.0
• yiisoft/data-response: ^2.0
• yiisoft/friendly-exception: ^1.0
• yiisoft/router-fastroute: ^3.0
• yiisoft/session: ^2.0
• yiisoft/yii-http: ^1.0

Requires (Dev)

• phpunit/phpunit: ^10.0
• roave/infection-static-analysis-plugin: ^1.0
• roave/security-advisories: dev-latest
• vimeo/psalm: ^5.0
• yiisoft/event-dispatcher: ^1.0
• yiisoft/test-support: ^3.0
• yiisoft/yii-view: ^6.0

BSD-3-Clause

• Chris Yates

• form
• wizard
• steps
• multi-part
• plot branching

README

Wizard to handle multi-step forms.

Features

• All forms submit to the same URL
• Next/Previous or Forward Only navigation
• Looping
  • repeat one or more steps on a form as many times as needed
• Plot Branching Navigation (PBN)
  • allows the form to decide which path to take depending on the user's response
• Step Timeout
  • steps can have a timeout to ensure a user responds within a given time
• Save/Restore
  • save partially completed forms; restore and continue from that point
• Event driven
  • write the handler functions and hook them up to events

For license information see the LICENSE file.

Installation

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist beastbytes/wizard

or add

"beastbytes/wizard": "^1.0"

to the require section of your composer.json.

Usage

For more explanation and examples see the Wiki.

Controller

Constructor

Inject the Wizard in the controller's constructor and initialise it.

public function __construct(
    // other constructor injections
    private WizardInterface $wizard
): void
{
    // other initialisation
    $this->wizard = $this // minimal wizard initialisation
        ->wizard
        ->withCompletedRoute(self::COMPLETED_ROUTE)
        ->withStepRoute(self::STEP_ROUTE)
        ->withSteps(['step_1', 'step_2', 'step_3', ..., 'step_n'])
    ;
}

Action

The controller action is very simple:

public function wizard(ServerRequestInterface $request): ResponseInterface
{
    return $this
        ->wizard
        ->step($request)
    ;
}

TIP: BeastBytes\Wizard\WizardTrait provides the wizard action.

Events

A number of events are raised as the wizard runs. All events can retrieve the wizard instance using

$this->getWizard();

BeforeWizard

Raised before the wizard processes any steps. The wizard can be prevented from running with

BeforeWizard::continue(false);

Step

Raised when processing a step. The event handler for this event does what actions normally do, i.e. rendering the view, and data validation and saving on form submission; this event is raised twice for each step.

1. The first time this event is raised the event handler is responsible for rendering the appropriate form in a view.
2. The second time the event handler is responsible for data validation and setting the data into the event.

Request

The event handler uses

$this
    ->getWizard()
    ->getRequest()
;

to determine the type (Method::GET or Method::POST) of request.

CurrentStep

The event handler uses

$this
    ->getWizard()
    ->getCurrentStep()
;

to determine the step being processed.

Saving Data

The event handler uses

$this->saveData($data);

to save data for the step.

TIP: Use the same for a repeated step; the wizard will correctly save data for all repeated steps.

Next Step

By default the wizard will move to the next step in the steps array, taking into account any active branches. The event handler can tell the wizard to go to an earlier step or repeat a step using

$this->setGoto($goto);

where $goto is one of:

• Wizard::DIRECTION_BACKWARD the wizard goes to the previous step
• Wizard::DIRECTION_FORWARD the wizard goes to the next step; default behaviour)
• Wizard::REPEAT the wizard repeats the current step; the event handler is responsible for determining how many times the step is repeated
• 'stepName' the wizard returns to the given step; the step must be an earlier step.

Branching

THe event handler is responsible for deciding which branches (if any) in the steps array to take; use

$this->branches($branches);

where $branches is a map: ['branchName' => BranchDirective] where BranchDirective is Wizard::BRANCH_DISABLED or Wizard::BRANCH_ENABLED.

AfterWizard

Raised after the wizard has finished. This event handler is responsible for retrieving data from the wizard and saving it to models.

Date is retrieved from the wizard using

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

to get the data for all steps, or

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

to get the data for a specific step.

StepExpired

Raised when processing a step has expired. If this event is raised, the step data will be stored in the Wizard.