Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / b0dd10f8171945e0c1f3527dd1e9d18b043e01a7 / . / user_guide / libraries / validation.html
blob: 2489aa6e935ee88f478abcdd0aa01d779945995e [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Code Igniter User Guide</title>
<style type='text/css' media='all'>@import url('../userguide.css');</style>
<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
<script type="text/javascript" src="../scripts/nav.js"></script>
<script type="text/javascript" src="../scripts/prototype.lite.js"></script>
<script type="text/javascript" src="../scripts/moo.fx.js"></script>
<script type="text/javascript">
window.onload = function() {
myHeight = new fx.Height('nav', {duration: 400});
myHeight.hide();
}
</script>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv='expires' content='-1' />
<meta http-equiv= 'pragma' content='no-cache' />
<meta name='robots' content='all' />
<meta name='author' content='Rick Ellis' />
<meta name='description' content='Code Igniter User Guide' />
</head>
<body>
<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle.jpg" width="153" height="44" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>Code Igniter User Guide Version 1.4.0</h1></td>
<td id="breadcrumb_right"><a href="../toc.html">Full Table of Contents</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->
<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="http://www.codeigniter.com/">Code Igniter Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Form Validation
</td>
<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="www.codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
</tr>
</table>
<!-- END BREADCRUMB -->
<br clear="all" />
<!-- START CONTENT -->
<div id="content">
<h1>Form Validation</h1>
<p>Before explaining Code Igniter's approach to data validation, let's describe the ideal scenario:</p>
<ol>
<li>A form is displayed.</li>
<li>You fill it in and submit it.</li>
<li>If you submitted something invalid, or perhaps missed a required item, the form is redisplayed containing your data along with an error message describing the problem.</li>
<li>This process continues until you have submitted a valid form.</li>
</ol>
<p>On the receiving end, the script must:</p>
<ol>
<li>Check for required data.</li>
<li>Verify that the data is of the correct type, and meets the correct criteria. (For example, if a username is submitted
it must be validated to contain only permitted characters. It must be of a minimum length,
and not exceed a maximum length. The username can't be someone else's existing username, or perhaps even a reserved word. Etc.)
<li>Sanitize the data for security.</li>
<li>Pre-format the data if needed (Does the data need to be trimmed? HTML encoded? Etc.)</li>
<li>Prep the data for insertion in the database.</li>
</ol>
<p>Although there is nothing complex about the above process, it usually requires a significant
amount of code, and to display error messages, various control structures are usually placed within the form HTML.
Form validation, while simple to create, is generally very messy and tedious to implement.</p>
<dfn>Code Igniter provides a comprehensive validation framework that truly minimizes the amount of code you'll write.
It also removes all control structures from your form HTML, permitting it to be clean and free of code.</dfn>
<h2>Overview</h2>
<p>In order to implement Code Igniter's form validation you'll need three things:</p>
<ol>
<li>A <a href="../general/views.html">View</a> file containing the form.</li>
<li>A View file containing a "success" message to be displayed upon successful submission.</li>
<li>A <a href="../general/controllers.html">controller</a> function to receive and process the submitted data.</li>
</ol>
<p>Let's create those three things, using a member sign-up form as the example.</p>
<h2>The Form</h2>
<p>Using a text editor, create a form called <dfn>myform.php</dfn>. In it, place this code and save it to your <samp>applications/views/</samp>
folder:</p>
<textarea class="textarea" style="width:100%" cols="50" rows="30"><html>
<head>
<title>My Form</title>
</head>
<body>
<?=$this->validation->error_string; ?>
<?=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></textarea>
<h2>The Success Page</h2>
<p>Using a text editor, create a form called <dfn>formsuccess.php</dfn>. In it, place this code and save it to your <samp>applications/views/</samp>
folder:</p>
<textarea class="textarea" style="width:100%" cols="50" rows="14"><html>
<head>
<title>My Form</title>
</head>
<body>
<h3>Your form was successfully submitted!</h3>
<p><?=anchor('form', 'Try it again!'); ?></p>
</body>
</html></textarea>
<h2>The Controller</h2>
<p>Using a text editor, create a controller called <dfn>form.php</dfn>. In it, place this code and save it to your <samp>applications/controllers/</samp>
folder:</p>
<textarea class="textarea" style="width:100%" cols="50" rows="21"><?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');
}
}
}
?></textarea>
<h2>Try it!</h2>
<p>To try your form, visit your site using a URL similar to this one:</p>
<code>www.your-site.com/index.php/<var>form</var>/</code>
<p><strong>If you submit the form you should simply see the form reload. That's because you haven't set up any validation
rules yet, which we'll get to in a moment.</strong></p>
<h2>Explanation</h2>
<p>You'll notice several things about the above pages:</p>
<p>The <dfn>form</dfn> (myform.php) is a standard web form with a couple exceptions:</p>
<ol>
<li>It uses a <dfn>form helper</dfn> to create the form opening.
Technically, this isn't necessary. You could create the form using standard HTML. However, the benefit of using the helper
is that it generates the action URL for you, based on the URL in your config file. This makes your application more portable
and flexible in the event your URLs change.</li>
<li>At the top of the form you'll notice the following variable:
<code>&lt;?=$this->validation->error_string; ?&gt;</code>
<p>This variable will display any error messages sent back by the validator. If there are no messages it returns nothing.</p>
</li>
</ol>
<p>The <dfn>controller</dfn> (form.php) has one function: <dfn>index()</dfn>. This function initializes the validation class and
loads the <var>form helper</var> and <var>URL helper</var> used by your view files. It also <samp>runs</samp>
the validation routine. Based on
whether the validation was successful it either presents the form or the success page.</p>
<p><strong>Since you haven't told the validation class to validate anything yet, it returns "false" (boolean false) by default. The <samp>run()</samp>
function only returns "true" if it has successfully applied your rules without any of them failing.</strong></p>
<h2>Setting Validation Rules</h2>
<p>Code Igniter lets you set as many validation rules as you need for a given field, cascading them in order, and it even lets you prep and pre-process the field data
at the same time. Let's see it in action, we'll explain it afterwards.</p>
<p>In your <dfn>controller</dfn> (form.php), add this code just below the validation initialization function:</p>
<code>$rules['username'] = "required";<br />
$rules['password'] = "required";<br />
$rules['passconf'] = "required";<br />
$rules['email'] = "required";<br />
<br />
$this->validation->set_rules($rules);</code>
<p>Your controller should now look like this:</p>
<textarea class="textarea" style="width:100%" cols="50" rows="28"><?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');
}
}
}
?></textarea>
<p><dfn>Now submit the form with the fields blank and you should see the error message.
If you submit the form with all the fields populated you'll see your success page.</dfn></p>
<p class="important"><strong>Note:</strong> The form fields are not yet being re-populated with the data when
there is an error. We'll get to that shortly, once we're through explaining the validation rules.</p>
<h2>Changing the Error Delimiters</h2>
<p>By default, the system adds a paragraph tag (&lt;p&gt;) around each error message shown. You can easily change these delimiters with
this code, placed in your controller:</p>
<code>$this->validation->set_error_delimiters('<kbd>&lt;div class="error"></kbd>', '<kbd>&lt;/div></kbd>');</code>
<p>In this example, we've switched to using div tags.</p>
<h2>Cascading Rules</h2>
<p>Code Igniter lets you pipe multiple rules together. Let's try it. Change your rules array like this:</p>
<code>$rules['username'] = "required|min_length[5]|max_length[12]";<br />
$rules['password'] = "required|matches[passconf]";<br />
$rules['passconf'] = "required";<br />
$rules['email'] = "required|valid_email";</code>
<p>The above code requires that:</p>
<ol>
<li>The username field be no shorter than 5 characters and no longer than 12.</li>
<li>The password field must match the password confirmation field.</li>
<li>The email field must contain a valid email address.</li>
</ol>
<p>Give it a try!</p>
<p class="important"><strong>Note:</strong> There are numerous rules available which you can read about in the validation reference.</p>
<h2>Prepping Data</h2>
<p>In addition to the validation functions like the ones we used above, you can also prep your data in various ways.
For example, you can set up rules like this:
<code>$rules['username'] = "<kbd>trim</kbd>|required|min_length[5]|max_length[12]|<kbd>xss_clean</kbd>";<br />
$rules['password'] = "<kbd>trim</kbd>|required|matches[passconf]|<kbd>md5</kbd>";<br />
$rules['passconf'] = "<kbd>trim</kbd>|required";<br />
$rules['email'] = "<kbd>trim</kbd>|required|valid_email";</code>
<p>In the above, we are "trimming" the fields, converting the password to MD5, and running the username through
the "xss_clean" function, which removes malicious data.</p>
<p class="important"><strong>Any native PHP function that accepts one parameter can be used as a rule, like <dfn>htmlspecialchars</dfn>,
<dfn>trim</dfn>, <dfn>MD5</dfn>, etc.</strong></p>
<p><strong>Note:</strong> You will generally want to use the prepping functions <strong>after</strong>
the validation rules so if there is an error, the original data will be shown in the form.</p>
<h2>Callbacks: Your own Validation Functions</h2>
<p>The validation system supports callbacks to your own validation functions. This permits you to extend the validation class
to meet your needs. For example, if you need to run a database query to see if the user is choosing a unique username, you can
create a callback function that does that. Let's create a simple example.</p>
<p>In your controller, change the "username" rule to this:</p>
<code>$rules['username'] = "callback_username_check"; </code>
<p>Then add a new function called <dfn>username_check</dfn> to your controller. Here's how your controller should look:</p>
<textarea class="textarea" style="width:100%" cols="50" rows="44"><?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;
}
}
}
?></textarea>
<p>Reload your form and submit it with the word "test" as the username. You can see that the form field data was passed to your
callback function for you to process.</p>
<p><strong>To invoke a callback just put the function name in a rule, with "callback_" as the rule prefix.</strong></p>
<p>The error message was set using the <dfn>$this->validation->set_message</dfn> function.
Just remember that the message key (the first parameter) must match your function name.</p>
<p class="important"><strong>Note:</strong> You can apply your own custom error messages to any rule, just by setting the
message similarly. For example, to change the message for the "required" rule you will do this:</p>
<code>$this->validation->set_message('required', 'Your custom message here');</code>
<h2>Re-populating the form</h2>
<p>Thus far we have only been dealing with errors. It's time to repopulate the form field with the submitted data.
This is done similarly to your rules. Add the following code to your controller, just below your rules:</p>
<code>$fields['username'] = 'Username';<br />
$fields['password'] = 'Password';<br />
$fields['passconf'] = 'Password Confirmation';<br />
$fields['email'] = 'Email Address';<br />
<br />
$this->validation->set_fields($fields);</code>
<p>The array keys are the actual names of the form fields, the value represents the full name that you want shown in the
error message.</p>
<p>The index function of your controller should now look like this:</p>
<textarea class="textarea" style="width:100%" cols="50" rows="30">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');
}
}</textarea>
<p>Now open your <dfn>myform.php</dfn> view file and update the value in each field so that it has an object corresponding to its name:</p>
<textarea class="textarea" style="width:100%" cols="50" rows="30"><html>
<head>
<title>My Form</title>
</head>
<body>
<?=$this->validation->error_string; ?>
<?=form_open('form'); ?>
<h5>Username</h5>
<input type="text" name="username" value="<?=$this->validation->username;?>" size="50" />
<h5>Password</h5>
<input type="text" name="password" value="<?=$this->validation->password;?>" size="50" />
<h5>Password Confirm</h5>
<input type="text" name="passconf" value="<?=$this->validation->passconf;?>" size="50" />
<h5>Email Address</h5>
<input type="text" name="email" value="<?=$this->validation->email;?>" size="50" />
<div><input type="submit" value="Submit" /></div>
</form>
</body>
</html></textarea>
<p>Now reload your page and submit the form so that it triggers an error. Your form fields should be populated
and the error messages will contain a more relevant field name.</p>
<h2>Showing Errors Individually</h2>
<p>If you prefer to show an error message next to each form field, rather than as a list, you can change your form so that it looks like this:</p>
<textarea class="textarea" style="width:100%" cols="50" rows="20">
<h5>Username</h5>
<?=$this->validation->username_error; ?>
<input type="text" name="username" value="<?=$this->validation->username;?>" size="50" />
<h5>Password</h5>
<?=$this->validation->password_error; ?>
<input type="text" name="password" value="<?=$this->validation->password;?>" size="50" />
<h5>Password Confirm</h5>
<?=$this->validation->passconf_error; ?>
<input type="text" name="passconf" value="<?=$this->validation->passconf;?>" size="50" />
<h5>Email Address</h5>
<?=$this->validation->email_error; ?>
<input type="text" name="email" value="<?=$this->validation->email;?>" size="50" /></textarea>
<p>If there are no errors, nothing will be shown. If there is an error, the message will appear, wrapped in the delimiters you
have set (&lt;p> tags by default).</p>
<p class="important"><strong>Note: </strong>To display errors this way you must remember to set your fields using the <kbd>$this->validation->set_fields</kbd>
function described earlier. The errors will be turned into variables that have "_error" after your field name.
For example, your "username" error will be available at:<br /><dfn>$this->validation->username_error</dfn>.</p>
<h2>Rule Reference</h2>
<p>The following is a list of all the native rules that are available to use:</p>
<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
<tr>
<th>Rule</th>
<th>Parameter</th>
<th>Description</th>
<th>Example</th>
</tr><tr>
<td class="td"><strong>required</strong></td>
<td class="td">No</td>
<td class="td">Returns FALSE if the form element is empty.</td>
<td class="td">&nbsp;</td>
</tr><tr>
<td class="td"><strong>matches</strong></td>
<td class="td">Yes</td>
<td class="td">Returns FALSE if the form element does not match the one in the parameter.</td>
<td class="td">matches[form_item]</td>
</tr><tr>
<td class="td"><strong>min_length</strong></td>
<td class="td">Yes</td>
<td class="td">Returns FALSE if the form element is shorter then the parameter value.</td>
<td class="td">min_length[6]</td>
</tr><tr>
<td class="td"><strong>max_length</strong></td>
<td class="td">Yes</td>
<td class="td">Returns FALSE if the form element is longer then the parameter value.</td>
<td class="td">max_length[12]</td>
</tr><tr>
<td class="td"><strong>exact_length</strong></td>
<td class="td">Yes</td>
<td class="td">Returns FALSE if the form element is not exactly the parameter value.</td>
<td class="td">exact_length[8]</td>
</tr><tr>
<td class="td"><strong>alpha</strong></td>
<td class="td">No</td>
<td class="td">Returns FALSE if the form element contains anything other than alphabetical characters.</td>
<td class="td">&nbsp;</td>
</tr><tr>
<td class="td"><strong>alpha_numeric</strong></td>
<td class="td">No</td>
<td class="td">Returns FALSE if the form element contains anything other than alpha-numeric characters.</td>
<td class="td">&nbsp;</td>
</tr><tr>
<td class="td"><strong>alpha_dash</strong></td>
<td class="td">No</td>
<td class="td">Returns FALSE if the form element contains anything other than alpha-numeric characters, underscores or dashes.</td>
<td class="td">&nbsp;</td>
</tr><tr>
<td class="td"><strong>numeric</strong></td>
<td class="td">No</td>
<td class="td">Returns FALSE if the form element contains anything other than numeric characters.</td>
<td class="td">&nbsp;</td>
</tr><tr>
<td class="td"><strong>valid_email</strong></td>
<td class="td">No</td>
<td class="td">Returns FALSE if the form element does not contain a valid email address.</td>
<td class="td">&nbsp;</td>
</tr>
</table>
<p><strong>Note:</strong> These rules can also be called as discreet functions. For example:</p>
<code>$this->validation->required($string);</code>
<p class="important"><strong>Note:</strong> You can also use any native PHP functions that permit one parameter.</p>
<h2>Prepping Reference</h2>
<p>The following is a list of all the prepping functions that are available to use:</p>
<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
<tr>
<th>Name</th>
<th>Parameter</th>
<th>Description</th>
</tr><tr>
<td class="td"><strong>xss_clean</strong></td>
<td class="td">No</td>
<td class="td">Runs the data through the XSS filtering function, described in the <a href="input.html">Input Class</a> page.</td>
</tr><tr>
<td class="td"><strong>prep_for_form</strong></td>
<td class="td">No</td>
<td class="td">Converts special characters so that HTML data can be shown in a form field without breaking it.</td>
</tr><tr>
<td class="td"><strong>prep_url</strong></td>
<td class="td">No</td>
<td class="td">Adds "http://" to URLs if missing.</td>
</tr><tr>
<td class="td"><strong>strip_image_tags</strong></td>
<td class="td">No</td>
<td class="td">Strips the HTML from image tags leaving the raw URL.</td>
</tr><tr>
<td class="td"><strong>encode_php_tags</strong></td>
<td class="td">No</td>
<td class="td">Converts PHP tags to entities.</td>
</tr>
</table>
<p class="important"><strong>Note:</strong> You can also use any native PHP functions that permit one parameter,
like <kbd>trim</kbd>, <kbd>htmlspecialchars</kbd>, <kbd>urldecode</kbd>, etc.</p>
<h2>Setting Custom Error Messages</h2>
<p>All of the native error messages are located in the following language file: <dfn>language/english/validation_lang.php</dfn></p>
<p>To set your own custom message you can either edit that file, or use the following function:</p>
<code>$this->validation->set_message('<var>rule</var>', '<var>Error Message</var>');</code>
<p>Where <var>rule</var> corresponds to the name of a particular rule, and <var>Error Message</var> is the text you would like displayed.</p>
</div>
<!-- END CONTENT -->
<div id="footer">
<p>
Previous Topic:&nbsp;&nbsp;<a href="uri.html">URI Class</a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href="xmlrpc.html">XML-RPC Class</a>
<p>
<p><a href="http://www.codeigniter.com">Code Igniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 &nbsp;&middot;&nbsp; <a href="http://www.pmachine.com">pMachine, Inc.</a></p>
</div>
</body>
</html>