表单辅助函数

表单辅助函数文件包含用于处理表单的函数。

配置 

从 v4.3.0 开始，form_helper 函数中的空 HTML 元素（例如 <input>）默认情况下已更改为与 HTML5 兼容，如果您需要与 XHTML 兼容，则必须将 app/Config/DocTypes.php 中的 $html5 属性设置为 false。

加载此辅助函数 

此辅助函数使用以下代码加载

<?php

helper('form');

转义字段值 

您可能需要在表单元素中使用 HTML 和引号等字符。为了安全起见，您需要使用通用函数 esc()。

请考虑以下示例

<?php

$string = 'Here is a string containing "quoted" text.';

?>

<input type="text" name="myfield" value="<?= $string ?>">

由于上面的字符串包含一组引号，它会导致表单崩溃。 esc() 函数将 HTML 特殊字符转换为可以安全使用的形式

<input type="text" name="myfield" value="<?= esc($string) ?>">

注意

如果您使用此页面上列出的任何表单辅助函数，并将值作为关联数组传递，则表单值将自动转义，因此无需调用此函数。仅当您创建自己的表单元素（您将作为字符串传递）时才使用它。

可用函数 

以下函数可用

form_open([$action = ''[, $attributes = ''[, $hidden = []]]])

参数:

$action (string) – 表单操作/目标 URI 字符串
$attributes (mixed) – HTML 属性，作为数组或转义字符串
$hidden (array) – 隐藏字段定义的数组

返回值:

HTML 表单打开标签

返回类型:

string

创建一个带有站点 URL 的表单打开标签，该 URL **由您的** Config\App::$baseURL **构建**。它可以选择让您添加表单属性和隐藏输入字段，并且始终会根据您配置文件中的字符集值添加 accept-charset 属性。

使用此标签而不是硬编码您自己的 HTML 的主要好处是它允许您的网站在您的 URL 发生更改时更具可移植性。

这是一个简单的示例

<?php

echo form_open('email/send');

上面的示例将创建一个指向您的网站 URL 加上“email/send” URI 段的表单，如下所示

<form action="http://example.com/index.php/email/send" method="post" accept-charset="utf-8">

您也可以添加 {locale}，如下所示

<?php

echo form_open('{locale}/email/send');

上面的示例将创建一个指向您的网站 URL 加上当前请求区域设置和“email/send” URI 段的表单，如下所示

<form action="http://example.com/index.php/en/email/send" method="post" accept-charset="utf-8">

添加属性

可以通过将关联数组传递给第二个参数来添加属性，如下所示
<?php

$attributes = ['class' => 'email', 'id' => 'myform'];
echo form_open('email/send', $attributes);
或者，您可以将第二个参数指定为字符串
<?php

echo form_open('email/send', 'class="email" id="myform"');
上面的示例将创建一个类似于此的表单
<form action="http://example.com/index.php/email/send" class="email" id="myform" method="post" accept-charset="utf-8">
如果 CSRF 过滤器已打开，form_open() 将在表单开头生成 CSRF 字段。您可以通过将 csrf_id 作为 $attribute 数组之一传递来指定此字段的 ID
<?php

echo form_open('/u/sign-up', ['csrf_id' => 'my-id']);
将返回
<form action="http://example.com/index.php/u/sign-up" method="post" accept-charset="utf-8">
<input type="hidden" id="my-id" name="csrf_field" value="964ede6e0ae8a680f7b8eab69136717d">
注意

要使用 CSRF 字段的自动生成，您需要在表单页面上打开 CSRF 过滤器。在大多数情况下，它使用 GET 方法请求。

添加隐藏输入字段

可以通过将关联数组传递给第三个参数来添加隐藏字段，如下所示
<?php

$hidden = ['username' => 'Joe', 'member_id' => '234'];
echo form_open('email/send', '', $hidden);
您可以通过向其传递任何假值来跳过第二个参数。

