README

Form 组件允许检查用户传入的数据，显示表单组件，并执行这些数据的后处理。

表单处理开始于创建构成表单的字段，以及它们的配置。例如

$f = new Form($request);
$f->addInput('name', 'Имя')
  ->addFilter('!^[a-z]+$!i');
$f->addCheckbox('is_active', 'Вкл');
$f->addSelect('status', 'Статус', array('new' => 'Новый', 'old' => 'Старый'));
$f->addFile('image', 'Изображение')
  ->setIsRequired();
    

表单中的每个元素都是独立的对象，具有自己的参数集。`add*` 方法返回创建的元素对象，因此可以立即指定所需的属性和过滤器。

表单元素

• 输入
• 密码
• 复选框
• 单选按钮
• 选择框
• 文本区域
• 文件

如果愿意，可以创建自己的表单元素，继承自 SQRT\Form\Element 类，并通过 $f->add() 方法将其添加到表单中。

之后，可以使用 $f->getFields() 获取表单的所有字段，或者使用 $f->field('name') 选择性地获取字段；

每个元素都实现了一个 render() 方法，该方法返回一个具有相应字段显示的 Tag 对象。

验证

表单配置

对于数据验证，以下选项可供每个表单元素进行配置

• setIsRequired() - 字段必须填写
• addFilter($filter) - 使用正则表达式，callable 或允许选项数组对数据进行过滤。

如果需要更复杂的逻辑，可以在 setBeforeValidation 和 setAfterValidation 方法中添加相应的 callable 对象来添加验证前后的检查。

$f->setBeforeValidation(
  function ($data, Form $form) {
    if ($data['status'] == 'new' && $data['age'] > 10) {
      $form->addError('Возраст новых участников должен быть меньше 10');
    }
    
    $data['is_active'] = 1;

    return $data;
  }
);

函数接收一个与字段列表和表单对象相对应的数据数组。函数必须返回一个包含数据的数据数组，并且可以在验证的下一阶段之前修改它们。

验证结果

创建表单后，可以检查从用户那里接收到的数据：$f->validate($data = null)。

在创建表单对象时，它传递一个 Request 对象，表单默认从中获取用户数据。如果愿意，可以直接将数据传递给验证方法。

如果数据未通过验证，可以使用 $f->getErrors() 获取表单错误列表，或使用 $f->isValid() 检查表单状态。

验证后，可以简单地使用 $f->getValues() 或 $f->getValue($field) 获取“干净”数据，或者将处理程序添加到表单本身。

$f->setProcessData(
  function(Form $form){
    $data = $form->getValues();
    
    try {
        // Действия с данными    
    } catch (\Exception $e) {
        $form->addError($e->getMessage());
    }
  }
);

处理程序仅在验证成功时调用。

如果表单与 Request 对象一起使用，可以获取“原始”数据 getValueFromRequest($field, $default = false) 或确保请求中存在值 checkRequestHasValue($field)。

表单继承

如果表单被继承，则重写 init() 方法以配置字段，从而避免重复构造函数的逻辑。

在继承时，也可以重写验证前后的处理程序以及数据处理过程。

• beforeValidation($data)
• afterValidation($data)
• process()

文件处理

默认情况下，表单从 Request 中获取数据，如果需要直接将数据传递给 validate($data) 方法，则文件以 \Symfony\Component\HttpFoundation\File\File 对象的形式传递。

为了方便处理文件，表单字段具有以下方法，用于区分 File 和 UploadedFile 对象：

$f->field('image')->getExtension(); // Расширение загруженного файла
$f->field('image')->copy($destination); // Скопировать или переместить (move_uploaded_file) файл

验证码 (Captcha)

要将在表单中包含验证码检查，请调用方法 $f->enableCaptcha($name = 'captcha')。参数 $name 指定会话中的变量名和表单字段名。可以通过传递 $name 等于 false 来禁用验证码。

显示验证码给用户的脚本必须将当前验证码的值记录到会话中。表单始终使用传递的 Request 中的会话。

可以通过 $f->setErrCaptcha($err_captcha) 使用 $f->setErrCaptcha($err_captcha) 更改用户输入错误验证码时的消息文本。