# CodeIgniter 用户指南 版本 2.2.0

编辑文档、查看近期更改请 登录 或 注册 找回密码

搜索用户指南

查看原文

这个类库已经废弃掉了。鼓励使用 form_validation 类库。

# 表单验证

在解释CodeIgniter的数据验证前，让我们先描述下理想情况：

1. 显示一个表单；
2. 你填写文字并点击提交按钮；
3. 如果你提交的东西是残缺的，又或者漏填了必须填写的项，表单重新显示并包含你提交数据的一条错误信息；
4. 这个过程继续，直到你提交了正确的信息

在这个过程中，程序必须：

1. 检查必须的数据。
2. 校验数据的格式是否正确，是否符合标准(比如，如果提交用户名，那么必须只能包含有效的字符。必须有最小的长度，并且不能超过允许的长度。 用户名不可以与已有用户名重复，或者不能为保留字，等等。 Etc.)
3. 处理数据使之更安全。
4. 需要的情况下预格式化数据（数据需要进行剪裁，HTML格式化？等等）。
5. 准备数据，写入数据库。

尽管上面的过程没有什么复杂的地方，但这通常需要一定数量的代码来提交错误信息，各种控制结构放置在HTML文件里。 创建简单表单验证，代码通常会非常凌乱而效能地下。

CodeIgniter提供了一个全面的解决框架，真正的精简你需要写的代码数量。当然也可以从你的HTML表单中分离出控制结构，使得它成为干净而灵活的代码。

## 预览

为了能使用CodeIgniter的表单验证功能，你需要做以下三件事情：

1. 一个包含表单的 视图 文件。
2. 一个包含提交“成功”信息的视图文件。
3. 一个控制器函数，用来接受和处理提交的数据。

让我们创建这三个事件，使用注册表单作为样例：

## 表单页

使用一个文本编辑器，创建一个名叫myform.php的文件。在文中写入如下代码并保存到`applications/views/` 文件夹下:

<html> <head> <title>My Form</title> </head> <body> <?php echo $this->validation->error_string; ?> <?php echo form_open('form'); ?> <h5>Username</h5> <input type="text" name="username" value="" size="50" /> <h5>Password</h5> <input type="text" name="password" value="" size="50" /> <h5>Password Confirm</h5> <input type="text" name="passconf" value="" size="50" /> <h5>Email Address</h5> <input type="text" name="email" value="" size="50" /> <div><input type="submit" value="Submit" /></div> </form> </body> </html>

## 成功页

使用一个文本编辑器，创建一个名叫 formsuccess.php的文件。在文中写入如下代码并保存到`applications/views/` 文件夹下:

<html> <head> <title>My Form</title> </head> <body> <h3>Your form was successfully submitted!</h3> <p><?php echo anchor('form', 'Try it again!'); ?></p> </body> </html>

## 控制器页

使用一个文本编辑器，创建一个名叫 form.php的文件。在文中写入如下代码并保存到`applications/controllers/` 文件夹下:

<?php class Form extends Controller { function index() { $this->load->helper(array('form', 'url')); $this->load->library('validation'); if ($this->validation->run() == FALSE) { $this->load->view('myform'); } else { $this->load->view('formsuccess'); } } } ?>

## 试一试！

用与下面相似的URL地址测试下你的表单：

`example.com/index.php/form/`

如果你提交了表单，你会发现表单重载了。那是因为你还没有设置任何验证条件，这就是我们接下来要做的。

## 说明：

你会注意到一些关于上面页面的事情：

那个 页面 (myform.php) 是一个除了两个例外的标准页面：

1. 它使用一个表单助手 来创建表单to create the form opening. 从技术上讲，这是没有必要的。你可以用标准的HTML来创建表单。然而，使用这个助手的好处在于： 它为你生成了一个段URL，就是你在CONFIG文件里定义的那个。这使得你的程序在修改时可以更简单和灵活。
2. 在表单的顶部，你会注意到一下的不同点： `<?php echo $this->validation->error_string; ?>`

   验证类会使用这个变量返回并显示一些错误信息。如果没有信息将没有返回值。

