README

用于处理多步骤表单的向导。

功能

• 所有表单都提交到同一URL
• 仅支持前进/后退导航
• 循环
  • 根据需要重复表单中的一步或几步
• 分支导航（PBN）
  • 允许表单根据用户的响应决定采取哪条路径
• 步骤超时
  • 步骤可以设置超时，以确保用户在指定时间内做出响应
• 保存/恢复
  • 保存部分完成的表单；从该点恢复并继续
• 事件驱动
  • 编写处理函数并将它们连接到事件

有关许可信息，请参阅LICENSE文件。

安装

安装此扩展的首选方法是通过composer。

运行以下命令：

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

或将其添加到composer.json文件的require部分：

"beastbytes/wizard": "^1.0"

使用

使用

有关更多解释和示例，请参阅Wiki。

控制器

构造函数

在控制器构造函数中注入向导并初始化。

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'])
    ;
}

操作

控制器操作非常简单

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

提示： BeastBytes\Wizard\WizardTrait提供了向导操作。

事件

向导运行时会引发多个事件。所有事件都可以使用

$this->getWizard();

BeforeWizard

在向导处理任何步骤之前引发。可以使用以下方式阻止向导运行：

BeforeWizard::continue(false);

步骤

在处理步骤时引发。此事件的处理器执行通常的操作，例如渲染视图、表单提交的数据验证和保存；此事件针对每个步骤引发两次。

1. 第一次此事件引发时，事件处理器负责在视图中渲染适当的表单。
2. 第二次事件处理器负责数据验证并将数据设置到事件中。

请求

事件处理器使用

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

来确定请求的类型（Method::GET或Method::POST）。

CurrentStep

事件处理器使用

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

来确定正在处理的步骤。

保存数据

事件处理器使用

$this->saveData($data);

保存步骤的数据。

提示： 对于重复的步骤也使用相同的操作；向导将正确保存所有重复步骤的数据。

下一步

默认情况下，向导将移动到步骤数组中的下一个步骤，同时考虑任何活动分支。事件处理器可以告诉向导转到较早的步骤或重复步骤，使用

$this->setGoto($goto);

其中$goto是以下之一：

• Wizard::DIRECTION_BACKWARD向导转到上一个步骤
• Wizard::DIRECTION_FORWARD向导转到下一个步骤；默认行为
• Wizard::REPEAT向导重复当前步骤；事件处理器负责确定步骤重复的次数
• 'stepName'向导返回到指定的步骤；该步骤必须是较早的步骤。

分支

事件处理器负责决定在步骤数组中采取哪些分支（如果有的话）；使用

$this->branches($branches);

其中$branches是一个映射：['branchName' => BranchDirective]其中BranchDirective是Wizard::BRANCH_DISABLED或Wizard::BRANCH_ENABLED。

AfterWizard

在向导完成后触发。此事件处理器负责从向导中检索数据并将其保存到模型中。

使用以下方法从向导中检索日期：

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

以获取所有步骤的数据，或者

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

以获取特定步骤的数据。

StepExpired

在处理步骤超时时触发。如果触发此事件，步骤数据将被存储在向导中。