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 Session 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 NullSessionStorage when there is no need to split form sessions or there is no dependency on initial user input.

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 by calculating data and must return an updated form entity. Method will receive a null or previous renderable step 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 count of steps or different steps depending on 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 and handled steps data. The package has implementation of simple in-memory storage (ArrayStorage). To create your own storage (e.g. session, database, redis) implement StorageInterface interface.

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

Dynamic stepped form will trigger clearing all steps data after current one when handle step. 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 clearing after currently submitted step (for dynamic forms):

Entity Copy

The Stepped Form uses an Entity Copy for passing previous submitted entity copy to the step handle method and saving it to the storage.

The package already has SimpleEntityCopy implementation of EntityCopyInterface. But you have to implement __clone method to clone internal objects if you use objects as a form entity.

Alternative for the package SimpleEntityCopy is DeepClone.

Form Events

The form can dispatch the following events:

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

Form Exceptions

The form can dispatch 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. FormIsNotStartedException - 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. StepIsNotSubmittedException - when one of the previous step is not submitted.
8. StepNotFoundException - when trying to render or handle not existed step.
9. StepNotRenderableException - when trying to render not renderable step.

License

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