这个控制器 (form.php) 有一个函数： index(). 这个函数初始化验证类并加载你的视图文件需要使用的 form helper 和 URL helper 。 当然也 `运行` 验证过程。这取决于验证是否成功，既不显示表单也没有返回成功信息。

如果还没有告诉验证类使之生效的信息，它会一直返回“FALSE”(布尔值 FALSE)作为默认值。如果数据成功地接受你的条件并且它们没有任何错误，那么`run()` 函数值返回“TRUE”。

## 设置验证条件

CodeIgniter可以让你设置任意数量的条件来控制给定的范围，循环，甚至同时它可以让你准备并预处理数据。让我们先看看它的用法，我们后面再具体解释。

在你的控制器 (form.php)里, 仅加入下面的初始化函数：

`$rules['username'] = "required";
$rules['password'] = "required";
$rules['passconf'] = "required";
$rules['email'] = "required";
$this->validation->set_rules($rules);`

你的控制器现在看起来像下面这样：

<?php class Form extends Controller { function index() { $this->load->helper(array('form', 'url')); $this->load->library('validation'); $rules['username'] = "required"; $rules['password'] = "required"; $rules['passconf'] = "required"; $rules['email'] = "required"; $this->validation->set_rules($rules); if ($this->validation->run() == FALSE) { $this->load->view('myform'); } else { $this->load->view('formsuccess'); } } } ?>

现在提交空白的表单,你将会看到错误信息。如果你提交的表单包含有完全正确的信息，你将看到你的成功页。

注意： 当表单数据有错误时，它不会被重新填充。当我们讲明验证规则后，马上回来解释它。

## 改变出错信息的样式

默认情况下，系统会为每个错误提示信息添加一个段落的标识(<p>)。你可以很容易地通过编码去改变这些界定符号，在控制器里写入一下代码:

`$this->validation->set_error_delimiters('`<div class="error">`', '`</div>`');`

在这个例子中，我们将其改成了 div 标签。

## 顺序编排规则

CodeIgniter可以让你把所有的验证条件有序地串联起来。我们来试一下。把你的验证条件数据改成下面的样子：

`$rules['username'] = "required|min_length[5]|max_length[12]";
$rules['password'] = "required|matches[passconf]";
$rules['passconf'] = "required";
$rules['email'] = "required|valid_email";`

以上代码要求如下:

1. username区域要求在5位到12位之间.
2. password 区域必须和 password confirmation 区域匹配.
3. Email 区域 必须包含一个合法的Email地址.

尽管尝试下吧!

请注意: 如果你阅读最后的“规则参考”(Rule Reference)，你会发现有很多可用的规则！

## 准备数据

在验证函数的基础上，你可以使用不同的方法准备好你的数据，例如，你可以建立这样的规则：

`$rules['username'] = "`trim`|required|min_length[5]|max_length[12]|`xss_clean`";
$rules['password'] = "`trim`|required|matches[passconf]|`md5`";
$rules['passconf'] = "`trim`|required";
$rules['email'] = "`trim`|required|valid_email";`

上面的例子中，我们“修剪”内容，转换密码区域为 MD5 编码，通过“XSS_CLEAN”函数检测用户名，移除危险的数据。

默认的PHP函数能为一个规则使用一个参数，像 htmlspecialchars, trim, MD5, 等等.

Note: You will generally want to use the prepping functions after the validation rules so if there is an error, the original data will be shown in the form.

## 回调函数：你自己的验证函数

验证系统支持回调你自己的验证函数. 这允许你通过扩展验证类来适应自己的需要. 例如, 如果你需要执行一个数据库查询来查看用户是否选择了唯一的用户名，你可以通过创建一个回调函数来做这件事. 让我们创建一个简单的例子.

在你的控制器中将username规则改为:

`$rules['username'] = "callback_username_check";`

然后在你的控制器中添加一个新的函数叫做 username_check . 你的控制器看起来应该像下面的例子:

