README

用于值解析、数据持久化、模板、CSRF和XSS防护的输入生成库。

文档

本文件作为Dora API文档。如果您愿意，可以在浏览交互式演示的同时学习Dora API，并使用本文件作为API参考。

表单

Form是一个数据容器。

/**
 * @param array $data Data used to populate Input generated using an instance of this Form.
 * @param null|string $template Template class name.
 */
$form = new \Gajus\Dora\Form([
    'foo' => 'Heeeere\'s...Johnny!',
    'bar' => 'Yada, yada, yada.',
    'baz' => 0,
    'qux' => ['1', 2 => '3'],
    'corge[grault]' = 'garply'
], null);

使用Form实例生成的Input将继承Form数据。

echo $form->input('foo');

名为"foo"的Input将继承"Here's...Johnny!"的值

<input name="foo" type="text" value="Heeeere's...Johnny!">

Input可以是任何类型的HTML输入。

echo $form->input('bar', ['type' => 'textarea', 'class' => 'test']);
echo $form->input('baz', null, ['options' => ['Knock, knock...', 'Come in.']]);

<textarea class="test" name="bar">Yada, yada, yada.</textarea>
<select name="baz">
    <option value="0" selected="selected">Knock, knock...</option>
    <option value="1">Come in.</option>
</select>

Input的名称可以从数组中解析值

echo $form->input('corge[grault]');

当使用变量数组语法声明Input时，Input的索引（即Input生成的顺序）将与数据数组中相应索引的值匹配。

echo $form->input('qux[]');
echo $form->input('qux[]');
echo $form->input('qux[]');

<input name="qux[]" type="text" value="1">
<input name="qux[]" type="text" value="">
<input name="qux[]" type="text" value="3">

输入

输入是由四个参数定义的独立实体。只需第一个参数是必需的。

/**
 * @param string $name Input name.
 * @param array $attributes HTML attributes.
 * @param array $properties Input properties, e.g. input name.
 * @param null|string $template Template class name.
 */
new \Gajus\Dora\Input('foo', ['type' => 'textarea'], ['name' => 'Foo'], null);

大多数情况下，Form将作为工厂来生成Input（如本页上的所有示例）。

HTML属性

添加到生成的输入的HTML属性。所有属性都将被原样接受，除了"type"。"type"属性将更改实际输入类型，例如："select"将使输入变为<select>，"textarea"将使它变为<textarea>。

输入属性

在生成输入模板时使用输入属性。

模板

Input可以使用Template进行装饰。当输入被转换为字符串时使用Template。Form模板将成为使用该Form实例生成的所有Input的默认模板

$form = new \Gajus\Dora\Form([], 'Gajus\Dora\Template\Traditional');

"Gajus\Dora\Template\Traditional"是默认模板。null将返回没有模板的输入。

传统模板

传统模板由标签、输入和可选描述组成。

<?php
namespace Gajus\Dora\Template;

/**
 * @link https://github.com/gajus/dora for the canonical source repository
 * @license https://github.com/gajus/dora/blob/master/LICENSE BSD 3-Clause
 */
class Traditional extends \Gajus\Dora\Template {
    public function toString () {
        $input = $this->getInput();
        $input_id = $input->getAttribute('id');
        $description = $input->getProperty('description');

        $class = $input->getProperty('class');
        $class = $class ? ' ' . $class : '';

        ob_start();?>
        <div class="dora-input<?=$class?>">
            <label for="<?=$input_id?>"><?=$input->getProperty('name')?></label>
            <?=$input?>
            
            <?php if ($description):?>
            <div class="description">
                <p><?=$description?></p>
            </div>
            <?php endif;?>
        </div>
        <?php
        return ob_get_clean();
    }
}

样式

Dora或传统模板不施加样式。传统布局样式的示例仅用于说明目的。

编写模板

模板类必须扩展Gajus\Dora\Template。

参考现有模板以了解更多信息。

CSRF

使用Dora生成的表单需要签名

$form = new \Gajus\Dora\Form();
?>
<form>
    <?=$form->sign()?>
    <input type="submit">
</form>

生成的签名由UID和CSRF令牌组成

<input type="hidden" name="gajus[dora][uid]" value="2953768934">
<input type="hidden" name="gajus[dora][csrf]" value="d0be2dc421be4fcd0172e5afceea3970e2f3d940">

UID用于识别用于生成输入的Form实例。UID在请求之间不会更改。
CSRF用于验证用户会话。

使用isSubmitted方法捕获表单提交时的情况，例如：

// $form from the preceding example.

if ($form->isSubmitted()) {
    // This will be triggered if CSRF passed.
}

不要使用

if ($_SERVER['REQUEST_METHOD'] === 'POST') {}
if (isset($_POST['gajus'])) {}
if (isset($_POST['your']['input'])) {}

上面的示例允许CSRF漏洞。

要绕过CSRF验证但继续从UID表单识别中受益，请使用isSubmitted(false)。

如果您不熟悉跨站请求伪造（CSRF，发音为"sea-surf"），请阅读：

Post/Redirect/Get

多拉假定应用程序是使用Post/Redirect/Get模式设计的。由于假定POST请求会导致重定向，多拉不会在POST请求中填充表单。多拉会复制POST数据并将其存储在临时会话中。这是通过使用./src/inc/agent.php脚本来实现的。如果你使用Composer，则此脚本将自动包含在每个请求中。

数据持久性

使用Post/Redirect/Get模式需要对用户输入进行特殊处理。如果你想在POST事件后（例如在出现错误的情况下）将用户返回到表单，你不想让用户重新输入所有值。多拉利用$_SESSION['gajus']['dora']['flash']变量来复制一个Post/Redirect/Get周期内的$_POST数据。如果你在POST后返回用户到表单，表单将填充最初提交的数据。

安装

使用多拉的推荐方式是通过Composer。

{
    "require": {
        "gajus/dora": "0.1.*"
    }
}

gajus / dora

维护者

详细信息