Blame - user_guide/libraries/form_validation.html - code-igniter-v3-giggi

<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="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>

47

</tr>

48

</table>

49

55

56

57

<h1>Form Validation</h1>

58

59

<p>CodeIgniter provides a comprehensive form validation and data prepping class that helps minimize the amount of code you'll write.</p>

60

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

61

<ul>

62

<li><a href="#overview">Overview</a></li>

63

<li><a href="#tutorial">Form Validation Tutorial</a>

<ul>

<li><a href="#thesuccesspage">The Success Page</a></li>

68

<li><a href="#thecontroller">The Controller</a></li>

69

<li><a href="#validationrules">Setting Validation Rules</a></li>

70

<li><a href="#validationrulesasarray">Setting Validation Rules Using an Array</a></li>

71

<li><a href="#cascadingrules">Cascading Rules</a></li>

72

<li><a href="#preppingdata">Prepping Data</a></li>

73

<li><a href="#repopulatingform">Re-populating the Form</a></li>

74

<li><a href="#callbacks">Callbacks</a></li>

75

<li><a href="#settingerrors">Setting Error Messages</a></li>

76

<li><a href="#errordelimiters">Changing the Error Delimiters</a></li>

77

<li><a href="#translatingfn">Translating Field Names</a></li>

78

<li><a href="#individualerrors">Showing Errors Individually</a></li>

79

<li><a href="#savingtoconfig">Saving Sets of Validation Rules to a Config File</a></li>

80

<li><a href="#arraysasfields">Using Arrays as Field Names</a></li>

81

</ul>

82

</li>

83

<li><a href="#rulereference">Rule Reference</a></li>

84

<li><a href="#preppingreference">Prepping Reference</a></li>

85

<li><a href="#functionreference">Function Reference</a></li>

86

<li><a href="#helperreference">Helper Reference</a></li>

</ul>

<h1>Overview</h1>

<p>Before explaining CodeIgniter's approach to data validation, let's describe the ideal scenario:</p>

102

103

<ol>

104

<li>A form is displayed.</li>

105

<li>You fill it in and submit it.</li>

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

106

<li>If you submitted something invalid, or perhaps missed a required item, the form is redisplayed containing your data

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

107

along with an error message describing the problem.</li>

108

<li>This process continues until you have submitted a valid form.</li>

109

</ol>

110

111

<p>On the receiving end, the script must:</p>

112

113

<ol>

114

<li>Check for required data.</li>

115

<li>Verify that the data is of the correct type, and meets the correct criteria. For example, if a username is submitted

116

it must be validated to contain only permitted characters. It must be of a minimum length,

117

and not exceed a maximum length. The username can't be someone else's existing username, or perhaps even a reserved word. Etc.</li>

118

<li>Sanitize the data for security.</li>

119

<li>Pre-format the data if needed (Does the data need to be trimmed? HTML encoded? Etc.)</li>

120

<li>Prep the data for insertion in the database.</li>

</ol>

<p>Although there is nothing terribly complex about the above process, it usually requires a significant

125

amount of code, and to display error messages, various control structures are usually placed within the form HTML.

126

Form validation, while simple to create, is generally very messy and tedious to implement.</p>

<h1>Form Validation Tutorial</h1>

133

134

<p>What follows is a "hands on" tutorial for implementing CodeIgniters Form Validation.</p>

135

136

137

<p>In order to implement form validation you'll need three things:</p>

138

139

<ol>

140

<li>A <a href="../general/views.html">View</a> file containing a form.</li>

141

<li>A View file containing a "success" message to be displayed upon successful submission.</li>

142

<li>A <a href="../general/controllers.html">controller</a> function to receive and process the submitted data.</li>

143

</ol>

144

145

<p>Let's create those three things, using a member sign-up form as the example.</p>

<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>

<head>

</head>

<body>

<?php echo validation_errors(); ?>

164

165

<?php echo form_open('form'); ?>

<h5>Username</h5>

<h5>Password</h5>

<h5>Password Confirm</h5>

174

175

176

<h5>Email Address</h5>

</form>

</body>

</html>

</textarea>

<h2>The Success Page</h2>

192

193

194

<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>

<html>

<head>

</head>

<body>

<h3>Your form was successfully submitted!</h3>

</body>

</html>

</textarea>

<h2>The Controller</h2>

217

218

<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

223

224