上面的示例将创建一个类似于此的表单
<form action="http://example.com/index.php/email/send" method="post" accept-charset="utf-8">
    <input type="hidden" name="username" value="Joe">
    <input type="hidden" name="member_id" value="234">

form_open_multipart([$action = ''[, $attributes = ''[, $hidden = []]]])

参数:

$action (string) – 表单操作/目标 URI 字符串
$attributes (mixed) – HTML 属性，作为数组或转义字符串
$hidden (array) – 隐藏字段定义的数组

返回值:

一个 HTML 多部分表单打开标签

返回类型:

string

此函数与上面的 form_open() 相同，只是它添加了一个 multipart 属性，如果您想使用表单上传文件，则需要此属性。

form_hidden($name[, $value = ''])

参数:

$name (string) – 字段名称
$value (string) – 字段值

返回值:

一个 HTML 隐藏输入字段标签

返回类型:

string

允许您生成隐藏输入字段。您可以提交一个名称/值字符串来创建一个字段

<?php

form_hidden('username', 'johndoe');
// Would produce: <input type="hidden" name="username" value="johndoe">

…或者您可以提交一个关联数组来创建多个字段

<?php

$data = [
    'name'  => 'John Doe',
    'email' => '[email protected]',
    'url'   => 'http://example.com',
];

echo form_hidden($data);
/*
 * Would produce:
 * <input type="hidden" name="name" value="John Doe">
 * <input type="hidden" name="email" value="[email protected]">
 * <input type="hidden" name="url" value="http://example.com">
 */

您也可以将关联数组传递给 value 字段

<?php

$data = [
    'name'  => 'John Doe',
    'email' => '[email protected]',
    'url'   => 'http://example.com',
];

echo form_hidden('my_array', $data);
/*
 * Would produce:
 * <input type="hidden" name="my_array[name]" value="John Doe">
 * <input type="hidden" name="my_array[email]" value="[email protected]">
 * <input type="hidden" name="my_array[url]" value="http://example.com">
 */

如果您想创建带有额外属性的隐藏输入字段

<?php

$data = [
    'type'  => 'hidden',
    'name'  => 'email',
    'id'    => 'hiddenemail',
    'value' => '[email protected]',
    'class' => 'hiddenemail',
];

echo form_input($data);
/*
 * Would produce:
 * <input type="hidden" name="email" value="[email protected]" id="hiddenemail" class="hiddenemail">
 */

form_input([$data = ''[, $value = ''[, $extra = ''[, $type = 'text']]]])

参数:

$data (array) – 字段属性数据
$value (string) – 字段值
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串
$type (string) – 输入字段的类型。例如，“text”、“email”、“number”等。

返回值:

一个 HTML 文本输入字段标签

返回类型:

string

允许您生成一个标准的文本输入字段。您可以在第一个和第二个参数中最小限度地传递字段名称和值

<?php

echo form_input('username', 'johndoe');
/*
 * Would produce:
 * <input type="text" name="username" value="johndoe">
 */

或者您可以传递一个关联数组，其中包含您希望表单包含的任何数据

<?php

$data = [
    'name'      => 'username',
    'id'        => 'username',
    'value'     => 'johndoe',
    'maxlength' => '100',
    'size'      => '50',
    'style'     => 'width:50%',
];
echo form_input($data);
/*
 * Would produce:
 * <input type="text" name="username" value="johndoe" id="username" maxlength="100" size="50" style="width:50%">
 */

如果您想要布尔属性，请传递布尔值 (true/false)。在这种情况下，布尔值无关紧要

<?php

$data = [
    'name'     => 'username',
    'id'       => 'username',
    'value'    => '',
    'required' => true,
];
echo form_input($data);
/*
 * Would produce:
 * <input type="text" name="username" value="" id="username" required>
 */

如果您希望表单包含一些附加数据，例如 JavaScript，您可以将其作为字符串传递给第三个参数

<?php

