Introduction - validation and filters

Introduction - validation and filters -- How to process submitted data

Validation rules

QuickForm makes client-side and server-side form validation easy. It allows for validation against regular expressions or custom functions and methods. You can define your own validation rules and apply them to the elements or groups you want. In this section, we will explore the different possibilities QuickForm offers to make validation easier.

QuickForm can verify if required elements are filled when the form is submitted. This works with every type of elements or groups, integer 0 is not considered as an empty value.
require_once 'HTML/QuickForm.php';

$form = new HTML_QuickForm('myform', 'post');
$form->addElement('text', 'email', 'Your email:');
$form->addElement('submit', 'submit', 'Submit');

// Validation rules

$form->addRule('email', 'E-Mail is required', 'required');

// Validation

if ($form->validate()) {
    $form->freeze();
}
$form->display();

On empty elements validation: If the element is empty, no validation rules other than required are checked for it. This means that empty element can be invalid only when it is required.

On required uploads: required rule does not work for file elements. Use uploadedfile.

The HTML_QuickForm::validate() method will scan through each rules in the order they have been set. If a rule is not validated, the error message corresponding to the element will be displayed and the form will be shown once again. You can use templates to set the position of this error message. The order you decide to set your validation rules is important because it will determine which error message is used.

Client-side validation

QuickForm can generate the javascript necessary to validate the form on the client side. This feature works for all standard elements and for groups. Server side validation is always performed in case the client has javascript turned off.
$form->addRule('email', 'E-Mail is required', 'required', null, 'client');

Tip: By setting the parameter 'client', you trigger the javascript automatic generation.

Built-in validation rules

QuickForm offers a few registered rules that are often used when validating forms.

Simple validation rules

required

value is not empty

maxlength

value must not exceed n characters

minlength

value must have more than n characters

rangelength

value must have between m and n characters

regex

value must pass the regular expression

email

value is a correctly formatted email

lettersonly

value must contain only letters

alphanumeric

value must contain only letters and numbers

numeric

value must be a number

nopunctuation

value must not contain punctuation characters

nonzero

value must be a number not starting with 0

Validation rules for file uploads

uploadedfile

Required file upload

maxfilesize

The file size must not exceed the given number of bytes

mimetype

The file must have a correct mimetype

filename

The filename must match the given regex

Other rules

callback

This rule allows to use an external function/method for validation, either by registering it or by passing a callback as a format parameter.

compare

The rule allows to compare the values of two form fields. This can be used for e.g. 'Password repeat must match password' kind of rule.

On rules for file uploads: These rules are defined in HTML/QuickForm/file.php, and are automatically registered when a file type element is added to the form. These rules are server-side only, for obvious reasons.

Some of these rules require an extra format parameter in order to work correctly. For example, the regex rule can be used this way to validate a signed integer:
$form->addRule('amount', 'Amount incorrect', 'regex', '/^[+-]?\d+$/');

Validation classes

Since release 3.2 all builtin validation is performed by subclasses of HTML_QuickForm_Rule class. You can create your own subclass of it and implement validate() and getValidationScript() methods. Consult the source for the examples.

Validation functions and methods

When you need a more complex validation, QuickForm can use your own custom-made functions to validate an element or a group. QuickForm can also call a method of a class. This way, it is possible to use PEAR's Validate package or any other class. If you want to use your own functions, you basically have two options:

  1. Register the function via registerRule() using 'callback' as $type and giving the new rule a custom $ruleName. Later you add the rule with this name via addRule() like any buitin rule.

  2. Add the rule of callback type via addRule() passing the name of your function as $format. This way you'll have less characters to type, but will be unable to pass additional data to your function.

You can pass an extra parameter of the type you want to your function when set with HTML_QuickForm::addRule(). Here we used TRUE to enable the DNS check of our function.

If you use a method, you must specify the class your method is in. Use this syntax when you register your rule:
// Method checkEmail is in class Validate
$form->registerRule('checkmail', 'callback', 'checkEmail', 'Validate');

Tip: You can also use a javascript function to validate your form, give it the same name as your PHP function, have it return a boolean and set the 'client' parameter.

Group validation

Groups of elements can be validated the same way other elements are, or use a more complex validation scheme. To validate a group as a whole, just use HTML_QuickForm::addRule(). The group elements' values will be passed to the validation function as an array.

You can have more complex validation for your groups using the HTML_QuickForm::addGroupRule() method. This allows for a per element validation. It also makes it possible to specify the number of elements that need to be valid for the group to be valid too.

In this example, we have set rules for the elements inside our group. Instead of using their names, we could have used their index (determined by the order they were created) in the group, it would speed up the validation process.

The following example takes the same group and will validate the form only if at least one of our two elements is not empty. To achieve this, we use the howmany parameter and set it to 1.
$form->addGroupRule('id', 'Fill at least one element', 'required', null, 1);

Conclusion

You have seen that QuickForm makes it easy to validate your elements and groups without having to write all the usually necessary code to find the different values. It takes care of required elements, generates the javascript automatically and adds a lot of flexibility by allowing you to use your own validation functions and regular expressions. It's time to experiment...

Filters

If we add a rule like
$form->addRule('element', 'The element is required', 'required');
to the form, then any input will satisfy it, including, for example, a single space. This is because the rule simply ensures that there are one or more characters present, and a space character satisfies the rule.

Of course this can be fixed by making a custom regex rule, but there is an easier solution. We usually do not care about leading and trailing spaces at all, and we can make the element's value pass through builtin trim() function before doing any validation on it:
$form->applyFilter('element', 'trim');

Filters are applied recursively, which means that trim() on an array will work, too. You can pass any valid callback as an argument to applyFilter() method.

Use filters if you want to 'sanitize' user input and do not really care about invalid values.