1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
|
<!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="../nav/nav.js"></script>
<script type="text/javascript" src="../scripts/prototype.lite.js"></script>
<script type="text/javascript" src="../nav/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.5.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> ›
<a href="../index.html">User Guide Home</a> ›
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 <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" /> <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><?=$this->validation->error_string; ?></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 (<p>) 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><div class="error"></kbd>', '<kbd></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 (<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"> </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"> </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"> </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"> </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"> </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"> </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: <a href="uri.html">URI Class</a>
·
<a href="#top">Top of Page</a> ·
<a href="../index.html">User Guide Home</a> ·
Next Topic: <a href="xmlrpc.html">XML-RPC Class</a>
<p>
<p><a href="http://www.codeigniter.com">Code Igniter</a> · Copyright © 2006 · <a href="http://www.pmachine.com">pMachine, Inc.</a></p>
</div>
</body>
</html>
|