$js = 'onClick="some_function ()"';
echo form_input('username', 'johndoe', $js);
/*
 * Would produce:
 * <input type="text" name="username" value="johndoe" onClick="some_function ()">
 */

或者您可以将其作为数组传递

<?php

$js = ['onClick' => 'some_function ();'];
echo form_input('username', 'johndoe', $js);
/*
 * Would produce:
 * <input type="text" name="username" value="johndoe" onClick="some_function ();">
 */

为了支持扩展的 HTML5 输入字段范围，您可以将输入类型作为第四个参数传递

<?php

echo form_input('email', '[email protected]', ['placeholder' => 'Email Address...'], 'email');
/*
 * Would produce:
 * <input type="email" name="email" value="[email protected]" placeholder="Email Address...">
 */

form_password([$data = ''[, $value = ''[, $extra = '']]])

参数:

$data (array) – 字段属性数据
$value (string) – 字段值
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串

返回值:

一个 HTML 密码输入字段标签

返回类型:

string

此函数在所有方面都与上面的 form_input() 函数相同，只是它使用“password”输入类型。

form_upload([$data = ''[, $value = ''[, $extra = '']]])

参数:

$data (array) – 字段属性数据
$value (string) – 字段值
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串

返回值:

一个 HTML 文件上传输入字段标签

返回类型:

string

此函数在所有方面都与上面的 form_input() 函数相同，只是它使用“文件”输入类型，允许它用于上传文件。

form_textarea([$data = ''[, $value = ''[, $extra = '']]])

参数:

$data (array) – 字段属性数据
$value (string) – 字段值
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串

返回值:

一个 HTML textarea 标签

返回类型:

string

此函数在所有方面都与上面的 form_input() 函数相同，只是它生成一个“textarea”类型。

注意

与上面的示例中的 maxlength 和 size 属性不同，您将改为指定 rows 和 cols。

form_dropdown([$name = ''[, $options = [][, $selected = [][, $extra = '']]]])

参数:

$name (string) – 字段名称
$options (array) – 要列出的选项的关联数组
$selected (array) – 要标记为 selected 属性的字段列表
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串

返回值:

一个 HTML 下拉选择字段标签

返回类型:

string

允许您创建一个标准的下拉字段。第一个参数将包含字段的名称，第二个参数将包含选项的关联数组，第三个参数将包含您希望被选中的值。您也可以通过第三个参数传递多个项目的数组，助手将为您创建一个多选。

示例

<?php

$options = [
    'small'  => 'Small Shirt',
    'med'    => 'Medium Shirt',
    'large'  => 'Large Shirt',
    'xlarge' => 'Extra Large Shirt',
];

$shirts_on_sale = ['small', 'large'];
echo form_dropdown('shirts', $options, 'large');
/*
 * Would produce:
 * <select name="shirts">
 *     <option value="small">Small Shirt</option>
 *     <option value="med">Medium Shirt</option>
 *     <option value="large" selected="selected">Large Shirt</option>
 *     <option value="xlarge">Extra Large Shirt</option>
 * </select>
 */

echo form_dropdown('shirts', $options, $shirts_on_sale);
/*
 * Would produce:
 * <select name="shirts" multiple="multiple">
 *     <option value="small" selected="selected">Small Shirt</option>
 *     <option value="med">Medium Shirt</option>
 *     <option value="large" selected="selected">Large Shirt</option>
 *     <option value="xlarge">Extra Large Shirt</option>
 * </select>
 */

如果您希望打开的 <select> 包含其他数据，例如 id 属性或 JavaScript，您可以将其作为字符串传递给第四个参数。

<?php

$js = 'id="shirts" onChange="some_function();"';
echo form_dropdown('shirts', $options, 'large', $js);

或者您可以将其作为数组传递

<?php

$js = [
    'id'       => 'shirts',
    'onChange' => 'some_function();',
];
echo form_dropdown('shirts', $options, 'large', $js);