<?php class Form extends Controller { function index() { $this->load->helper(array('form', 'url')); $this->load->library('validation'); $rules['username'] = "callback_username_check"; $rules['password'] = "required"; $rules['passconf'] = "required"; $rules['email'] = "required"; $this->validation->set_rules($rules); if ($this->validation->run() == FALSE) { $this->load->view('myform'); } else { $this->load->view('formsuccess'); } } function username_check($str) { if ($str == 'test') { $this->validation->set_message('username_check', 'The %s field can not be the word "test"'); return FALSE; } else { return TRUE; } } } ?>

重新载入表单并以"test"做为用户名提交. 你可以看到表单中的数据已经发送到你的回调函数中处理.

要想回调一个函数只需在你定义的函数名前加上一个"callback_"前缀即可.

错误消息可以使用 $this->validation->set_message 函数来设置. 请牢记消息键（第一个参数）必须与您的函数名相匹配.

注意: 你可以在任何规则中使用你自定义的错误消息, 只需设置类似的消息. 例如,为"required"规则改变消息你可以这样做:

`$this->validation->set_message('required', 'Your custom message here');`

## 填充表单

我们花了不少时间处理错误。现在是讨论使用数据重新填充表单的时候了。这里的做法和你的验证规则类似。在你的验证规则下面加入如下代码：

`$fields['username'] = 'Username';
$fields['password'] = 'Password';
$fields['passconf'] = 'Password Confirmation';
$fields['email'] = 'Email Address';
$this->validation->set_fields($fields);`

数组的关键字实际上是表单域的名字，对应的值是你想要在错误信息中显示的全名。

现在你控制器中的index函数看起来应该像这样：

function index() { $this->load->helper(array('form', 'url')); $this->load->library('validation'); $rules['username'] = "required"; $rules['password'] = "required"; $rules['passconf'] = "required"; $rules['email'] = "required"; $this->validation->set_rules($rules); $fields['username'] = 'Username'; $fields['password'] = 'Password'; $fields['passconf'] = 'Password Confirmation'; $fields['email'] = 'Email Address'; $this->validation->set_fields($fields); if ($this->validation->run() == FALSE) { $this->load->view('myform'); } else { $this->load->view('formsuccess'); } }

现在打开你的视图文件myform.php，根据每个表单域的名字更新它们的值。

<html> <head> <title>My Form</title> </head> <body> <?=$this->validation->error_string; ?> <?php echo form_open('form'); ?> <h5>Username</h5> <input type="text" name="username" value="<?php echo $this->validation->username;?>" size="50" /> <h5>Password</h5> <input type="text" name="password" value="<?php echo $this->validation->password;?>" size="50" /> <h5>Password Confirm</h5> <input type="text" name="passconf" value="<?php echo $this->validation->passconf;?>" size="50" /> <h5>Email Address</h5> <input type="text" name="email" value="<?php echo $this->validation->email;?>" size="50" /> <div><input type="submit" value="Submit" /></div> </form> </body> </html>

现在重新加载你的页面，提交表单并触发一个错误。你的表单将会被重新填充而且错误信息也会包含更多相关的表单域的名字。

## 单独显示错误

如果你想要在每个表单域旁显示错误，而不是显示一个错误列表，你可以像这样修改你的表单：

<h5>Username</h5> <?php echo $this->validation->username_error; ?> <input type="text" name="username" value="<?php echo $this->validation->username;?>" size="50" /> <h5>Password</h5> <?php echo $this->validation->password_error; ?> <input type="text" name="password" value="<?php echo $this->validation->password;?>" size="50" /> <h5>Password Confirm</h5> <?php echo $this->validation->passconf_error; ?> <input type="text" name="passconf" value="<?php echo $this->validation->passconf;?>" size="50" /> <h5>Email Address</h5> <?php echo $this->validation->email_error; ?> <input type="text" name="email" value="<?php echo $this->validation->email;?>" size="50" />

如果没有错误，不会显示任何东西。如果有错误发生，消息将会使用你设置的分割标记显示(<p> 标记是默认值)。

Note: 要这样显示错误信息，你必须之前使用`$this->validation->set_fields` 函数描述。错误将会被转换成表单域名加"_error"后缀的变量。例如，你的用户名错误的值可以这样访问：
$this->validation->username_error.