class Form extends Controller {

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

225

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

226

function index()

227

{

228

$this->load->helper(array('form', 'url'));

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

229

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

230

$this->load->library('form_validation');

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

231

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

232

if ($this->form_validation->run() == FALSE)

233

{

234

$this->load->view('myform');

}

else

{

$this->load->view('formsuccess');

}

}

}

?></textarea>

<p>To try your form, visit your site using a URL similar to this one:</p>

248

249

<code>example.com/index.php/<var>form</var>/</code>

250

251

<p><dfn>If you submit the form you should simply see the form reload. That's because you haven't set up any validation

252

rules yet.</dfn></p>

253

254

<p><strong>Since you haven't told the Form Validation class to validate anything yet, it returns <kbd>FALSE</kbd> (boolean false) by default. The <samp>run()</samp>

255

function only returns <kbd>TRUE</kbd> if it has successfully applied your rules without any of them failing.</strong></p>

<h2>Explanation</h2>

<p>You'll notice several things about the above pages:</p>

261

262

<p>The <dfn>form</dfn> (myform.php) is a standard web form with a couple exceptions:</p>

263

264

<ol>

265

<li>It uses a <dfn>form helper</dfn> to create the form opening.

266

Technically, this isn't necessary. You could create the form using standard HTML. However, the benefit of using the helper

267

is that it generates the action URL for you, based on the URL in your config file. This makes your application more portable in the event your URLs change.</li>

268

269

<li>At the top of the form you'll notice the following function call:

270

271

272

<p>This function will return any error messages sent back by the validator. If there are no messages it returns an empty string.</p>

</li>

</ol>

<p>The <dfn>controller</dfn> (form.php) has one function: <dfn>index()</dfn>. This function initializes the validation class and

277

loads the <var>form helper</var> and <var>URL helper</var> used by your view files. It also <samp>runs</samp>

278

the validation routine. Based on

279

whether the validation was successful it either presents the form or the success page.</p>

<h2>Setting Validation Rules</h2>

287

288

<p>CodeIgniter 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

289

at the same time. To set validation rules you will use the <dfn>set_rules()</dfn> function:</p>

290

291

<code>$this->form_validation->set_rules();</code>

292

293

<p>The above function takes <strong>three</strong> parameters as input:</p>

294

295

<ol>

296

<li>The field name - the exact name you've given the form field.</li>

297

<li>A "human" name for this field, which will be inserted into the error message. For example, if your field is named "user" you might give it a human name of "Username". <strong>Note:</strong> If you would like the field name to be stored in a language file, please see <a href="#translatingfn">Translating Field Names</a>.</li>

298

<li>The validation rules for this form field.</li>

</ol>

<p><br />Here is an example. In your <dfn>controller</dfn> (form.php), add this code just below the validation initialization function:</p>

303

304

<code>

305

$this->form_validation->set_rules('username', 'Username', 'required');<br />

306

$this->form_validation->set_rules('password', 'Password', 'required');<br />

307

$this->form_validation->set_rules('passconf', 'Password Confirmation', 'required');<br />

308

$this->form_validation->set_rules('email', 'Email', 'required');<br />

309

</code>

310

311

<p>Your controller should now look like this:</p>

312

Derek Allard

4b6d493

2008-12-07 17:04:56 +0000

[diff] [blame]

313

<textarea class="textarea" style="width:100%" cols="50" rows="28"><?php

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

314

315