如果作为 $options 传递的数组是多维数组，那么 form_dropdown() 将生成一个 <optgroup>，其数组键作为标签。

form_multiselect([$name = ''[, $options = [][, $selected = [][, $extra = '']]]])

参数:

$name (string) – 字段名称
$options (array) – 要列出的选项的关联数组
$selected (array) – 要标记为 selected 属性的字段列表
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串

返回值:

一个 HTML 下拉多选字段标签

返回类型:

string

允许您创建一个标准的多选字段。第一个参数将包含字段的名称，第二个参数将包含选项的关联数组，第三个参数将包含您希望选择的 value 或 values。

参数用法与使用上面的 form_dropdown() 相同，当然，字段的名称需要使用 POST 数组语法，例如 foo[]。

form_fieldset([$legend_text = ''[, $attributes = []]])

参数:

$legend_text (string) – 要放在 <legend> 标签中的文本
$attributes (array) – 要设置在 <fieldset> 标签上的属性

返回值:

一个 HTML fieldset 开启标签

返回类型:

string

允许您生成 fieldset/legend 字段。

示例

<?php

echo form_fieldset('Address Information');
echo "<p>fieldset content here</p>\n";
echo form_fieldset_close();

?>

<!-- Produces: -->
<fieldset>
    <legend>Address Information</legend>
    <p>form content here</p>
</fieldset>

与其他函数类似，如果您希望设置其他属性，可以在第二个参数中提交一个关联数组。

<?php

$attributes = [
    'id'    => 'address_info',
    'class' => 'address_info',
];

echo form_fieldset('Address Information', $attributes);
echo "<p>fieldset content here</p>\n";
echo form_fieldset_close();

?>

<!-- Produces: -->
<fieldset id="address_info" class="address_info">
    <legend>Address Information</legend>
    <p>form content here</p>
</fieldset>

form_fieldset_close([$extra = ''])

参数:

$extra (string) – 要在结束标签后追加的任何内容，按原样

返回值:

一个 HTML fieldset 结束标签

返回类型:

string

生成一个闭合的 </fieldset> 标签。使用此函数的唯一优势是它允许您传递数据，这些数据将在标签下方添加。例如

<?php

$string = '</div></div>';
echo form_fieldset_close($string);
// Would produce: </fieldset></div></div>

form_checkbox([$data = ''[, $value = ''[, $checked = false[, $extra = '']]]])

参数:

$data (array) – 字段属性数据
$value (string) – 字段值
$checked (bool) – 是否将复选框标记为选中
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串

返回值:

一个 HTML 复选框输入标签

返回类型:

string

允许您生成一个复选框字段。简单示例

<?php

echo form_checkbox('newsletter', 'accept', true);
// Would produce:  <input type="checkbox" name="newsletter" value="accept" checked="checked">

第三个参数包含一个布尔值 true/false，用于确定是否应选中该框。

与该助手中的其他表单函数类似，您也可以将属性数组传递给该函数

<?php

$data = [
    'name'    => 'newsletter',
    'id'      => 'newsletter',
    'value'   => 'accept',
    'checked' => true,
    'style'   => 'margin:10px',
];

echo form_checkbox($data);
// Would produce: <input type="checkbox" name="newsletter" id="newsletter" value="accept" checked="checked" style="margin:10px">

同样，与其他函数一样，如果您希望标签包含其他数据（如 JavaScript），您可以将其作为字符串传递给第四个参数

<?php

$js = 'onClick="some_function()"';
echo form_checkbox('newsletter', 'accept', true, $js);

或者您可以将其作为数组传递

<?php

$js = ['onClick' => 'some_function();'];
echo form_checkbox('newsletter', 'accept', true, $js);

form_radio([$data = ''[, $value = ''[, $checked = false[, $extra = '']]]])

参数:

$data (array) – 字段属性数据
$value (string) – 字段值
$checked (bool) – 是否将单选按钮标记为选中
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串

