Introduction - validation and filters

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');

Built-in validation rules

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

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.

/**
 * Validate an email address
 *
 * @param string    $email         Email address to validate
 * @param boolean   $domainCheck   Check if the domain exists
 */
function checkEmail($email, $domainCheck = false)
{
    if (preg_match('/^[a-zA-Z0-9\._-]+\@(\[?)[a-zA-Z0-9\-\.]+'.
                   '\.([a-zA-Z]{2,4}|[0-9]{1,3})(\]?)$/', $email)) {
        if ($domainCheck && function_exists('checkdnsrr')) {
            list (, $domain)  = explode('@', $email);
            if (checkdnsrr($domain, 'MX') || checkdnsrr($domain, 'A')) {
                return true;
            }
            return false;
        }
        return true;
    }
    return false;
}
$form->registerRule('checkmail', 'callback', 'checkEmail');
$form->addRule('email', 'Email is incorrect', 'checkmail', true);

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');

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.

// Group
$id[] = &HTML_QuickForm::createElement('text', 'username', 'Username');
$id[] = &HTML_QuickForm::createElement('text', 'code', 'Code');
$form->addGroup($id, 'id', 'Your ID:', '-');

// Validation rules per element

$rule['username'][] = array('Username is required', 'required');
$rule['username'][] = array('Username contains only letters', 'lettersonly');
$rule['username'][] = array('Username has between 5-8 characters', 'rangelength', array(5, 8));

$rule['code'][] = array('Code is required', 'required');
$rule['code'][] = array('Code contains numbers only', 'regex', '/^\d+$/');
$rule['code'][] = array('Code is 5 numbers long', 'rangelength', array(5, 5));

$form->addGroupRule('id', $rule);

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