README

一个由 Aura.Input 和 Ray.Di 驱动的面向切面的 Web 表单模块。

入门指南

安装

Composer 安装

$ composer require web-form-module

模块安装

use Ray\Di\AbstractModule;
use Ray\WebFormModule\AuraInputModule;

class AppModule extends AbstractModule
{
    protected function configure()
    {
        $this->install(new AuraInputModule);
    }
}

使用

表单类

我们提供了两种自我初始化表单类的方法，一种是 init() 方法，我们在其中添加一个输入字段并应用过滤器规则。另一种方法是 submit()，用于提交数据。更多详情请见 Aura.Input 自我初始化表单。

use Ray\WebFormModule\AbstractForm;
use Ray\WebFormModule\SetAntiCsrfTrait;

class MyForm extends AbstractForm
{
    // for anti CSRF
    use SetAntiCsrfTrait;

    /**
     * {@inheritdoc}
     */
    public function init()
    {
        $this->setField('name', 'text')
             ->setAttribs([
                 'id' => 'name'
             ]);
        $this->filter->validate('name')->is('alnum');
        $this->filter->useFieldMessage('name', 'Name must be alphabetic only.');
    }

    /**
     * {@inheritdoc}
     */
    public function submit()
    {
        return $_POST;
    }

    /**
     * {@inheritdoc}
     */
    public function __toString()
    {
        $form = $this->form();
        // name
        $form .= $this->helper->tag('div', ['class' => 'form-group']);
        $form .= $this->helper->tag('label', ['for' => 'name']);
        $form .= 'Name:';
        $form .= $this->helper->tag('/label') . PHP_EOL;
        $form .= $this->input('name');
        $form .= $this->error('name');
        $form .= $this->helper->tag('/div') . PHP_EOL;
        // submit
        $form .= $this->input('submit');
        $form .= $this->helper->tag('/form');

        return $form;
    }
}

控制器

我们将需要表单验证的方法注解为 @FormValidation。我们可以使用 name 指定表单对象属性名，使用 @onFailure 指定失败方法名。

use Ray\Di\Di\Inject;
use Ray\Di\Di\Named;
use Ray\WebFormModule\Annotation\FormValidation;
use Ray\WebFormModule\FormInterface;

class MyController
{
    /**
     * @var FormInterface
     */
    protected $contactForm;

    /**
     * @Inject
     * @Named("contact_form")
     */
    public function setForm(FormInterface $form)
    {
        $this->contactForm = $form;
    }

    /**
     * @FormValidation(form="contactForm", onFailure="badRequestAction")
     */
    public function createAction()
    {
        // validation success
    }

    public function badRequestAction()
    {
        // validation faild
    }
}

视图

当提供 __toString 时，您可以渲染整个表单 HTML。

  echo $form; // render entire form html

或者根据输入元素渲染。

  echo $form->input('name'); // <input id="name" type="text" name="name" size="20" maxlength="20" />
  echo $form->error('name'); // "Name must be alphabetic only." or blank.

CSRF 防护

use Ray\WebFormModule\SetAntiCsrfTrait;

class MyController 
{
    use SetAntiCsrfTrait;

您可以为您的自定义 AntiCsrf 类提供。更多详情请见 Aura.Input

验证异常

当我们按以下方式安装 Ray\WebFormModule\FormVndErrorModule 时，

use Ray\Di\AbstractModule;

class FakeVndErrorModule extends AbstractModule
{
    protected function configure()
    {
        $this->install(new AuraInputModule);
        $this->override(new FormVndErrorModule);
    }

将抛出一个 Ray\WebFormModule\Exception\ValidationException。我们可以通过捕获异常来获取 application/vnd.error+json 媒体类型。

echo $e->error;

//{
//    "message": "Validation failed",
//    "path": "/path/to/error",
//    "validation_messages": {
//        "name": [
//            "Name must be alphabetic only."
//        ]
//    }
//}

可以使用 @VndError 注解添加更多关于 vnd.error+json 的详细信息。

    /**
     * @FormValidation(form="contactForm")
     * @VndError(
     *   message="foo validation failed",
     *   logref="a1000", path="/path/to/error",
     *   href={"_self"="/path/to/error", "help"="/path/to/help"}
     * )
     */

此可选模块对于 API 应用程序非常方便。

示例

$ php -S docs/demo/1.csrf/web.php