返回值:

一个 HTML 单选按钮输入标签

返回类型:

string

此函数在所有方面都与上面的 form_checkbox() 函数相同，只是它使用“radio”输入类型。

form_label([$label_text = ''[, $id = ''[, $attributes = []]]])

参数:

$label_text (string) – 用于<label>标签的文本
$id (string) – 我们要为其创建标签的表单元素的ID
$attributes (string) – HTML属性

返回值:

一个HTML字段标签

返回类型:

string

允许您生成一个<label>。简单示例

<?php

echo form_label('What is your Name', 'username');
// Would produce:  <label for="username">What is your Name</label>

与其他函数类似，如果您希望设置其他属性，可以在第三个参数中提交一个关联数组。

示例

<?php

$attributes = [
    'class' => 'mycustomclass',
    'style' => 'color: #000;',
];

echo form_label('What is your Name', 'username', $attributes);
// Would produce:  <label for="username" class="mycustomclass" style="color: #000;">What is your Name</label>

form_submit([$data = ''[, $value = ''[, $extra = '']]])

参数:

$data (string) – 按钮名称
$value (string) – 按钮值
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串

返回值:

一个HTML输入提交标签

返回类型:

string

允许您生成一个标准的提交按钮。简单示例

<?php

echo form_submit('mysubmit', 'Submit Post!');
// Would produce:  <input type="submit" name="mysubmit" value="Submit Post!">

与其他函数类似，如果您希望设置自己的属性，可以在第一个参数中提交一个关联数组。第三个参数允许您向表单添加额外数据，例如JavaScript。

form_reset([$data = ''[, $value = ''[, $extra = '']]])

参数:

$data (string) – 按钮名称
$value (string) – 按钮值
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串

返回值:

HTML 表单重置按钮标签

返回类型:

string

用于生成标准重置按钮。用法与 form_submit() 相同。

form_button([$data = ''[, $content = ''[, $extra = '']]])

参数:

$data (string) – 按钮名称
$content (string) – 按钮标签
$extra (mixed) – 要添加到标签的额外属性，可以是数组或文字字符串

返回值:

HTML 按钮标签

返回类型:

string

用于生成标准按钮元素。您只需在第一个和第二个参数中传递按钮名称和内容即可。

<?php

echo form_button('name', 'content');
// Would produce: <button name="name" type="button">Content</button>

或者您可以传递一个关联数组，其中包含您希望表单包含的任何数据

<?php

$data = [
    'name'    => 'button',
    'id'      => 'button',
    'value'   => 'true',
    'type'    => 'reset',
    'content' => 'Reset',
];

echo form_button($data);
// Would produce: <button name="button" id="button" value="true" type="reset">Reset</button>

如果您希望表单包含一些附加数据，例如 JavaScript，您可以将其作为字符串传递给第三个参数

<?php

$js = 'onClick="some_function()"';
echo form_button('mybutton', 'Click Me', $js);

form_close([$extra = ''])

参数:

$extra (string) – 要在结束标签后追加的任何内容，按原样

返回值:

HTML 表单结束标签

返回类型:

string

生成一个结束的 </form> 标签。使用此函数的唯一优势是它允许您传递数据，这些数据将添加到标签下方。例如

<?php

$string = '</div></div>';
echo form_close($string);
// Would produce:  </form> </div></div>

set_value($field[, $default = ''[, $html_escape = true]])

参数:

$field (string) – 字段名称
$default (string) – 默认值
$html_escape (bool) – 是否关闭值的 HTML 转义

返回值:

字段值

返回类型:

string

允许您设置输入表单或文本区域的值。您必须通过函数的第一个参数提供字段名称。第二个（可选）参数允许您为表单设置默认值。第三个（可选）参数允许您关闭值的 HTML 转义，如果您需要将此函数与例如 form_input() 结合使用并避免双重转义。

示例

