lexal/laravel-stepped-form

Stepped Form for Laravel & Lumen.

v2.0.0 2023-12-30 16:47 UTC

Requires

• php: >=8.1
• illuminate/contracts: ^9.0 || ^10.0
• illuminate/routing: ^9.0 || ^10.0
• illuminate/support: ^9.0 || ^10.0
• lexal/http-stepped-form: ^2.1

Requires (Dev)

• dealerdirect/phpcodesniffer-composer-installer: ^1.0.0
• illuminate/http: ^9.0 || ^10.0
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.5
• roave/security-advisories: dev-latest
• webimpress/coding-standard: ^1.3

Suggests

• illuminate/config: Required to use Laravel config (^9.0 || ^10.0).
• illuminate/events: Required to use Laravel Dispatcher as form Event Dispatcher (^9.0 || ^10.0).
• illuminate/session: Required to use Laravel Session as Stepped Form storage (^9.0 || ^10.0).
• illuminate/view: Required to render Laravel views (^9.0 || ^10.0).

MIT

• Alex Lex

• laravel
• lumen
• multi-step
• stepped-form
• multi-step form
• dynamic stepped-form

README

The package is based on the HTTP Stepped Form and built for the Laravel & Lumen framework.

Table of Contents

1. Requirements
2. Installation
3. Configuration
   • Publish the config
   • Available config options
4. Usage
5. License

Requirements

PHP: >=8.1

Laravel: ^9.0 || ^10.0

Installation

Via Composer

composer require lexal/laravel-stepped-form

Additional changes for Lumen framework

Add the following snippet to the bootstrap/app.php file under the providers section as follows:

$app->register(Lexal\LaravelSteppedForm\ServiceProvider\ServiceProvider::class);

(back to top)

Configuration

Publish the config

Run the following command to publish the package config file:

php artisan vendor:publish --provider="Lexal\LaravelSteppedForm\ServiceProvider\ServiceProvider"

Available config options

The configuration file config/stepped-form.php has the following options:

1. renderer - contains Renderer class, instance or service alias that will translate step's template definition to the response. Must implement RendererInterface;
2. redirector - contains Redirector class, instance or service alias that will redirect user between different steps. Must implement RedirectorInterface;
3. entity_copy - contains Entity Copy class, instance or service alias that will clone entity of the given step. Must implement EntityCopyInterface;
4. event_dispatcher - contains Event Dispatcher class, instance or service alias that will dispatch form events. Must implement EventDispatcherInterface;
5. exception_normalizers - contains exception normalizers that the form will use to normalize SteppedFormException into the Response instance. Read more about them in the HTTP Stepped Form docs;
6. forms - contains array of all application forms definitions. Form definition must have builder class for dynamic forms or array of steps for the static forms, settings class and storage where the form will store data.

(back to top)

Usage

1. Publish configuration file.

2. Replace with custom implementation of redirector, renderer and entity copy if necessary. Add custom exception normalizers if necessary.

3. Declare your form settings.

    use Lexal\HttpSteppedForm\Settings\FormSettingsInterface;                                                            
    use Lexal\SteppedForm\Step\StepKey;
    
    final class FormSettings implements FormSettingsInterface
    {
        public function getStepUrl(StepKey $key): string
        {
            // return step URL
        }
   
        public function getUrlBeforeStart(): string
        {
            // returns a URL to redirect to when there is no previously renderable step
        }
   
        public function getUrlAfterFinish(): string
        {
            // return a URL to redirect to when the form was finishing
        }
    }
   
    $formSettings = new FormSettings();

4. Add forms definitions.

   • Static form

     return [
        // ...
     
        'forms' => [
            'customer' => [
                'steps' => [
                    'customer' => CustomerStep::class,
                    'broker' => BrokerStep::class,
                    'confirmation' => ConfirmationStep::class,
                    // other steps
                ],
                'settings_class' => FormSettings::class,
                'storage' => SessionStorage::class,
                'session_storage' => SessionSessionKeyStorage::class,
            ],
        ],
     
        // ...
     ];

   • Dynamic form

     return [
        // ...
     
        'forms' => [
            'customer' => [
                'builder_class' => CustomBuilder::class,
                'settings_class' => FormSettings::class,
                'storage' => SessionStorage::class,
                'session_storage' => SessionSessionKeyStorage::class,
            ],
        ],
     
        // ...
     ];

5. Use Stepped Form in you controller. Stepped Form will have service alias as "stepped-form." + form key form configuration.

   ServiceProvider.php

   use Lexal\HttpSteppedForm\SteppedFormInterface;
   
   $this->app->when(CustomerController::class)
        ->needs(SteppedFormInterface::class)
        ->give('stepped-form.customer');

   CustomerController.php

   use Lexal\HttpSteppedForm\SteppedFormInterface;
   
   final class CustomerController
   {
       public function __construct(private readonly SteppedFormInterface $form)
       {
       }
   
       // POST /customers
       public function start(): Response
       {
           return $this->form->start(new Customer(), /* nothing or customer id to split different sessions */);
       }
   
       // GET /customers/step/{step-key}
       public function render(string $key): Response
       {
           return $this->form->render($key);
       }
   
       // POST /customers/step/{step-key}
       public function handle(Request $request, string $key): Response
       {
           return $this->form->handle($key, $request);
       }
   
       // POST /customers/cansel
       public function cancel(): Response
       {
           return $this->form->cancel(route('customer.index'));
       }
   }

See configuration file for more information.

(back to top)

License

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