## 规则参考

下面是可用的原生规则列表：

Rule | Parameter | Description | Example
--- | --- | --- | ---
required | No | Returns FALSE if the form element is empty. |
matches | Yes | Returns FALSE if the form element does not match the one in the parameter. | matches[form_item]
min_length | Yes | Returns FALSE if the form element is shorter then the parameter value. | min_length[6]
max_length | Yes | Returns FALSE if the form element is longer then the parameter value. | max_length[12]
exact_length | Yes | Returns FALSE if the form element is not exactly the parameter value. | exact_length[8]
alpha | No | Returns FALSE if the form element contains anything other than alphabetical characters. |
alpha_numeric | No | Returns FALSE if the form element contains anything other than alpha-numeric characters. |
alpha_dash | No | Returns FALSE if the form element contains anything other than alpha-numeric characters, underscores or dashes. |
numeric | No | Returns FALSE if the form element contains anything other than numeric characters. |
integer | No | Returns FALSE if the form element contains anything other than an integer. |
valid_email | No | Returns FALSE if the form element does not contain a valid email address. |
is_natural | No | 如果为非整数(自然数) 则 Returns FALSE (注意 CI 1.7x版 新增, CI 1.6x不能使用该验证规则) |
is_natural_no_zero | No | 如果为非正整数(自然数) 则 Returns FALSE (注意 CI 1.7x版 新增, CI 1.6x不能使用该验证规则) |
valid_ip | No | Returns FALSE if the supplied IP is not valid. |
valid_base64 | No | Returns FALSE if the supplied string contains anything other than valid Base64 characters. |

Note: 这些规则也可以像独立的函数一样被调用。例如：

`$this->validation->required($string);`

Note: 你也可以使用接受一个参数的PHP原生函数。

## Prepping Reference

下面是所有可用的预处理函数列表

Name | Parameter | Description
--- | --- | ---
xss_clean | No | Runs the data through the XSS filtering function, described in the Input Class page.
prep_for_form | No | Converts special characters so that HTML data can be shown in a form field without breaking it.
prep_url | No | Adds "http://" to URLs if missing.
strip_image_tags | No | Strips the HTML from image tags leaving the raw URL.
encode_php_tags | No | Converts PHP tags to entities.

Note: 你也可以,使用接收一个参数的PHP原生函数，例如`trim`, `htmlspecialchars`, `urldecode`，等等。

## 设置自定义错误信息

所有的原生错误信息防止在下面的语言文件中：language/english/validation_lang.php

你可以编辑这个文件，或使用如下函数设置你自己的信息。

`$this->validation->set_message('rule', 'Error Message');`

rule是特定规则的名字，Error Message是你想要显示的信息。

## 处理选择菜单，单选按钮，和复选框

如果你使用了选择菜单，单选按钮，和复选框，你会想在出错时保持原先的选择。验证类有三个函数帮助你完成这些：

## set_select()

允许你显示和提交时状态一致的菜单项。第一个参数是选择菜单的名字，第二个参数必须包含每个选项的值。例如：

`<select name="myselect">
<option value="one" <?php echo $this->validation->set_select('myselect', 'one'); ?> >One</option>
<option value="two" <?php echo $this->validation->set_select('myselect', 'two'); ?> >Two</option>
<option value="three" <?php echo $this->validation->set_select('myselect', 'three'); ?> >Three</option>
</select>`

## set_checkbox()

允许你显示和提交时状态一致的复选框。第一个参数是复选框的名字，第二个参数必须包含它的值，例如：

`<input type="checkbox" name="mycheck" value="1" <?php echo $this->validation->set_checkbox('mycheck', '1'); ?> />`

## set_radio()

允许你显示和提交时状态一致的单选按钮。第一个参数是单选按钮的名字，第二个参数必须包含它的值：例如：

`<input type="radio" name="myradio" value="1" <?php echo $this->validation->set_radio('myradio', '1'); ?> />`

翻译贡献者: Hex, lishen2, lomatus, shnwqshnwq, tanqimin, wjm7301, yz20sui
最后修改: 2009-09-12 15:36:46