class Form extends Controller {

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

316

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

317

function index()

318

{

319

$this->load->helper(array('form', 'url'));

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

320

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

321

$this->load->library('form_validation');

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

322

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

323

$this->form_validation->set_rules('username', 'Username', 'required');

324

$this->form_validation->set_rules('password', 'Password', 'required');

325

$this->form_validation->set_rules('passconf', 'Password Confirmation', 'required');

326

$this->form_validation->set_rules('email', 'Email', 'required');

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

327

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

328

if ($this->form_validation->run() == FALSE)

329

{

330

$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 messages.

341

If you submit the form with all the fields populated you'll see your success page.</dfn></p>

342

343

<p class="important"><strong>Note:</strong> The form fields are not yet being re-populated with the data when

344

there is an error. We'll get to that shortly.</p>

<h2>Setting Rules Using an Array</h2>

351

352

<p>Before moving on it should be noted that the rule setting function can be passed an array if you prefer to set all your rules in one action.

353

If you use this approach you must name your array keys as indicated:</p>

354

355

<code>

356

$config = array(<br />

357

               array(<br />

358

                     'field'   => 'username', <br />

359

                     'label'   => 'Username', <br />

360

                     'rules'   => 'required'<br />

361

                  ),<br />

362

               array(<br />

363

                     'field'   => 'password', <br />

364

                     'label'   => 'Password', <br />

365

                     'rules'   => 'required'<br />

366

                  ),<br />

367

               array(<br />

368

                     'field'   => 'passconf', <br />

369

                     'label'   => 'Password Confirmation', <br />

370

                     'rules'   => 'required'<br />

371

                  ),   <br />

372

               array(<br />

373

                     'field'   => 'email', <br />

374

                     'label'   => 'Email', <br />

375

                     'rules'   => 'required'<br />

376

                  )<br />

377

            );<br />

378

<br />

379

$this->form_validation->set_rules($config);

</code>

<h2>Cascading Rules</h2>

389

390

<p>CodeIgniter lets you pipe multiple rules together. Let's try it. Change your rules in the third parameter of rule setting function, like this:</p>

391

392

<code>

393

$this->form_validation->set_rules('username', 'Username', 'required|min_length[5]|max_length[12]');<br />

394

$this->form_validation->set_rules('password', 'Password', 'required|matches[passconf]');<br />

395

$this->form_validation->set_rules('passconf', 'Password Confirmation', 'required');<br />

396

$this->form_validation->set_rules('email', 'Email', 'required|valid_email');<br />

397

</code>

398

399

<p>The above code sets the following rules:</p>

400

401

<ol>

402

<li>The username field be no shorter than 5 characters and no longer than 12.</li>

403

<li>The password field must match the password confirmation field.</li>

404

<li>The email field must contain a valid email address.</li>

405

</ol>

406

407

<p>Give it a try! Submit your form without the proper data and you'll see new error messages that correspond to your new rules.

408

There are numerous rules available which you can read about in the validation reference.</p>

<h2>Prepping Data</h2>

414

415

<p>In addition to the validation functions like the ones we used above, you can also prep your data in various ways.

416

For example, you can set up rules like this:</p>

417

418

<code>

419

$this->form_validation->set_rules('username', 'Username', '<kbd>trim</kbd>|required|min_length[5]|max_length[12]|<kbd>xss_clean</kbd>');<br />

420

$this->form_validation->set_rules('password', 'Password', '<kbd>trim</kbd>|required|matches[passconf]|<kbd>md5</kbd>');<br />

421

$this->form_validation->set_rules('passconf', 'Password Confirmation', '<kbd>trim</kbd>|required');<br />

422

$this->form_validation->set_rules('email', 'Email', '<kbd>trim</kbd>|required|valid_email');<br />

</code>

<p>In the above example, we are "trimming" the fields, converting the password to MD5, and running the username through

427

the "xss_clean" function, which removes malicious data.</p>

428

429

<p><strong>Any native PHP function that accepts one parameter can be used as a rule, like <dfn>htmlspecialchars</dfn>,

430

431

432

<p><strong>Note:</strong> You will generally want to use the prepping functions <strong>after</strong>

433

the validation rules so if there is an error, the original data will be shown in the form.</p>

<h2>Re-populating the form</h2>

440

441

<p>Thus far we have only been dealing with errors. It's time to repopulate the form field with the submitted data. CodeIgniter offers several helper functions

442

that permit you to do this. The one you will use most commonly is:</p>

443

444

<code>set_value('field name')</code>

445

446

447

<p>Open your <dfn>myform.php</dfn> view file and update the <strong>value</strong> in each field using the <dfn>set_value()</dfn> function:</p>

448

Derek Allard

028cbb5

2010-01-17 08:07:49 +0000

[diff] [blame]

449

<p><strong>Don't forget to include each field name in the <dfn>set_value()</dfn> functions!</strong></p>

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

<html>

<head>

</head>

<body>

<?php echo validation_errors(); ?>

460

461

<?php echo form_open('form'); ?>

<h5>Username</h5>

<h5>Password</h5>

<h5>Password Confirm</h5>

470

471

472

<h5>Email Address</h5>

</form>

</body>

</html>

</textarea>

<p><dfn>Now reload your page and submit the form so that it triggers an error. Your form fields should now be re-populated</dfn></p>

485

486

<p class="important"><strong>Note:</strong> The <a href="#functionreference">Function Reference</a> section below contains functions that

487

permit you to re-populate <select> menus, radio buttons, and checkboxes.</p>

488

489

490

<p><strong>Important Note:</strong> If you use an array as the name of a form field, you must supply it as an array to the function. Example:</p>

491

492

<code><input type="text" name="<kbd>colors[]</kbd>" value="<?php echo set_value('<kbd>colors[]</kbd>'); ?>" size="50" /></code>

493

494

<p>For more info please see the <a href="#arraysasfields">Using Arrays as Field Names</a> section below.</p>

<h2>Callbacks: Your own Validation Functions</h2>

502

503

<p>The validation system supports callbacks to your own validation functions. This permits you to extend the validation class

504

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

505

create a callback function that does that. Let's create a example of this.</p>

506

507

<p>In your controller, change the "username" rule to this:</p>

508

509

<code>$this->form_validation->set_rules('username', 'Username', '<kbd>callback_username_check</kbd>');</code>

510

511

512

<p>Then add a new function called <dfn>username_check</dfn> to your controller. Here's how your controller should now look:</p>

513

514

Derek Allard

4b6d493

2008-12-07 17:04:56 +0000

[diff] [blame]

515

<textarea class="textarea" style="width:100%" cols="50" rows="44"><?php

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

516

517

class Form extends Controller {

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

518

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

519

function index()

520

{

521

$this->load->helper(array('form', 'url'));

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

522

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

523

$this->load->library('form_validation');

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

524

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

525

$this->form_validation->set_rules('username', 'Username', 'callback_username_check');

526

$this->form_validation->set_rules('password', 'Password', 'required');

527

$this->form_validation->set_rules('passconf', 'Password Confirmation', 'required');

528

$this->form_validation->set_rules('email', 'Email', 'required');

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

529

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

530

if ($this->form_validation->run() == FALSE)

531

{

532

$this->load->view('myform');

}

else

{

$this->load->view('formsuccess');

537

}

538

}

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

539

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

540

function username_check($str)

{

if ($str == 'test')

{

$this->form_validation->set_message('username_check', 'The %s field can not be the word "test"');

return FALSE;

}

else

{

return TRUE;

}

}

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

552

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

}

?></textarea>

<p><dfn>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

557

callback function for you to process.</dfn></p>

558

559

<p><strong>To invoke a callback just put the function name in a rule, with "callback_" as the rule prefix.</strong></p>

560

561

<p>You can also process the form data that is passed to your callback and return it. If your callback returns anything other than a boolean TRUE/FALSE

562

it is assumed that the data is your newly processed form data.</p>

<h2>Setting Error Messages</h2>

569

570

571

<p>All of the native error messages are located in the following language file: <dfn>language/english/form_validation_lang.php</dfn></p>

572

573

<p>To set your own custom message you can either edit that file, or use the following function:</p>

574

575

<code>$this->form_validation->set_message('<var>rule</var>', '<var>Error Message</var>');</code>

576

577

<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>

578

579

<p>If you include <dfn>%s</dfn> in your error string, it will be replaced with the "human" name you used for your field when you set your rules.</p>

580

581

<p>In the "callback" example above, the error message was set by passing the name of the function:</p>

582

583

<code>$this->form_validation->set_message('username_check')</code>

584

585

<p>You can also override any error message found in the language file. For example, to change the message for the "required" rule you will do this:</p>

586

587

<code>$this->form_validation->set_message('required', 'Your custom message here');</code>

<h2>Translating Field Names</h2>

593

594

<p>If you would like to store the "human" name you passed to the <dfn>set_rules()</dfn> function in a language file, and therefore make the name able to be translated, here's how:</p>

595

596

<p>First, prefix your "human" name with <dfn>lang:</dfn>, as in this example:</p>

597

598

<code>

599

$this->form_validation->set_rules('first_name', '<kbd>lang:</kbd>first_name', 'required');<br />

600

</code>

601

602

<p>Then, store the name in one of your language file arrays (without the prefix):</p>

603

604

<code>$lang['first_name'] = 'First Name';</code>

605

606

<p><strong>Note:</strong> If you store your array item in a language file that is not loaded automatically by CI, you'll need to remember to load it in your controller using:</p>

<p>See the <a href="language.html">Language Class</a> page for more info regarding language files.</p>

<h2>Changing the Error Delimiters</h2>

615

Barry Mieny

dd67197

2010-10-04 16:33:58 +0200

[diff] [blame]

616

<p>By default, the Form Validation class adds a paragraph tag (<p>) around each error message shown. You can either change these delimiters globally or

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

individually.</p>

<ol>

<li><strong>Changing delimiters Globally</strong>

622

623

<p>To globally change the error delimiters, in your controller function, just after loading the Form Validation class, add this:</p>

624

625

<code>$this->form_validation->set_error_delimiters('<kbd><div class="error"></kbd>', '<kbd></div></kbd>');</code>

626

627

<p>In this example, we've switched to using div tags.</p>

</li>

<li><strong>Changing delimiters Individually</strong>

632

633

<p>Each of the two error generating functions shown in this tutorial can be supplied their own delimiters as follows:</p>

</li>

</ol>

<h2>Showing Errors Individually</h2>

649

650

<p>If you prefer to show an error message next to each form field, rather than as a list, you can use the <dfn>form_error()</dfn> function.</p>

651

652

<p>Try it! Change your form so that it looks like this:</p>

<h5>Username</h5>

<?php echo form_error('username'); ?>

<h5>Password</h5>

<?php echo form_error('password'); ?>

661

662

663

<h5>Password Confirm</h5>

664

<?php echo form_error('passconf'); ?>

665

666

667

<h5>Email Address</h5>

668

<?php echo form_error('email'); ?>

</textarea>

<p>If there are no errors, nothing will be shown. If there is an error, the message will appear.</p>

673

674

<p><strong>Important Note:</strong> If you use an array as the name of a form field, you must supply it as an array to the function. Example:</p>

675

676

<code><?php echo form_error('<kbd>options[size]</kbd>'); ?><br />

677

<input type="text" name="<kbd>options[size]</kbd>" value="<?php echo set_value("<kbd>options[size]</kbd>"); ?>" size="50" />

678

</code>

679

680

<p>For more info please see the <a href="#arraysasfields">Using Arrays as Field Names</a> section below.</p>

<h1>Saving Sets of Validation Rules to a Config File</h1>

690

691

<p>A nice feature of the Form Validation class is that it permits you to store all your validation rules for your entire application in a config file. You

692

can organize these rules into "groups". These groups can either be loaded automatically when a matching controller/function is called, or

693

you can manually call each set as needed.</p>

694

695

<h3>How to save your rules</h3>

696

697

<p>To store your validation rules, simply create a file named <kbd>form_validation.php</kbd> in your <dfn>application/config/</dfn> folder.

698

In that file you will place an array named <kbd>$config</kbd> with your rules. As shown earlier, the validation array will have this prototype:</p>

699

700

<code>

701

$config = array(<br />

702

               array(<br />

703

                     'field'   => 'username', <br />

704

                     'label'   => 'Username', <br />

705

                     'rules'   => 'required'<br />

706

                  ),<br />

707

               array(<br />

708

                     'field'   => 'password', <br />

709

                     'label'   => 'Password', <br />

710

                     'rules'   => 'required'<br />

711

                  ),<br />

712

               array(<br />

713

                     'field'   => 'passconf', <br />

714

                     'label'   => 'Password Confirmation', <br />

715

                     'rules'   => 'required'<br />

716

                  ),   <br />

717

               array(<br />

718

                     'field'   => 'email', <br />

719

                     'label'   => 'Email', <br />

720

                     'rules'   => 'required'<br />

721

                  )<br />

            );<br />

</code>

<p><dfn>Your validation rule file will be loaded automatically and used when you call the run() function.</dfn></p>

726

727

<p class="important">Please note that you MUST name your array $config.</p>

728

729

<h3>Creating Sets of Rules</h3>

730

731

<p>In order to organize your rules into "sets" requires that you place them into "sub arrays". Consider the following example, showing two sets of rules.

732

We've arbitrarily called these two rules "signup" and "email". You can name your rules anything you want:</p>

733

734

735

<code>$config = array(<br />

736

                 '<kbd>signup</kbd>' => array(<br />

737

                                    array(<br />

738

                                            'field' => 'username',<br />

739

                                            'label' => 'Username',<br />

740

                                            'rules' => 'required'<br />

741

                                         ),<br />

742

                                    array(<br />

743

                                            'field' => 'password',<br />

744

                                            'label' => 'Password',<br />

745

                                            'rules' => 'required'<br />

746

                                         ),<br />

747

                                    array(<br />

748

                                            'field' => 'passconf',<br />

749

                                            'label' => 'PasswordConfirmation',<br />

750

                                            'rules' => 'required'<br />

751

                                         ),<br />

752

                                    array(<br />

753

                                            'field' => 'email',<br />

754

                                            'label' => 'Email',<br />

755

                                            'rules' => 'required'<br />

756

                                         )<br />

757

                                    ),<br />

758

                 '<kbd>email</kbd>' => array(<br />

759

                                    array(<br />

760

                                            'field' => 'emailaddress',<br />

761

                                            'label' => 'EmailAddress',<br />

762

                                            'rules' => 'required|valid_email'<br />

763

                                         ),<br />

764

                                    array(<br />

765

                                            'field' => 'name',<br />

766

                                            'label' => 'Name',<br />

767

                                            'rules' => 'required|alpha'<br />

768

                                         ),<br />

769

                                    array(<br />

770

                                            'field' => 'title',<br />

771

                                            'label' => 'Title',<br />

772

                                            'rules' => 'required'<br />

773

                                         ),<br />

774

                                    array(<br />

775

                                            'field' => 'message',<br />

776

                                            'label' => 'MessageBody',<br />

777

                                            'rules' => 'required'<br />

778

                                         )<br />

779

                                    )                          <br />

780

               );<br />

</code>

<h3>Calling a Specific Rule Group</h3>

785

786

<p>In order to call a specific group you will pass its name to the <kbd>run()</kbd> function. For example, to call the <kbd>signup</kbd> rule you will do this:</p>

787

788

<code>

789

if ($this->form_validation->run('<kbd>signup</kbd>') == FALSE)<br />

790

{<br />

791

   $this->load->view('myform');<br />

}<br />

else<br />

{<br />

   $this->load->view('formsuccess');<br />

}<br />

</code>

<h3>Associating a Controller Function with a Rule Group</h3>

802

803

<p>An alternate (and more automatic) method of calling a rule group is to name it according to the controller class/function you intend to use it with. For example, let's say you

804

have a controller named <kbd>Member</kbd> and a function named <kbd>signup</kbd>. Here's what your class might look like:</p>

<code>

<?php<br /><br />

class <kbd>Member</kbd> extends Controller {<br />

809

<br />

810

   function <kbd>signup</kbd>()<br />

811

   {      <br />

812

      $this->load->library('form_validation');<br />

813

            <br />

814

      if ($this->form_validation->run() == FALSE)<br />

815

      {<br />

816

         $this->load->view('myform');<br />

      }<br />

      else<br />

      {<br />

         $this->load->view('formsuccess');<br />

      }<br />

   }<br />

}<br />

?></code>

<p>In your validation config file, you will name your rule group <kbd>member/signup</kbd>:</p>

827

828

829

<code>$config = array(<br />

Derek Allard

03d783b

2009-05-03 19:45:45 +0000

[diff] [blame]

830

           '<kbd>member/signup</kbd>' => array(<br />

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

831

                                    array(<br />

832

                                            'field' => 'username',<br />

833

                                            'label' => 'Username',<br />

834

                                            'rules' => 'required'<br />

835

                                         ),<br />

836

                                    array(<br />

837

                                            'field' => 'password',<br />

838

                                            'label' => 'Password',<br />

839

                                            'rules' => 'required'<br />

840

                                         ),<br />

841

                                    array(<br />

842

                                            'field' => 'passconf',<br />

843

                                            'label' => 'PasswordConfirmation',<br />

844

                                            'rules' => 'required'<br />

845

                                         ),<br />

846

                                    array(<br />

847

                                            'field' => 'email',<br />

848

                                            'label' => 'Email',<br />

849

                                            'rules' => 'required'<br />

850

                                         )<br />

851

                                    )<br />

852

               );<br />

853

</code>

854

855

<p><dfn>When a rule group is named identically to a controller class/function it will be used automatically when the run() function is invoked from that class/function.</dfn></p>

<h1>Using Arrays as Field Names</h1>

862

863

<p>The Form Validation class supports the use of arrays as field names. Consider this example:</p>

864

865

<code><input type="text" name="<kbd>options[]</kbd>" value="" size="50" /></code>

866

867

<p>If you do use an array as a field name, you must use the EXACT array name in the <a href="#helperreference">Helper Functions</a> that require the field name,

868

and as your Validation Rule field name.</p>

869

870

<p>For example, to set a rule for the above field you would use:</p>

871

872

<code>$this->form_validation->set_rules('<kbd>options[]</kbd>', 'Options', 'required');</code>

873

874

<p>Or, to show an error for the above field you would use:</p>

875

876

<code><?php echo form_error('<kbd>options[]</kbd>'); ?></code>

877

878

<p>Or to re-populate the field you would use:</p>

879

880

<code><input type="text" name="<kbd>options[]</kbd>" value="<kbd><?php echo set_value('<kbd>options[]</kbd>'); ?></kbd>" size="50" /></code>

881

882

<p>You can use multidimensional arrays as field names as well. For example:</p>

883

884

<code><input type="text" name="<kbd>options[size]</kbd>" value="" size="50" /></code>

<code><input type="text" name="<kbd>sports[nba][basketball]</kbd>" value="" size="50" /></code>

889

890

<p>As with our first example, you must use the exact array name in the helper functions:</p>

891

892

<code><?php echo form_error('<kbd>sports[nba][basketball]</kbd>'); ?></code>

893

894

<p>If you are using checkboxes (or other fields) that have multiple options, don't forget to leave an empty bracket after each option, so that all selections will be added to the

POST array:</p>

<code>

<input type="checkbox" name="<kbd>options[]</kbd>" value="red" /><br />

899

<input type="checkbox" name="<kbd>options[]</kbd>" value="blue" /><br />

900

<input type="checkbox" name="<kbd>options[]</kbd>" value="green" />

901

</code>

902

903

<p>Or if you use a multidimensional array:</p>

904

905

<code>

906

<input type="checkbox" name="<kbd>options[color][]</kbd>" value="red" /><br />

907

<input type="checkbox" name="<kbd>options[color][]</kbd>" value="blue" /><br />

908

<input type="checkbox" name="<kbd>options[color][]</kbd>" value="green" />

909

</code>

910

911

<p>When you use a helper function you'll include the bracket as well:</p>

912

913

<code><?php echo form_error('<kbd>options[color][]</kbd>'); ?></code>

<h1>Rule Reference</h1>

923

924

<p>The following is a list of all the native rules that are available to use:</p>

<tr>

<th>Parameter</th>

<th>Description</th>

<th>Example</th>

</tr><tr>

<td class="td"><strong>required</strong></td>

937

938

<td class="td">Returns FALSE if the form element is empty.</td>

</tr><tr>

<td class="td"><strong>matches</strong></td>

943

944

<td class="td">Returns FALSE if the form element does not match the one in the parameter.</td>

945

<td class="td">matches[form_item]</td>

946

</tr><tr>

947

948

<td class="td"><strong>min_length</strong></td>

949

950

<td class="td">Returns FALSE if the form element is shorter then the parameter value.</td>

951

<td class="td">min_length[6]</td>

952

</tr><tr>

953

954

<td class="td"><strong>max_length</strong></td>

955

956

<td class="td">Returns FALSE if the form element is longer then the parameter value.</td>

957

<td class="td">max_length[12]</td>

958

</tr><tr>

959

960

<td class="td"><strong>exact_length</strong></td>

961

962

<td class="td">Returns FALSE if the form element is not exactly the parameter value.</td>

963

<td class="td">exact_length[8]</td>

964

</tr><tr>

965

966

<td class="td"><strong>alpha</strong></td>

967

968

<td class="td">Returns FALSE if the form element contains anything other than alphabetical characters.</td>

</tr><tr>

<td class="td"><strong>alpha_numeric</strong></td>

973

974

<td class="td">Returns FALSE if the form element contains anything other than alpha-numeric characters.</td>

</tr><tr>

<td class="td"><strong>alpha_dash</strong></td>

979

980

<td class="td">Returns FALSE if the form element contains anything other than alpha-numeric characters, underscores or dashes.</td>

</tr>

<tr>

<td class="td"><strong>numeric</strong></td>

986

987

<td class="td">Returns FALSE if the form element contains anything other than numeric characters.</td>

</tr>

<tr>

<td class="td"><strong>integer</strong></td>

993

994

<td class="td">Returns FALSE if the form element contains anything other than an integer.</td>

</tr>

<tr>

<td class="td"><strong>is_natural</strong></td>

1000

1001

<td class="td">Returns FALSE if the form element contains anything other than a natural number: 0, 1, 2, 3, etc.</td>

</tr>

<tr>

<td class="td"><strong>is_natural_no_zero</strong></td>

1007

1008

<td class="td">Returns FALSE if the form element contains anything other than a natural number, but not zero: 1, 2, 3, etc.</td>

</tr>

<tr>

<td class="td"><strong>valid_email</strong></td>

1014

1015

<td class="td">Returns FALSE if the form element does not contain a valid email address.</td>

</tr>

<tr>

<td class="td"><strong>valid_emails</strong></td>

1021

1022

<td class="td">Returns FALSE if any value provided in a comma separated list is not a valid email.</td>

</tr>

<tr>

<td class="td"><strong>valid_ip</strong></td>

1028

1029

<td class="td">Returns FALSE if the supplied IP is not valid.</td>

</tr>

<tr>

<td class="td"><strong>valid_base64</strong></td>

1035

1036

<td class="td">Returns FALSE if the supplied string contains anything other than valid Base64 characters.</td>

</tr>

</table>

<p><strong>Note:</strong> These rules can also be called as discrete functions. For example:</p>

1044

1045

<code>$this->form_validation->required($string);</code>

1046

1047

<p class="important"><strong>Note:</strong> You can also use any native PHP functions that permit one parameter.</p>

<h1>Prepping Reference</h1>

1055

1056

<p>The following is a list of all the prepping functions that are available to use:</p>

<tr>

<th>Parameter</th>

<th>Description</th>

</tr><tr>

<td class="td"><strong>xss_clean</strong></td>

1068

1069

<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">Converts special characters so that HTML data can be shown in a form field without breaking it.</td>

</tr><tr>

<td class="td">Adds "http://" to URLs if missing.</td>

1080

</tr><tr>

1081

1082

<td class="td"><strong>strip_image_tags</strong></td>

1083

1084

<td class="td">Strips the HTML from image tags leaving the raw URL.</td>

1085

</tr><tr>

1086

1087

<td class="td"><strong>encode_php_tags</strong></td>

1088

1089

<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,

1095

like <kbd>trim</kbd>, <kbd>htmlspecialchars</kbd>, <kbd>urldecode</kbd>, etc.</p>

<h1>Function Reference</h1>

1107

1108

<p>The following functions are intended for use in your controller functions.</p>

1109

Derek Allard

5115725

2009-02-04 12:34:07 +0000

[diff] [blame]

1110

<h2>$this->form_validation->set_rules();</h2>

Derek Allard

2067d1a

2008-11-13 22:59:24 +0000

[diff] [blame]

1111

1112

<p>Permits you to set validation rules, as described in the tutorial sections above:</p>

1113

1114

<ul>

1115

<li><a href="#validationrules">Setting Validation Rules</a></li>

1116

<li><a href="#savingtoconfig">Saving Groups of Validation Rules to a Config File</a></li>

</ul>

<h2>$this->form_validation->run();</h2>

1121

1122

<p>Runs the validation routines. Returns boolean TRUE on success and FALSE on failure. You can optionally pass the name of the validation

1123

group via the function, as described in: <a href="#savingtoconfig">Saving Groups of Validation Rules to a Config File</a>.</p>

1124

1125

1126

<h2>$this->form_validation->set_message();</h2>

1127

1128

<p>Permits you to set custom error messages. See <a href="#settingerrors">Setting Error Messages</a> above.</p>

<h1>Helper Reference</h1>

1135

1136

<p>The following helper functions are available for use in the view files containing your forms. Note that these are procedural functions, so they

1137

<strong>do not</strong> require you to prepend them with $this->form_validation.</p>

1138

1139

<h2>form_error()</h2>

1140

1141

<p>Shows an individual error message associated with the field name supplied to the function. Example:</p>

<p>The error delimiters can be optionally specified. See the <a href="#errordelimiters">Changing the Error Delimiters</a> section above.</p>

<h2>validation_errors()</h2>

1150

<p>Shows all error messages as a string: Example:</p>

<p>The error delimiters can be optionally specified. See the <a href="#errordelimiters">Changing the Error Delimiters</a> section above.</p>

<h2>set_value()</h2>

<p>Permits you to set the value of an input form or textarea. You must supply the field name via the first parameter of the function.

1161

The second (optional) parameter allows you to set a default value for the form. Example:</p>

<p>The above form will show "0" when loaded for the first time.</p>

1166

1167

<h2>set_select()</h2>

1168

1169

<p>If you use a <dfn><select></dfn> menu, this function permits you to display the menu item that was selected. The first parameter

1170

must contain the name of the select menu, the second parameter must contain the value of

1171

each item, and the third (optional) parameter lets you set an item as the default (use boolean TRUE/FALSE).</p>

<p>Example:</p>

<code>

<option value="three" <dfn><?php echo set_select('myselect', 'three'); ?></dfn> >Three</option><br />

</select>

</code>

<h2>set_checkbox()</h2>

1185

1186

<p>Permits you to display a checkbox in the state it was submitted. The first parameter

1187

must contain the name of the checkbox, the second parameter must contain its value, and the third (optional) parameter lets you set an item as the default (use boolean TRUE/FALSE). Example:</p>

<h2>set_radio()</h2>

<p>Permits you to display radio buttons in the state they were submitted. This function is identical to the <strong>set_checkbox()</strong> function above.</p>

</div>