CraueFormFlowBundle 技术文档

1. 安装指南

1.1 获取 Bundle

使用 Composer 下载并安装 CraueFormFlowBundle：

composer require craue/formflow-bundle

1.2 启用 Bundle

如果你没有使用 Symfony Flex，需要手动注册 Bundle：

// 在 config/bundles.php 中
return [
    // ...
    Craue\FormFlowBundle\CraueFormFlowBundle::class => ['all' => true],
];

对于 Symfony 3.4：

// 在 app/AppKernel.php 中
public function registerBundles() {
    $bundles = [
        // ...
        new Craue\FormFlowBundle\CraueFormFlowBundle(),
    ];
    // ...
}

2. 项目使用说明

CraueFormFlowBundle 提供了一个在 Symfony 项目中构建和处理多步骤表单的工具。以下是一些主要功能：

• 导航：支持下一步、上一步、重新开始。
• 步骤标签：为每个步骤设置标签。
• 跳过步骤：根据条件跳过某些步骤。
• 验证组：为每个步骤设置不同的验证组。
• 文件上传处理：支持文件上传。
• 动态步骤导航：可选的动态步骤导航。
• 提交后重定向：支持 Post/Redirect/Get 模式。

3. 项目 API 使用文档

3.1 创建一个多步骤表单

方法 A：整个流程使用一个表单类型

创建 Flow 类

// src/MyCompany/MyBundle/Form/CreateVehicleFlow.php
use Craue\FormFlowBundle\Form\FormFlow;
use Craue\FormFlowBundle\Form\FormFlowInterface;
use MyCompany\MyBundle\Form\CreateVehicleForm;

class CreateVehicleFlow extends FormFlow {

    protected function loadStepsConfig() {
        return [
            [
                'label' => 'wheels',
                'form_type' => CreateVehicleForm::class,
            ],
            [
                'label' => 'engine',
                'form_type' => CreateVehicleForm::class,
                'skip' => function($estimatedCurrentStepNumber, FormFlowInterface $flow) {
                    return $estimatedCurrentStepNumber > 1 && !$flow->getFormData()->canHaveEngine();
                },
            ],
            [
                'label' => 'confirmation',
            ],
        ];
    }

}

创建表单类型类

// src/MyCompany/MyBundle/Form/CreateVehicleForm.php
use MyCompany\MyBundle\Form\Type\VehicleEngineType;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\FormBuilderInterface;

class CreateVehicleForm extends AbstractType {

    public function buildForm(FormBuilderInterface $builder, array $options) {
        switch ($options['flow_step']) {
            case 1:
                $validValues = [2, 4];
                $builder->add('numberOfWheels', ChoiceType::class, [
                    'choices' => array_combine($validValues, $validValues),
                    'placeholder' => '',
                ]);
                break;
            case 2:
                $builder->add('engine', VehicleEngineType::class, [
                    'placeholder' => '',
                ]);
                break;
        }
    }

    public function getBlockPrefix() {
        return 'createVehicle';
    }

}

方法 B：每个步骤使用一个表单类型

创建 Flow 类

// src/MyCompany/MyBundle/Form/CreateVehicleFlow.php
use Craue\FormFlowBundle\Form\FormFlow;
use Craue\FormFlowBundle\Form\FormFlowInterface;
use MyCompany\MyBundle\Form\CreateVehicleStep1Form;
use MyCompany\MyBundle\Form\CreateVehicleStep2Form;

class CreateVehicleFlow extends FormFlow {

    protected function loadStepsConfig() {
        return [
            [
                'label' => 'wheels',
                'form_type' => CreateVehicleStep1Form::class,
            ],
            [
                'label' => 'engine',
                'form_type' => CreateVehicleStep2Form::class,
                'skip' => function($estimatedCurrentStepNumber, FormFlowInterface $flow) {
                    return $estimatedCurrentStepNumber > 1 && !$flow->getFormData()->canHaveEngine();
                },
            ],
            [
                'label' => 'confirmation',
            ],
        ];
    }

}

创建表单类型类

// src/MyCompany/MyBundle/Form/CreateVehicleStep1Form.php
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\FormBuilderInterface;

class CreateVehicleStep1Form extends AbstractType {

    public function buildForm(FormBuilderInterface $builder, array $options) {
        $validValues = [2, 4];
        $builder->add('numberOfWheels', ChoiceType::class, [
            'choices' => array_combine($validValues, $validValues),
            'placeholder' => '',
        ]);
    }

    public function getBlockPrefix() {
        return 'createVehicleStep1';
    }

}

// src/MyCompany/MyBundle/Form/CreateVehicleStep2Form.php
use MyCompany\MyBundle\Form\Type\VehicleEngineType;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;

class CreateVehicleStep2Form extends AbstractType {

    public function buildForm(FormBuilderInterface $builder, array $options) {
        $builder->add('engine', VehicleEngineType::class, [
            'placeholder' => '',
        ]);
    }

    public function getBlockPrefix() {
        return 'createVehicleStep2';
    }

}

3.2 注册 Flow 为服务

XML 配置：

<services>
    <service id="myCompany.form.flow.createVehicle"
            class="MyCompany\MyBundle\Form\CreateVehicleFlow"
            autoconfigure="true">
    </service>
</services>

YAML 配置：

services:
    myCompany.form.flow.createVehicle:
        class: MyCompany\MyBundle\Form\CreateVehicleFlow
        autoconfigure: true

3.3 创建表单模板

{# in src/MyCompany/MyBundle/Resources/views/Vehicle/createVehicle.html.twig #}
<div>
    Steps:
    {% include '@CraueFormFlow/FormFlow/stepList.html.twig' %}
</div>
{{ form_start(form) }}
    {{ form_errors(form) }}

    {% if flow.getCurrentStepNumber() == 1 %}
        <div>
            When selecting four wheels you have to choose the engine in the next step.<br />
            {{ form_row(form.numberOfWheels) }}
        </div>
    {% endif %}

    {{ form_rest(form) }}

    {% include '@CraueFormFlow/FormFlow/buttons.html.twig' %}
{{ form_end(form) }}

3.4 创建 Action

// in src/MyCompany/MyBundle/Controller/VehicleController.php
public function createVehicleAction() {
    $formData = new Vehicle(); // Your form data class. Has to be an object, won't work properly with an array.

    $flow = $this->get('myCompany.form.flow.createVehicle'); // must match the flow's service id
    $flow->bind($formData);

    // form of the current step
    $form = $flow->createForm();
    if ($flow->isValid($form)) {
        $flow->saveCurrentStepData($form);

        if ($flow->nextStep()) {
            // form for the next step
            $form = $flow->createForm();
        } else {
            // flow finished
            $em = $this->getDoctrine()->getManager();
            $em->persist($formData);
            $em->flush();

            $flow->reset(); // remove step data from the session

            return $this->redirectToRoute('home'); // redirect when done
        }
    }

    return $this->render('@MyCompanyMy/Vehicle/createVehicle.html.twig', [
        'form' => $form->createView(),
        'flow' => $flow,
    ]);
}

4. 项目安装方式

通过 Composer 安装 CraueFormFlowBundle：

composer require craue/formflow-bundle

然后根据 Symfony 版本手动或自动注册 Bundle。