README

该软件包基于步骤表单软件包，并与HTTP响应和请求一起工作（将表单异常转换为响应，并根据基本表单返回值进行渲染或重定向）。

目录

1. 要求
2. 安装
3. 使用
   • 异常正常化
4. 许可

要求

PHP >=8.1

安装

通过Composer

composer require lexal/http-stepped-form

使用

1. 创建基础 步骤表单。

2. 声明您的表单设置。

   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();

3. 创建重定向器。重定向器创建并返回重定向响应。

   use Lexal\HttpSteppedForm\Routing\RedirectorInterface;
   use Symfony\Component\HttpFoundation\Response;
   
   final class Redirector implements RedirectorInterface
   {
       public function redirect(string $url, array $errors = []): Response
       {
           // create and return redirect response
       }
   }
   
   $redirector = new Redirector();

4. 创建渲染器。渲染器通过模板定义创建并返回响应。

   use Lexal\HttpSteppedForm\Renderer\RendererInterface;
   use Lexal\SteppedForm\Entity\TemplateDefinition;
   use Symfony\Component\HttpFoundation\Response;
   
   final class Renderer implements RendererInterface
   {
       public function render(TemplateDefinition $definition): Response
       {
           // create and return response
       }
   }
   
   $renderer = new Renderer();

5. 创建异常正常化。

   use Lexal\HttpSteppedForm\ExceptionNormalizer\ExceptionNormalizer;
   use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\AlreadyStartedExceptionNormalizer;
   use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\DefaultExceptionNormalizer;
   use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\EntityNotFoundExceptionNormalizer;
   use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\FormIsNotStartedExceptionNormalizer;
   use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\StepNotFoundExceptionNormalizer;
   use Lexal\HttpSteppedForm\ExceptionNormalizer\Normalizers\StepNotRenderableExceptionNormalizer;
   
   $normalizer = new ExceptionNormalizer([
       new AlreadyStartedExceptionNormalizer($redirector),
       new EntityNotFoundExceptionNormalizer($redirector),
       new FormIsNotStartedExceptionNormalizer($redirector),
       new StepNotRenderableExceptionNormalizer(),
       new StepNotFoundExceptionNormalizer(),
       new DefaultExceptionNormalizer(),
   ]);

6. 创建步骤表单。

   use Lexal\HttpSteppedForm\SteppedForm;
   
   $form = new SteppedForm(
       /* a base stepped form from the step 1 */,
       $formSettings,
       $redirector,
       $renderer,
       $normalizer,
   );

7. 在您的应用程序中使用步骤表单。

   /*
    * Starts a new form session.
    * Returns redirect response to the next step or URL after form finish.
    */
   $form->start(
       /* an entity to initialize a form state */,
       /* unique session key is you need to split different sessions of one form */,
   );
   
   /* Renders step by its definition */
   $form->render('key');
   
   /*
    * Handles a step logic and saves a new form state.
    * Returns redirect response to the next step or URL after form finish.
    */
   $form->handle('key', /* request instance*/);
   
   /* Cancels form session and returns redirect response to the given URL */
   $form->cancel(/* any URL */);

异常正常化

异常正常化用于将步骤表单异常规范化为响应实例。创建一个实现 ExceptionNormalizerInterface 的类来创建您自己的异常正常化器。

use Lexal\HttpSteppedForm\Settings\FormSettingsInterface;
use Lexal\HttpSteppedForm\ExceptionNormalizer\ExceptionNormalizerInterface;
use Lexal\SteppedForm\Exception\AlreadyStartedException;
use Lexal\SteppedForm\Exception\SteppedFormException;
use Symfony\Component\HttpFoundation\Response;

final class CustomExceptionNormalizer implements ExceptionNormalizerInterface
{
    public function supportsNormalization(SteppedFormException $exception): bool
    {
        return $exception instanceof AlreadyStartedException;
    }
    
    public function normalize(SteppedFormException $exception, FormSettingsInterface $formSettings): Response
    {
        // return custom response object
        return new Response();
    }
}

该软件包已包含所有可用异常的正常化器

1. AlreadyStartedExceptionNormalizer - 重定向到当前可渲染步骤。
2. EntityNotFoundExceptionNormalizer - 带错误重定向到之前可渲染步骤或表单开始之前的URL。
3. FormIsNotStartedExceptionNormalizer - 带错误重定向到表单开始之前的URL。
4. StepNotFoundExceptionNormalizer - 返回404 HTTP状态码。
5. StepNotRenderableExceptionNormalizer - 返回404 HTTP状态码。
6. SteppedFormErrorsExceptionNormalizer - 带错误重定向到之前可渲染步骤或表单开始之前的URL。
7. StepIsNotSubmittedExceptionNormalizer - 带错误重定向到之前可渲染步骤或表单开始之前的URL。
8. DefaultExceptionNormalizer - 重新抛出异常。

许可

HTTP步骤表单采用MIT许可证。有关完整的许可证文本，请参阅LICENSE。