README

用于转义输入值、生成HTML标签和管理数据的辅助类。

许可证

MIT许可证

PSR

PSR-1、PSR-2和PSR-4。

入门

安装

composer require "tuum/form: ^1.0"

示例代码

有许多辅助工具，其中一些相关。使用DataView对象来管理辅助工具会更简单。例如，

$view = new Tuum\Form\DataView();
$view->setData([
    'name' => 'my-name',
    'bold' => '<b>bold</b>',
    'list' => ['v1', 'v2'],
]);
$view->setInputs([
    'name' => 'old-name',
    'more' => [
        'key' => 'val'
    ]
]);
// getting escaped data. 
echo $view->data['name']; // 'my-name'
echo $view->data['bold']; // escaped <b>bold</b>
echo $view->data->get('bold'); //  escaped <b>bold</b>
echo $view->data->raw('bold'); //  raw <b>bold</b>
// and arrays.
$list = $view->data->extractKey('list');
echo $list[0]; // 'v1'
echo $list[1]; // 'v2'

// getting old inputs
echo $view->inputs->get('name', $data['name']); // 'old-name'
echo $view->inputs->get('more[key]'); // val
// and use it in form generator. 
echo $view->forms->text('name', 'default'); 
// will output <input type="text" value="old-name">

DataView对象将Inputs对象注入到Forms辅助工具中，以便它可以使用旧的输入值（即old-name）而不是给定的值（即default）来生成HTML标签。

辅助工具列表

这些辅助工具帮助管理在模板中查看的数据。有以下几种：

Escape 用于转义字符串，
Data 用于管理数据，
Inputs 用于管理输入数据，
Errors 用于管理输入错误，
Message 用于消息，
Forms 用于生成表单元素，以及
Dates 用于生成复杂的表单元素。

转义辅助工具

Escape 类管理将字符串转义为在特定内容中安全显示，例如HTML。

HTML转义

默认情况下，字符串将通过Escape::htmlSafe($string)方法（该方法内部使用htmlspecialchars函数）进行转义。还有一些其他转义方法。

$esc = new Escape();
echo $esc('<danger>safe</danger>'); // or
echo $esc->escape('<danger>safe</danger>');

使用其他转义方法

您可以在构造函数中指定另一个转义方法或使用withEscape方法。

$esc = new Escape('addslashes');
// or
$esc = $esc->setEscape('rawurlencode');

转义方法必须是一个可调用的；可以是函数名，也可以是接受字符串作为参数的闭包。

在DataView中使用Escape

DataView对象包含一个用于与其他辅助工具（如Data和Inputs）共享的Escape对象。

在构造函数中指定转义。

$view = new DataView(new Escape('addslashes'));
$view->inputs->get('with-slash'); // escaped with addslashes.
// or change how to escape
$view->escape->setEscape('rawurlencode');

Data辅助工具

使用Data类在转义值的同时将字符串和值显示到模板中。

// construct yourself. 
$data = Data::forge(['view'=>'<i>val</i>'], $escape);

// or use DataView class. 
$view = new DataView();
$view->setData(['some'=>'value']);
$data = $view->data;

要访问数据，以下任何一种方法都适用。

echo $data['view'];      // escaped
echo $data->view;        // escaped
echo $data->get('view'); // escaped
echo $data->raw('view'); // raw value
echo $data->get('none', 'non\'s'); // show escaped default value

遍历数组

Data对象实现了IteratorAggregate接口。

$data1 = [
    'text' => 'testing',
    'more' => '<b>todo</b>',
];
$data2 = [
    'text' => 'tested',
    'more' => '<i>done</i>',
];
$data = Data::forge([$data1, $data2]);
foreach($data as $key => $val) {
    echo "$key: ", $val->text;
    echo "$key: ", $val->more; // escaped. 
}

仅适用于数组。所以不要这样做...

$data = Data::forge([
    'text' => 'tested',
    'more' => '<i>done</i>',
]);
foreach($data as $key => $val) {
    echo "$key: ", $val->get(null); // won't work!
}

按键提取

使用extractKey方法创建Data对象的子集，如果数据是另一个数组（或对象）的数组。

