gregwar/dsd

强大的、实用的表单库

维护者

详细信息

github.com/Gregwar/DSD

主页

源码

问题

安装: 11

依赖: 0

建议者: 0

安全: 0

星星: 121

关注者: 8

分支: 20

v2.2.1 2023-10-06 16:22 UTC

Requires

Requires (Dev)

Suggests

MIT b8f3f94fc24191450ba1c619d9f26e63372e47d3

htmlFormsinputfields

This package is not auto-updated.

Last update: 2024-09-14 13:23:23 UTC

README

PHP 7 PHP 7.1 PHP 7.2 Build status paypal

Formidable 是一个 PHP 库，用于处理表单。它可以解析 HTML 表单，并允许您从 PHP 代码中操作它，然后渲染它。

它是如何工作的？

步骤 1：下载并安装 Formidable

通过 composer

{
    "require": {
        "gregwar/formidable": "dev-master"
    }
}

或者通过克隆仓库

git clone https://github.com/Gregwar/Formidable.git

或者下载它

步骤 2：在 HTML 中编写您的表单

首先，您需要在 HTML 中编写代码，例如

<!-- forms/example.html -->
<form method="post">
    Enter your name: 
    <input type="text" name="name" /><br />
    <input type="submit" />
</form>

步骤 3：将表单交给 Formidable

在您的 PHP 代码中，将表单交给 Formidable

<?php
session_start();
include('vendor/autoload.php');

// Formidable will parse the form and use it to check integrity
// on the server-side
$form = new Gregwar\Formidable\Form('forms/example.html');

$form->handle(function() {
    echo "Form OK!";
}, function($errors) {
    echo "Errors: <br/>";
    foreach ($errors as $error) {
        echo "$error<br />";
    }
});

echo $form;

简单，对吧？

步骤 4：享受魔法

然后，您可以使用 Formidable API 来玩转您的表单

<?php

// Will set the value of the field
$form->name = "Bob";

// Will get the value of the field
$name = $form->name;

// Adds a constraint on the name
$form->addConstraint('name', function($value) {
    if (strlen($value) < 10) {
        return 'Your name should be at least 10 characters!';
    }
});

// Adds a constraint on the whole form
$form->addConstraint(function($form) {
    if ($form->getValue('pass1') != $form->getValue('pass2')) {
        return 'The passwords are different';
    }
});

您也可以尝试直接在 HTML 代码中更改表单并添加约束

<input type="text" name="name" minlength="10" />

这将强制文本在服务器端约束检查时至少为 10 个字符长。

想要为表单添加 CAPTCHA 来确保安全吗？

<input type="captcha" name="code" />

这将生成客户端上的图片和输入字段，并使用服务器端会话来检查代码是否正确。

注意，这将使用与 Gregwar/Captcha 库的依赖关系（您将需要使用 composer 安装依赖项）。

类型

以下输入类型被支持

  • input 标签，类型
    • text
    • number 或 numeric，查看 min 和 max 属性
    • int 或 integer，查看 min 和 max 属性
    • file
    • checkbox
    • radio
    • hidden
    • password
    • captcha，将自动生成图片
    • date，将生成三个选择框，并返回一个 DateTime 作为数据
    • multiradio 和 multicheckbox（请参阅源代码部分）
  • textarea
  • select

属性

请注意，某些属性不是 HTML 有效的，例如 maxlength

<input type="text" name="name" maxlength="10" />

它将不会在 HTML 表单中渲染，但将用于检查完整性。

以下是可用属性的列表

  • minlength：值的最低长度
  • maxlength：值的最大长度
  • regex：值应该遵守的正则表达式
  • min（对于数字）：最小值
  • max（对于数字）：最大值
  • required：告诉字段是必需的
  • readonly：字段是只读的，不应修改
  • value：字段的默认值
  • min-entries：指定您应该提供的多个（如下所示）的最小数量
  • max-entries：指定您可以提供的多个（如下所示）的最大数量
  • entries：指定多个的最小和最大数量（如下所示）

API

您可以在您的 $form 对象上调用这些方法

  • posted()：如果表单已提交则返回 true
  • check()：检查表单并返回一个包含有效性错误的数组
  • handle($callback, $errorCallback)，这个快捷方法调用 posted 和 check()，如果表单有效则调用 $callback，否则调用 $errorCallback
  • setAttribute($field, $attr, $value)：在字段上设置一个额外属性
  • getAttribute($field, $attr)：获取字段上的一个额外属性
  • source($source, $values)：提供源（请参阅“源”部分）
  • setPlaceholder($name, $value)：设置一个占位符值（请参阅下文）
  • addConstraint($field, $callback)：在字段上添加自定义约束，callback将使用字段值被调用，如果无问题则返回false，或者一个错误字符串。如果您只传递一个闭包给它，闭包将使用表单作为参数被调用，然后可以执行涉及多个字段或表单信息的测试。
  • setValue($field, $value)：设置字段的值
  • getValue($field)：获取字段的值
  • setValues(array $values)：为一些字段设置值
  • getValues()：获取所有字段的值

CSRF保护

当表单提交时，会自动在表单中插入一个额外的CSRF令牌并检查其有效性。因此，您的所有表单都将得到保护。

CSRF令牌的存在和有效性被用来检查在调用posted方法（它在handle中内部使用）时表单是否已被提交。

