Download the PHP package lexal/stepped-form without Composer

PHP Implementation of the Stepped Form

With this package you can create a Stepped Form and render or handle its steps.

Table of Contents

1. Requirements
2. Installation
3. Usage
   • Step
   • Form Builder
   • Form Data Storage
   • Entity Copy
4. License

Requirements

PHP: >=8.1

Installation

Via Composer

Usage

1. Create a Step.

2. Create a Form Builder.

3. Create a storage to save current form session key and have ability to split one form into different sessions depending on initial user input (e.g. customer id). Use default NullSessionKeyStorage when there is no need to split form sessions or there is no dependency on initial user input.

   Create a Storage to store steps data.

4. Create a Storage and data controllers.

5. Create an Event Dispatcher.

6. Create a Stepped Form.

7. Use Stepped Form in the application.

Step

Step can render any information to user with different types of input or just do calculations on backend depending on previous user input.

The first type of step must implement RenderStepInterface interface. Method getTemplateDefinition must return TemplateDefinition with template name to render and data to pass to template, e.g.:

The second type of step must implement StepInterface. Method handle can have business logic for calculating data and must return an updated form entity. Method will receive a null or previously submitted data as a second argument.

Form Builder

The Stepped Form uses a Form Builder for building a Steps collection by the form entity.

Stepped Form can have a fixed list of steps or dynamic one depending on the previous user input data.

Example of Stepped Form with fixed list of steps:

Example of Stepped Form with dynamic list of steps depending on previous user input:

Note: Step key must have only "A-z", "0-9", "-" and "_".

Form Data Storage

Stepped Form uses a storage to store current step key, handled steps data and a form session key. It's possible to create your own storage (e.g. session, database, redis) by implementing SessionKeyStorageInterface and StorageInterface interfaces.

Stepped Form uses NullSessionKeyStorage as SessionKeyStorageInterface by default, which means it always uses only one session key.

StepControlInterface and DataControlInterface help to work with current step key and step data respectively.

Dynamic stepped form triggers clearing all steps data after current one after handling it. Steps data are not cleared from the storage for static forms or when current step implements StepBehaviourInterface and method forgetDataAfterCurrent returns false.

Example of skipping data storage from being cleared after currently submitted step (for dynamic forms):

Form Events

The form can dispatch the following events:

1. BeforeHandleStep - is dispatched before handling the step. Event contains data passed to the handle method, form entity, and step instance. Event listener can update event data after some validation.
2. FormFinished - is dispatched when there is no next step after handling current one. Event contains a final form entity.

Form Exceptions

The form can throw the following exceptions:

1. AlreadyStartedException - when trying to start already started form.
2. EntityNotFoundException - when previous step entity not found for rendering or handling step.
3. EventDispatcherException - on dispatching events.
4. FormNotStartedException - when trying to render, handle or cancel not started form.
5. NoStepsAddedException - when trying to start form without steps.
6. StepHandleException - on handling step.
7. StepNotSubmittedException - when one of the previous step has not been submitted.
8. StepNotFoundException - when trying to render or handle not existed step.
9. StepNotRenderableException - when trying to render not renderable step.
10. ReadSessionKeyException - when can't get current session key.

License

Stepped Form is licensed under the MIT License. See LICENSE for the full license text.