晴天飞舞/forms

简单的表单抽象API

维护者

详细信息

github.com/SunnyFlail/Forms

源代码

问题

安装: 93

依赖者: 0

建议者: 0

安全性: 0

星标: 0

关注者: 1

分支: 0

开放问题: 0

1.6.4 2021-08-04 11:43 UTC

Requires

Requires (Dev)

MIT a4a2a1134dbadf67b0dce6c03b9f4ed6a2bed434

This package is auto-updated.

Last update: 2024-09-04 18:15:59 UTC

README

简单的表单抽象层

1 创建表单

首先创建一个扩展 SunnyFlail\Forms\Form\FormElement 类的类。它必须实现 IFormElement::build 方法。

use SunnyFlail\Forms\Form\FormElement;
use SunnyFlail\Forms\Interfaces\IFormBuilder;

class ConcreteForm extends FormElement
{

    public function build(IFormBuilder $builder)
    {
        (...)
    }

}

1.1 添加字段

在 IFormElement::build 方法内部调用 IFormBuilder::add，将需要添加的字段作为参数提供。您可以链接此方法。

$builder->add(new InputField('text'));

1.2 配置表单

在 `方法内部，您可以更改属性
(必填) string $formName - 表单名称 - 将作为前缀提供给表单的字段名称
`string $formMethod` - 此表单将使用的 HTTP 方法（默认为 GET）
`string $buttonText` - 将显示在提交按钮中的文本
`array $attributes` - 提供给表单元素的属性
`array buttonAttributes` - 提供给表单提交按钮元素的属性
`IElement[] $topElements` - 实现 `SunnyFlail\HtmlAbstraction\Interfaces\IElement` 接口的对象数组 - 在所有字段之前打印的元素
`IElement[] $middleElements` - 实现 `SunnyFlail\HtmlAbstraction\Interfaces\IElement` 接口的对象数组 - 在字段之后、按钮之前打印的元素
`IElement[] $bottomElements` - 实现 `SunnyFlail\HtmlAbstraction\Interfaces\IElement` 接口的对象数组 - 在提交按钮之后打印的元素
`string|null $classFQCN` - 将解析为（普通旧PHP对象）类的FQCN，如果此值为null，则解析为 array
`bool $useHtmlValidation` - 此表单是否应使用 Html 验证（默认为 true）
`bool $withFiles` 如果设置为 true，则设置 enctype（编码类型）为 multipart/form-data

2 使用表单

2.1 创建构建器

首先需要创建表单构建器的全局副本

$objectCreator = new SunnyFlail\ObjectCreator\ObjectCreator();
$valueMapper = new SunnyFlail\Forms\Mappers\ValueMapper($objectCreator);
$valueProviderFactory = new SunnyFlail\Forms\Providers\ProviderFactory();

$builder = new SunnyFlail\Forms\Form\FormBuilder($valueMapper, $valueProviderFactory);

2.2 构建表单

然后调用 IFormBuilder::buildForm 方法，将表单 FQCN 作为第一个参数提供，可选地提供对象/数组以从中提取值作为第二个。
这返回构建器的副本，因此为它准备另一个变量

$concreteFormBuilder = $builder->buildForm(ConcreteForm::class);

2.3 处理用户输入

要处理用户提供的数据，请使用实现 Psr\Http\Message\ServerRequestInterface 接口的对象作为参数调用 IFormBuilder::processForm
这将返回一个布尔值，指示表单是否获取了有效值

if ($concreteFormBuilder->processForm($request)) {
    (...)
}

2.4 获取值

要获取从表单元素中刮取的值，请使用 IFormBuilder::getProcessedData

$values = $concreteFormBuilder->getProcessedData();

2.5 添加错误

要向表单添加错误，请使用 IFormBuilder::addError

$concreteFormBuilder->addError('An error occurred!');

2.6 渲染表单

您可以只将表单字符串化（例如 echo $concreteFormBuilder;）或将所有字段手动渲染。
要手动渲染表单，首先您需要通过调用 IFormBuilder::accessForm 来获取 Form 的副本
要获取 HTML 表单标签属性，请调用 IFormElement::getHTMLAttributes
要获取字段的关联数组，请调用 IFormElement::getFields
要获取字段输入元素，请调用 IField::getInputElement
要获取字段标签元素，请调用 IField::getLabelElement
这些方法可能返回一个 IElement 或它们的数组
如果发生错误，您可以使用 IField::getErrorElement 获取错误元素

3 个可用字段

3.1 InputField

这是 <input type="(...)"> 的表示

$input = new SunnyFlail\Forms\Fields\InputField();

Input 字段构造函数接受以下参数

string $name - 字段名称
string $type - 字段类型
bool $required - 是否此字段必须填写
bool $rememberValue - 是否此字段应保留提供的错误值
IConstraint[] $constraints - 实现 SunnyFlail\Constraints\Interfaces\IConstraint 接口的对象数组
array $errorMessages - 字符串数组，键必须是数字字符串，'-1' 用于无值错误，正键用于失败的约束错误
IElement[] $topElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在标签之前打印的元素
IElement[] $middleElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在输入之前打印的元素
IElement[] $bottomElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在错误之前打印的元素
array $inputAttributes - 提供给输入元素的 HTML 属性数组
array $containerAttributes - 提供给包装元素的 HTML 属性数组
array $errorAttributes - 提供给错误元素的 HTML 属性数组
?string $labelText - 标签内显示的文本，如果未设置，则显示字段名称
array $labelAttributes - 提供给标签元素的 HTML 属性数组

3.2 EmailField

这是 <input type="email"> 的表示

$input = new SunnyFlail\Forms\Fields\EmailField();

Email 字段构造函数接受以下参数
string $name - 字段名称
bool $required - 是否此字段必须填写
bool $rememberValue - 是否此字段应保留提供的错误值
array $errorMessages - 字符串数组，键必须是数字字符串，'-1' 用于无值错误，正键用于失败的约束错误
IElement[] $topElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在标签之前打印的元素
IElement[] $middleElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在输入之前打印的元素
IElement[] $bottomElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在错误之前打印的元素
array $inputAttributes - 提供给输入元素的 HTML 属性数组
array $containerAttributes - 提供给包装元素的 HTML 属性数组
array $errorAttributes - 提供给错误元素的 HTML 属性数组
?string $labelText - 标签内显示的文本，如果未设置，则显示字段名称
array $labelAttributes - 提供给标签元素的 HTML 属性数组

3.3 PasswordField

这是 <input type="password"> 的表示

$input = new SunnyFlail\Forms\Fields\PasswordField();

此字段引入了 Peeper - 一个按钮，当与适当的 JS 配合使用时，可以显示提供给字段的密码

Password 字段构造函数接受以下参数

string $name - 字段名称
bool $required - 是否此字段必须填写
bool $rememberValue - 是否此字段应保留提供的错误值
IConstraint[] $constraints - 实现 SunnyFlail\Constraints\Interfaces\IConstraint 接口的对象数组
array $errorMessages - 字符串数组，键必须是数字字符串，'-1' 用于无值错误，正键用于失败的约束错误
IElement[] $topElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在标签之前打印的元素
IElement[] $middleElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在输入之前打印的元素
IElement[] $bottomElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在错误之前打印的元素
bool $withPeeper - 是否此字段应带有 Peeper
array $inputAttributes - 提供给输入元素的 HTML 属性数组
array $peeperAttributes - 提供给 Peeper 元素的 HTML 属性数组
array $containerAttributes - 提供给包装元素的 HTML 属性数组
array $errorAttributes - 提供给错误元素的 HTML 属性数组
?string $labelText - 标签内显示的文本，如果未设置，则显示字段名称
array $labelAttributes - 提供给标签元素的 HTML 属性数组

3.4 TextAreaField

这是 <textarea></textarea> 的表示

$input = new SunnyFlail\Forms\Fields\TextAreaField();

TextArea 字段构造函数接受以下参数

string $name - 字段名称
bool $required - 是否此字段必须填写
bool $rememberValue - 是否此字段应保留提供的错误值
IConstraint[] $constraints - 实现 SunnyFlail\Constraints\Interfaces\IConstraint 接口的对象数组
array $errorMessages - 字符串数组，键必须是数字字符串，'-1' 用于无值错误，正键用于失败的约束错误
IElement[] $topElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在标签之前打印的元素
IElement[] $middleElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在输入之前打印的元素
IElement[] $bottomElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在错误之前打印的元素
array $inputAttributes - 提供给输入元素的 HTML 属性数组
array $containerAttributes - 提供给包装元素的 HTML 属性数组
array $errorAttributes - 提供给错误元素的 HTML 属性数组
?string $labelText - 标签内显示的文本，如果未设置，则显示字段名称
array $labelAttributes - 提供给标签元素的 HTML 属性数组

3.5 SelectField

这是 <select>(...)</select> 的表示

$input = new SunnyFlail\Forms\Fields\SelectField();

Select 字段构造函数接受以下参数

string $name - 字段名称
数组 $options - 渲染选项 - bool $required- 此字段是否必须填写
bool $rememberValue - 是否此字段应保留提供的错误值
bool $multiple - 此字段是否允许多个值
bool $useIntristicValues - 是否只检查 $options 参数中提供的值，还是接受任何符合提供约束的值
IConstraint[] $constraints - 实现 SunnyFlail\Constraints\Interfaces\IConstraint 接口的对象数组
array $errorMessages - 字符串数组，键必须是数字字符串，'-1' 用于无值错误，正键用于失败的约束错误
IElement[] $topElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在标签之前打印的元素
IElement[] $middleElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在输入之前打印的元素
IElement[] $bottomElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在错误之前打印的元素
array $inputAttributes - 提供给输入元素的 HTML 属性数组
array $containerAttributes - 提供给包装元素的 HTML 属性数组
array $errorAttributes - 提供给错误元素的 HTML 属性数组
?string $labelText - 标签内显示的文本，如果未设置，则显示字段名称
数组 $optionAttributes - 传递给 option 元素的 HTML 属性数组
array $labelAttributes - 提供给标签元素的 HTML 属性数组

3.6 CheckBoxGroupField

这是 <input type="checkbox"> 组的表示

$input = new SunnyFlail\Forms\Fields\CheckBoxGroupField();

复选框字段构造函数接收参数

string $name - 字段名称
数组 $options - 渲染选项 - bool $required- 此字段是否必须填写
bool $rememberValue - 是否此字段应保留提供的错误值
bool $multiple - 此字段是否允许多个值
bool $useIntristicValues - 是否只检查 $options 参数中提供的值，还是接受任何符合提供约束的值
IConstraint[] $constraints - 实现 SunnyFlail\Constraints\Interfaces\IConstraint 接口的对象数组
array $errorMessages - 字符串数组，键必须是数字字符串，'-1' 用于无值错误，正键用于失败的约束错误
array $inputAttributes - 提供给输入元素的 HTML 属性数组
array $containerAttributes - 提供给包装元素的 HTML 属性数组
array $errorAttributes - 提供给错误元素的 HTML 属性数组
array $labelAttributes - 提供给标签元素的 HTML 属性数组

3.7 RadioGroupField

这是 <input type="radio"> 组的表示

$input = new SunnyFlail\Forms\Fields\RadioGroupField();

单选按钮字段构造函数接收参数

string $name - 字段名称
数组 $options - 渲染选项 - bool $required- 此字段是否必须填写
bool $rememberValue - 是否此字段应保留提供的错误值
bool $useIntristicValues - 是否只检查 $options 参数中提供的值，还是接受任何符合提供约束的值
IConstraint[] $constraints - 实现 SunnyFlail\Constraints\Interfaces\IConstraint 接口的对象数组
array $errorMessages - 字符串数组，键必须是数字字符串，'-1' 用于无值错误，正键用于失败的约束错误
array $inputAttributes - 提供给输入元素的 HTML 属性数组
array $containerAttributes - 提供给包装元素的 HTML 属性数组
array $errorAttributes - 提供给错误元素的 HTML 属性数组
array $labelAttributes - 提供给标签元素的 HTML 属性数组

3.8 RepeatedInputField

包含两个字段，其值必须相同的字段

$input = new SunnyFlail\Forms\Fields\RepeatedInputField();

重复字段构造函数接收参数

IInputField $field - 第一个字段
IInputField $repeatedField - 重复字段
string $missmatchError - 错误时显示的消息

3.9 ClassMappedField

一组字段，其值将映射到普通 PHP 对象

$input = new SunnyFlail\Forms\Fields\ClassMappedField();

类映射字段构造函数接收参数

string $fieldName - 字段名称
string $classFQCN - 类名称
IField ...$fields - 命名为类属性名称的字段

3.10 FileUploadField

这是 <input type="file"> 的表示

文件上传字段构造函数接收参数

string $name - 字段名称
bool $required - 是否此字段必须填写
bool $multiple - 此字段是否允许多个值
IFileConstraint[] $constraints - 实现 SunnyFlail\Constraints\Interfaces\IFileConstraint 接口的对象数组
IElement[] $topElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在标签之前打印的元素
IElement[] $middleElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在输入之前打印的元素
IElement[] $bottomElements - 实现 SunnyFlail\HtmlAbstraction\Interfaces\IElement 接口的对象数组 - 在错误之前打印的元素
array $errorMessages - 字符串数组，键必须是数字字符串，'-1' 用于无值错误，正键用于失败的约束错误
array $inputAttributes - 提供给输入元素的 HTML 属性数组
array $containerAttributes - 提供给包装元素的 HTML 属性数组
array $errorAttributes - 提供给错误元素的 HTML 属性数组
?string $labelText - 标签内显示的文本，如果未设置，则显示字段名称
array $labelAttributes - 提供给标签元素的 HTML 属性数组
bool $terminateOnError - 如果某个文件的上传发生 http 错误，是否使此字段无效

3.11 FileUploadGroupField [自版本 ^1.3 开始]

一组文件上传字段

文件上传字段构造函数接收参数

string $name - 字段名称
int $inputCount - 应渲染多少个输入 - 必须至少为 1，如果设置为 1，则此字段的 multiple 属性设置为 false
int $required- 必需文件的最小数量
IFileConstraint[] $constraints - 实现 SunnyFlail\Constraints\Interfaces\IFileConstraint 接口的对象数组
array $errorMessages - 字符串数组，键必须是数字字符串，'-1' 用于无值错误，正键用于失败的约束错误
string[] $labelTexts - 标签内显示的文本，如果设置，则必须是一个增量数组，其键的数量与 $inputCount 中设置的相同，否则显示数字
array $inputAttributes - 提供给输入元素的 HTML 属性数组
array $containerAttributes - 提供给包装元素的 HTML 属性数组
array $errorAttributes - 提供给错误元素的 HTML 属性数组
array $labelAttributes - 提供给标签元素的 HTML 属性数组
bool $terminateOnError - 如果某个文件的上传发生 http 错误，是否使此字段无效

4 TODO

需要添加一个 IFormBuilder::getRawValues，它将返回一个关联数组，包含提供给字段的原始值