<input type="text" name="quantity" value="<?= set_value('quantity', '0') ?>" size="50">

上面的表单在第一次加载时将显示“0”。

set_select($field[, $value = ''[, $default = false]])

参数:

$field (string) – 字段名称
$value (string) – 要检查的值
$default (string) – 该值是否也是默认值

返回值:

‘selected’ 属性或空字符串

返回类型:

string

如果您使用 <select> 菜单，此函数允许您显示所选的菜单项。

第一个参数必须包含选择菜单的名称，第二个参数必须包含每个项目的 value，第三个（可选）参数允许您将一个项目设置为默认值（使用布尔值 true/false）。

示例

<select name="myselect">
    <option value="one" <?= set_select('myselect', 'one', true) ?>>One</option>
    <option value="two" <?= set_select('myselect', 'two') ?>>Two</option>
    <option value="three" <?= set_select('myselect', 'three') ?>>Three</option>
</select>

set_checkbox($field[, $value = ''[, $default = false]])

参数:

$field (string) – 字段名称
$value (string) – 要检查的值
$default (string) – 该值是否也是默认值

返回值:

‘checked’ 属性或空字符串

返回类型:

string

允许您以提交时的状态显示复选框。

第一个参数必须包含复选框的名称，第二个参数必须包含其值，第三个（可选）参数允许您将一个项目设置为默认值（使用布尔值 true/false）。

示例

<input type="checkbox" name="mycheck[]" value="1" <?= set_checkbox('mycheck', '1') ?>>
<input type="checkbox" name="mycheck[]" value="2" <?= set_checkbox('mycheck', '2') ?>>

set_radio($field[, $value = ''[, $default = false]])

参数:

$field (string) – 字段名称
$value (string) – 要检查的值
$default (string) – 该值是否也是默认值

返回值:

‘checked’ 属性或空字符串

返回类型:

string

允许您以提交时的状态显示单选按钮。此函数与上面的 set_checkbox() 函数相同。

示例

<input type="radio" name="myradio" value="1" <?= set_radio('myradio', '1', true) ?>>
<input type="radio" name="myradio" value="2" <?= set_radio('myradio', '2') ?>>

validation_errors()

版本 4.3.0 中新增。

返回值:: 验证错误
返回类型:: 数组

返回验证错误。首先，此函数检查存储在会话中的验证错误。要将错误存储在会话中，您需要使用 withInput() 与 redirect() 一起使用。

返回的数组与 Validation::getErrors() 相同。有关详细信息，请参阅 Validation。

注意

此函数不适用于模型内验证。如果您想在模型验证中获取验证错误，请参阅获取验证错误。

示例

<?php $errors = validation_errors(); ?>

validation_list_errors($template = 'list')

版本 4.3.0 中新增。

参数:

$template (string) – 验证模板名称

返回值:

验证错误的渲染 HTML

返回类型:

string

返回验证错误的渲染 HTML。

参数 $template 是一个验证模板名称。有关详细信息，请参阅自定义错误显示。

此函数在内部使用 validation_errors()。

注意

此函数不适用于模型内验证。如果您想在模型验证中获取验证错误，请参阅获取验证错误。

示例

<?= validation_list_errors() ?>

validation_show_error($field, $template = 'single')

版本 4.3.0 中新增。

参数:

$field (string) – 字段名称
$template (string) – 验证模板名称

返回值:

验证错误的渲染 HTML

返回类型:

string

返回指定字段的单个错误，以格式化的 HTML 格式。

参数 $template 是一个验证模板名称。有关详细信息，请参阅自定义错误显示。

此函数在内部使用 validation_errors()。

注意

此函数不适用于模型内验证。如果您想在模型验证中获取验证错误，请参阅获取验证错误。

示例

<?= validation_show_error('username') ?>

表单辅助函数

配置

加载此辅助函数

转义字段值

可用函数

配置 

加载此辅助函数 

转义字段值 

可用函数 