表单辅助函数

表单辅助函数文件包含了帮助处理表单的函数。

配置

从 v4.3.0 开始, form_helper 函数中的空 HTML 元素(如 <input>)默认为兼容 HTML5,如果你需要兼容 XHTML,必须在 app/Config/DocTypes.php 中将 $html5 属性设置为 false。

加载此辅助函数

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

<?php

helper('form');

转义字段值

你可能需要在表单元素中使用 HTML 和诸如引号之类的字符。为了安全地做到这一点,你需要使用 common function 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

创建一个开启的 form 标签，其 action 的 base 使用你的 Config\App::$baseURL 值。它将可选地允许你添加表单属性和隐藏输入字段，并且将始终根据你的 app/Config/App.php 配置文件中的 $charset 属性添加 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_test_name" value="964ede6e0ae8a680f7b8eab69136717d">

备注

要使用 CSRF 字段的自动生成，你需要打开 app/Config/Filters.php 文件中的 CSRF 过滤器。 在大多数情况下，表单页面是使用 GET 方法请求的。通常，POST/PUT/DELETE/PATCH 请求需要 CSRF 保护， 但即使是 GET 请求，对于显示表单的页面也必须启用 CSRF 过滤器。

如果你使用 $globals 启用 CSRF 过滤器，它将对所有请求类型生效。 但如果你使用 public array $methods = ['POST' => ['csrf']]; 启用 CSRF 过滤器，那么在 GET 请求中不会添加隐藏的 CSRF 字段。

添加隐藏输入字段

可以通过将关联数组作为第三个参数传递来添加隐藏字段,如下所示:

<?php

$hidden = ['username' => 'Joe', 'member_id' => '234'];
echo form_open('email/send', '', $hidden);

你可以通过向它传递任何 false 值来跳过第二个参数。

上面的示例将创建一个类似以下的表单:

<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 隐藏 input 元素

返回类型:

string

让你生成隐藏的输入字段。你可以提交名称/值字符串以创建一个字段:

<?php

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

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

<?php

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

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

你也可以将关联数组传递给值字段:

<?php

$data = [
    'name'  => 'John Doe',
    'email' => 'john@example.com',
    '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="john@example.com">
 * <input type="hidden" name="my_array[url]" value="http://example.com">
 */

如果你想要带有额外属性的隐藏输入字段:

<?php

$data = [
    'type'  => 'hidden',
    'name'  => 'email',
    'id'    => 'hiddenemail',
    'value' => 'john@example.com',
    'class' => 'hiddenemail',
];

echo form_input($data);
/*
 * Would produce:
 * <input type="hidden" name="email" value="john@example.com" id="hiddenemail" class="hiddenemail">
 */

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

参数:

• $data (array) – 字段属性数据

• $value (string) – 字段值

• $extra (mixed) – 要作为数组或字符串添加到标记的额外属性

• $type (string) – 输入字段的类型。即,’text’、’email’、’number’等

返回:

一个 HTML 文本 input 元素

返回类型:

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', 'joe@example.com', ['placeholder' => 'Email Address...'], 'email');
/*
 * Would produce:
 * <input type="email" name="email" value="joe@example.com" placeholder="Email Address...">
 */

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

参数:

• $data (array) – 字段属性数据

• $value (string) – 字段值

• $extra (mixed) – 要作为数组或字符串添加到标记的额外属性

返回:

一个 HTML 密码 input 元素

返回类型:

string

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

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

参数:

• $data (array) – 字段属性数据

• $value (string) – 字段值

• $extra (mixed) – 要作为数组或字符串添加到标记的额外属性

返回:

一个 HTML 文件上传 input 元素

返回类型:

string

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

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 select(下拉框) 元素

返回类型:

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 带有 multiple 属性的 select 元素

返回类型:

string

允许你创建一个标准的多选字段。第一个参数将包含字段的名称,第二个参数将包含选项的关联数组,第三个参数将包含你希望选中的值或值。

参数用法与使用上面的 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) – 是否将复选框标记为 checked

• $extra (mixed) – 要作为数组或字符串添加到标记的额外属性

返回:

一个 HTML 复选框 input 元素

返回类型:

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) – 是否将单选按钮标记为 checked

• $extra (mixed) – 要作为数组或字符串添加到标记的额外属性

返回:

一个 HTML 单选按钮 input 元素

返回类型:

string

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

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

参数:

• $label_text (string) – 要放入 <label> 标签中的文本

• $id (string) – 我们为其创建标签的表单元素的 ID

• $attributes (string) – HTML 属性

返回:

一个 HTML label 元素

返回类型:

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 提交 input 元素

返回类型:

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 reset input 元素

返回类型:

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

允许你设置输入表单或 textarea 元素的值。你必须通过函数的第一个参数提供字段名称。第二个(可选)参数允许你为字段设置默认值。第三个(可选)参数允许你关闭值的 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> 菜单,此函数允许你显示所选菜单项。

第一个参数必须包含选择菜单的名称,第二个参数必须包含每个项目的值,第三个(可选)参数允许你将某个项目设置为默认值(使用布尔值 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 版本加入.

返回:

验证错误

返回类型:

array

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

返回的数组与 Validation::getErrors() 相同。详见 验证。

备注

此函数与 模型内验证 不兼容。如果你想在模型验证中获取验证错误，请参阅 获取验证错误。

示例:

<?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') ?>