如果您在form中指定了name属性，这个特定表单的CSRF令牌将会有所不同，这将允许Formidable区分在同一个页面上如果有多个表单，哪个表单被提交。

语言

可以使用setLanguage()设置错误信息的语言

<?php

// Will set the language to french for errors
$form->setLanguage(new Gregwar\Formidable\Language\French);

请检查您的语言是否在Language目录中得到支持，不要犹豫参与进来！

源码

您可以使用来源系统动态地填充一个select、一个multiradio或一个multicheckbox

<input type="multicheckbox" name="colours" source="colours" />

然后使用source填充它

<?php
$form->source('colours', array('red', 'yellow', 'blue'));

这将通过一些复选框来渲染。

您可以使用相同的方式使用select

<select name="colour">
    <options source="colours" />
    <option value="other">Other</option>
</select>

然后用相同的方法填充来源

从字符串创建表单

您可以从文件或从字符串创建表单，这将自动检测

<?php

$form = new Gregwar\Formidable\Form('<form method="post">
    <select name="colour">
        <option value="blue">Blue</option>
        <option selected value="red">Red</option>
        <option value="green">Green</option>
    </select>
    </form>');

echo $form->getValue('colour') . "\n";
// red

// Sets the color to blue
$form->setValue('colour', 'blue');

echo $form;
/* Will display:
<form method="post">
    <select name="colour" >
        <option selected="selected" value="blue">Blue</option>
        <option value="red">Red</option>
        <option value="green">Green</option>
    </select>
    <input type="hidden" name="posted_token" value="d293dc38017381b6086ff1a856c1e8fe43738c60" />
</form>
*/

映射

您还可以使用mapping属性来填充表单或以数组或对象的形式返回表单数据，例如

<?php

class Person
{
    protected $name;
    public function getName() { return $this->name; }
    public function setName($name) {
        $this->name = $name;
    }
}

$person = new Person;
$person->setName('Jack');

$form = new Gregwar\Formidable\Form('<form method="post">
    <input type="text" name="name" mapping="name" />
    </form>');

$form->setData($person);

echo $form;
/*
Will output something like:

<form method="post">
    <input required="required" type="text" name="name" value="Jack" />
    <input type="hidden" name="posted_token" value="aa27f437cc6127c244db14361fd614af51c79aac" />
</form>
*/

请注意，映射使用Symfony PropertyAccessor，然后您可以使用类似上面的示例来填充属性。

您可以使用

  • getData($entity = array())：填充并返回填充了数据的实体
  • setData($entity)：用实体属性填充表单

创建多个子表单

您可以使用<multiple>标签向页面上添加多个子表单

<form method="post">
    Film name: <input type="text" name="film_name" mapping="name" />

    <h2>Actors</h2>
    <multiple name="actors" mapping="actors">
        First name: <input name="first_name" mapping="firstName" /><br />
        Last name: <input name="last_name" mapping="lastName" /><br />
    </multiple>
    <input type="submit" />
</form>

在这种情况下，<multiple>可以像字段一样使用，但它将包含一个元素数组。

页面中将注入一些JS，允许您添加/删除一些元素。

您可以使用min-entries和max-entries约束来设置多个元素的数量限制。

如果您为min-entries和max-entries指定了相同的值，或者指定了entries（这实际上是一个别名）的值，则输入数量将是固定的，不需要JavaScript。

将动态数据添加到表单中

在某些情况下，您可能想要将自定义数据添加到表单中，有两种方法可以实现。

第一种方法：使用占位符

{{ something }}语法允许您简单地从代码中注入数据，如下所示

<?php

$form = new Gregwar\Formidable\Form('<form method="post">
    Hello {{ name }}!
    </form>');

$form->setPlaceholder('name', 'Bob');

echo $form;

在上面的例子中，{{ name }}将被渲染为Bob。

请注意，占位符可以在除了<form>和input标签之外的地方使用。

<?php

$form = new Gregwar\Formidable\Form('<form method="post">
    <span style="color:{{ color }}">Hello</span>
    </form>');

$form->setPlaceholder('color', 'red');

echo $form;

第二种方法：使用PHP表单

您也可以像模板一样编写表单，例如

<form>
    <?php echo $label; ?>: <input type="text" name="name" />
    <input type="submit" />
</form>

然后通过传递模板变量作为第二个参数来实例化表单

<?php

$form = new Gregwar\Formidable\Form('the-above-form.php', array('label' => 'Your name'));

$label将被PHP解释。

缓存

出于性能考虑，您可能希望缓存解析后的表单。

为此，只需将 true 作为构造函数的第三个参数传递即可。

<?php

/**
 * Parsed data for the form will be serialized and stored in a cache file,
 * if you use this form often, this will offer you better performances.
 */
$form = new Gregwar\Formidable\Form('form.html', null, true);

这将使用 Gregwar/Cache 系统，您需要获取此存储库的 composer 依赖项或手动安装它。默认情况下，缓存文件将写入从脚本运行处的 cache 目录。

尝试在 examples/ 目录中运行 performances.php 脚本，这将给出使用缓存提高性能的示例。

您还可以传递 Gregwar\Cache\Cache 的实例作为第三个参数，这将允许您设置缓存目录。

许可协议

Gregwar\Formidable 采用 MIT 许可协议，有关更多信息，请参阅 LICENSE 文件。

历史记录

V2.0.0 停止支持 PHP <5.6

V2.1.0 移除对 Captcha 库的硬依赖