$data = Data::forge([
    'obj'=>new ArrayObject['type' => 'object']
]);
$obj = $data->extractKey('obj');
echo $obj->type;  // object

隐藏标签

有一个简单的方法来显示隐藏标签

$data = Data::forge(['_method'=>'put']);
echo $data->hiddenTag('_method');  
// <input type="hidden" name="_method" value="put" />

Inputs辅助工具

使用Inputs类通过HTML表单元素名称方便地访问数据数组。

<?php
$input = Inputs::forge([
    'name' => '<my> name',
    'gender' => 'male',
    'types' => [ 'a', 'c' ],
    'sns' => [
        'twitter' => 'example@twitter.com',
        'facebook' => 'example@facebook.com',
    ],
], $esc);

echo $input->get('name'); // escaped '<my> name'
echo $input->get('sns[twitter]'); // 'example@twitter.com'
vardump($input->get('types')); // ['a', 'c']

`selected`和`checked`方法

存在selected和checked方法来简化某些表单元素的检查。

// supply name of elements and its value. 
echo $input->selected('gender', 'male');   // 'selected'
echo $input->selected('gender', 'female'); // empty
echo $input->checked('types', 'a'); // ' checked'
echo $input->checked('types', 'b'); // empty

Errors辅助工具

Errors类管理与输入值相关的错误消息，其工作方式与Inputs类类似，但该类有一个方法，即p，它以预定义的格式输出错误消息。

<?php
$errors = Errors::forge([
    'name' => 'message for name',
    'gender' => 'gender message',
    'types' => [ 2 => 'message for type:B' ],
    'sns' => [
        'facebook' => 'love messaging facebook?',
    ],
], $esc);
// default format is: <p class="text-danger">%s</p>
echo $errors->p('name'); // message for name
echo $errors->p('gender');   // gender message
echo $errors->p('types[2]'); // message for type:B
echo $errors->p('sns[facebook]'); // love messaging facebook?

消息格式

要更改错误消息的格式，只需这样做。

$errors->format = '<div>(*_*) %s</div>';

Message辅助工具

此辅助工具可能不是通用的。Message类是用于在网页主要内容中显示的通用消息。

$message = Message::forge();
$message->add('hello');
$message->add('whoops', Message::ERROR);

echo $message;
// shows two divs for hello and whoops. 

echo $message->onlyOne(); 
// <div class="alert alert-danger">Whoops</div>

onlyOne方法仅显示最严重的第一条消息。

消息格式

对于每个严重性级别，都有3种格式。根据需要更改格式。

$message->formats = [
    self::MESSAGE => '<div>:) %s</div>',
    self::ALERT   => '<div>:| %s</div>',
    self::ERROR   => '<div>:( %s</div>',
];

Forms辅助工具

Forms辅助工具类生成各种HTML表单标签。

$form = new Form();

// or using DataView
$view = new DataView();
$form = $view->forms;

使用`Inputs`对象

将Inputs对象注入到Forms对象中，以便在生成HTML标签时使用。

$forms = $forms->withInputs($inputs);

HTML转义

Forms类不会转义其属性和值。它假设值由程序员提供。因此，在显示用户输入时，请使用Data辅助类。

$forms->text('safe', $data->get('safe'));

输入元素

创建各种表单输入元素。最通用的是input方法。

<?= $form->input('text', 'name', 'default value'); ?>

将生成

<input type="text" name="name" value="default value" />

已经存在许多用于HTML输入标签的方法，例如：文本、隐藏、电子邮件、密码、单选和复选框。

可以通过方法添加额外的HTML属性，如下所示。

<?= $form->date('radio')->class('form')->placeholder('date')->checked; ?>

在Forms对象中定义了许多快捷方法，如text、hidden、datetime等。所有这些快捷方法具有相同的签名

$form->$method(string $name, string $value = null);

打开/关闭表单

开始和关闭表单；

<?= $form->open()->action('to')->method('post')->uploader(); ?>
<?= $form->close(); ?>

如果提供了非标准方法，则将在open()方法中生成一个包含该方法的隐藏标签。默认名称为_method，可以通过method的第二个参数进行修改，如下所示；

<?= $form->open()->action('to')->method('put', 'method_token'); ?>

<form method="post" action="to" >
<input type="hidden" name="method_token" value="put" />

按钮

目前支持两种按钮。

$form->submit('button name');
$form->reset('cancel me');

文本区域

支持文本区域。

$form->textArea('area-name', 'default value');

选择列表

创建选择框非常简单。

$list = [
    '1' => 'selecting',
    '2' => 'made',
    '3' => 'easy',
];
echo $form->select('name', $list, '2');

第一个参数是元素的名称，第二个是选项的索引，第三个是选中项。

复选框和单选按钮列表

通常您想生成一个复选框或单选按钮的列表。您可以像创建选择框一样构建它。

$list = [
    '1' => 'checkbox',
    '2' => 'radio',
];
echo $form->checkList('checks', $list, '1');

将在ul > li内输出复选框列表，并用label包围；

<ul>
  <li><label><input type="checkbox" name="checks" value="1" />checkbox</label></li>
  <li><label><input type="checkbox" name="radio" value="1" />radio</label></li>
</ul>

您可以使用自己的代码构建HTML。

$list = $form->checkList('radio', $list, '2');
foreach($list as $key => $html) {
   echo $list->getLabel($key), ': ', $html, '<br/>';
}

日期辅助类

Dates辅助类旨在帮助构建复杂表单元素，例如日期（具有年、月和日输入元素）。例如，

$form = new Dates();
echo $dates->setYear(
    Lists::years(2014, 2016)
)->dateYMD('my-date', '2015-06-18');

将生成2014年和2016年之间的HTML；

<select name="my-date_y">...</select>
<select name="my-date_m">...</select>
<select name="my-date_d">...</select>

使用列表表示年、月和日

当使用年列表构建日期时，默认情况下，它将生成从去年到下一年作为范围。您可以通过使用setYear方法来更改此设置。

有set*方法用于年、月、日、时、分和秒。每个方法期望得到ListInterface、Traversable对象或数组。对于每种类型，也有相应的List对象，具有特定方法以显示不同的格式。

    
echo $date->setYear(
    Lists::years(2014, 2016)->useJpnGenGou()
)->setMonth(
    Lists::months()->useFullText()
)->withClass('tested-class')
->dateYM('test')
->resetWidth('123px');

将生成一些HTML，如下所示，

<select name="test_y" class="tested-class" style="width: 123px" >
    <option value="2014">平成26年</option>
    <option value="2015">平成27年</option>
    <option value="2016">平成28年</option>
</select>/<select name="test_m" class="tested-class" style="width: 123px" >
    <option value="1">January</option>
    <option value="2">February</option>
    <option value="3">March</option>
    <option value="4">April</option>
    <option value="5">May</option>
    <option value="6">June</option>
    <option value="7">July</option>
    <option value="8">August</option>
    <option value="9">September</option>
    <option value="10">October</option>
    <option value="11">November</option>
    <option value="12">December</option>
</select>

tuum / form

维护者

详情

README

许可证

PSR

入门

安装

示例代码

辅助工具列表

转义辅助工具

HTML转义

使用其他转义方法

在DataView中使用Escape

Data辅助工具

遍历数组

按键提取

隐藏标签

Inputs辅助工具

`selected`和`checked`方法

Errors辅助工具

消息格式

Message辅助工具

消息格式

Forms辅助工具

使用`Inputs`对象

HTML转义

输入元素

打开/关闭表单

标签

按钮

文本区域

选择列表

复选框和单选按钮列表

日期辅助类

使用列表表示年、月和日

tuum / form

维护者

详情

README

许可证

PSR

入门

安装

示例代码

辅助工具列表

转义辅助工具

HTML转义

使用其他转义方法

在DataView中使用Escape

Data辅助工具

遍历数组

按键提取

隐藏标签

Inputs辅助工具

selected和checked方法

Errors辅助工具

消息格式

Message辅助工具

消息格式

Forms辅助工具

使用Inputs对象

HTML转义

输入元素

打开/关闭表单

标签

按钮

文本区域

选择列表

复选框和单选按钮列表

日期辅助类

使用列表表示年、月和日

`selected`和`checked`方法

使用`Inputs`对象