Server-side validation in HTML_QuickForm2 is performed by HTML_QuickForm2::validate() method. Validation rules doing actual checks on element values are implemented as subclasses of HTML_QuickForm2_Rule, they are added to elements via HTML_QuickForm2_Node::addRule().

Basically, the form is invalid if it contains at least one invalid element. The element is considered invalid if it has an error message (accessible by HTML_QuickForm2_Node::getError()) set and valid otherwise. That error can appear in two different ways:

• You can manually set an error message for an element using HTML_QuickForm2_Node::setError().

• A rule added to the element will set an error message if it has such a message and its validation routine returned FALSE.

The latter happens in the course of executing HTML_QuickForm2::validate(). It iterates over all form's elements, for each element calling validate() methods of all its rules in the order they were added. As soon as an error is set on an element, its validation stops.

Do not forget to provide an error message to the rule, otherwise the element will be considered valid even if rule's validation routine returns FALSE. Not setting an error message is only useful when chaining (see below).

Some of the elements may perform additional hardcoded validation. For example, file uploads will check the value of 'error' field in $_FILES and assign a relevant error message when file upload was attempted but failed.

Of course, you will rarely need to instantiate Rule subclasses directly, Rule objects can be created by HTML_QuickForm2_Node::createRule() or automatically by addRule() if first parameter is a string representing registered rule type.

New rule types are registered by HTML_QuickForm2_Factory::registerRule() which accepts rule type name, corresponding class name and optionally file name containing that class and default configuration data for all rules of the given type.

For your convenience, all rules included in the package are already registered with HTML_QuickForm2_Factory and can be easily created with createRule() / addRule(). Some of the rule classes are registered under several names with different configuration data to save keystrokes and improve readability:

List of validation rules known to HTML_QuickForm2_Factory

Rule name	Class name	Description	Configuration
nonempty	HTML_QuickForm2_Rule_Nonempty	Checks that the field is not empty	Minimum number of nonempty values for Containers / arrays, integer
empty	HTML_QuickForm2_Rule_Empty	Checks that the field is empty
required	HTML_QuickForm2_Rule_Required	Like nonempty, but the field is marked as required in output	Like nonempty
compare	HTML_QuickForm2_Rule_Compare	Compares the value of the field with some other value using the given operator	Either of the following: operand array([operator, ]operand) array(['operator' => operator, ]['operand' => operand]) If operator is missing it will default to '==='. Operand can either be a literal value or another form element.
eq	As compare rule with hardcoded '===' operator	Operand. The values are compared as strings.
neq	As compare rule with hardcoded '!==' operator
lt	As compare rule with hardcoded '<' operator	Operand. The values are compared as numbers.
lte	As compare rule with hardcoded '<=' operator
gt	As compare rule with hardcoded '>' operator
gte	As compare rule with hardcoded '>=' operator
regex	HTML_QuickForm2_Rule_Regex	Checks that the field value matches the given regular expression.	Regular expression, string. Use slashes for delimiters if you intend to do client-side validation.
callback	HTML_QuickForm2_Rule_Callback	Checks the value using a provided callback function (method). It is expected to return TRUE if the element is valid	Either of A valid callback array ('callback' => validation callback [, 'arguments' => additional arguments] [, 'js_callback' => javascript callback for client-side validation])
length	HTML_QuickForm2_Rule_Length	Checks that the value's length is within the given limits	Either of integer (rule checks for exact length) array(minlength, maxlength) array(['min' => minlength, ]['max' => maxlength])
minlength	Checks that the value's length is at least the given number of characters	Minimal length, integer
maxlength	Checks that the value's length is at most the given number of characters	Maximal length, integer
notcallback	HTML_QuickForm2_Rule_NotCallback	Checks the value using a provided callback function (method). It is expected to return FALSE if the element is valid.	Like callback
notregex	HTML_QuickForm2_Rule_NotRegex	Checks that the field value does not match the given regular expression.	Like regex
Rules specific for file uploads
maxfilesize	HTML_QuickForm2_Rule_MaxFileSize	Checks that uploaded file size does not exceed the given limit	Maximum allowed file size, integer
mimetype	HTML_QuickForm2_Rule_MimeType	Checks that uploaded file is of the correct MIME type	Allowed MIME type or an array of types
Rules specific for containers
each	HTML_QuickForm2_Rule_Each	Validates all elements in a Container using a template Rule	Template Rule, instance of HTML_QuickForm2_Rule

Usage of builtin rules is covered in builtin-rules.php example installed with the package.

Most of the built-in rules are designed to check scalar values and will not work properly if added to a Container (this includes Groups and Group-based elements as Date and Hierselect), as Containers return their values in an associative array. One notable exception is nonempty / required rule that can validate a container (or <select multiple="multiple" />):

It is of course possible to implement a custom rule that will properly handle an associative array as the element's value. It is also possible to leverage existing "scalar" rules to validate Containers by using each rule, it applies a template rule to all the elements in a Container and considers Container valid if its validation routine returns TRUE for all of them:

More specific rules are run first: rules added to container will be checked after rules added to its contained elements.

HTML_QuickForm2 allows validation of elements based on values and validation status of other elements. This is done by building a "chain" of validation rules using HTML_QuickForm2_Rule::and_() and HTML_QuickForm2_Rule::or_() methods. Execution of the chain starts with a rule that was added to an element, then results of other rules' validation routines are combined using corresponding logical operators. Error is only set on the element if the whole chain returned FALSE.

Behaviour of and_() and or_() is similar to PHP's and and or operators:

• and_() has higher precedence than or_().

• Evaluation is short-circuited. If first argument of and_() evaluates to FALSE then FALSE is returned without evaluating second argument, if first argument of or_() evaluates to TRUE then TRUE is returned without evaluating second argument.

Rules that are added to the chain behave the same way as the rules that are added directly to the element they validate (this is not necessarily the same element the chain is added to), they will set an error if the rule itself returns FALSE, not the chain. Thus it is often needed not to provide error messages to the rules. It may also make sense to add a chain of rules to a chain (this is similar to adding parentheses to a PHP expression with and and or).

Validation library

Client-side validation depends on a JS library residing in quickform.js file. Neither a link to that file nor its contents is automatically included in the output generated by a renderer, the next section describes how you can properly handle including it.

You can tell a rule to also generate Javascript necessary for client-side validation. This is done by passing a $runAt parameter with HTML_QuickForm2_Rule::CLIENT flag set to addRule():

If more rules were chained to the added one with and_() and or_(), Javascript will be generated for the whole chain.

Since release 0.6.0 it is possible to run client-side rules for an element on changing its value or on it losing input focus ('onchange' and 'onblur' events) in addition to form submit ('onsubmit' event). This is triggered by passing a $runAt parameter with HTML_QuickForm2_Rule::ONBLUR_CLIENT flag set to addRule(). If a rule has chained rules, then validation will be triggered by all elements appearing in a chain.

Another change introduced in 0.6.0 is that validation errors are now output near the elements instead of being shown in Javascript alert(). In a nuthshell, client-side validation behaviour in HTML_QuickForm2 0.6.0+ is more similar to that of HTML_QuickForm_DHTMLRulesTableless than to that of old HTML_QuickForm.

Most of the built-in rules are able to run client-side, the only exceptions are maxfilesize and mimetype rules specific for file uploads.

If you want to run callback rule client-side, you will obviously need to implement a callback in Javascript as well as in PHP. If you don't explicitly set 'js_callback' configuration parameter, callback rule will try to run Javascript function having the same name as provided PHP 'callback'. This may be especially useful if you use HTML_AJAX to proxy PHP classes or callbacks in Javascript.

When running regex rules client-side, you should stick to regular expression syntax common in PHP and Javascript:

• Use a slash / as a delimiter.

• Use only i, m, u pattern modifiers. If u modifier is used, PHP's Unicode escapes \x{NNNN} are automatically converted to Javascript's Unicode escapes \uNNNN when creating a client-side rule.

• Do not use regular expession features that are not supported in Javascript (e.g. lookbehind assertions).

While it is possible to add a client-side only rule

<?php
$username->addRule('minlength', 'Username should be at least 4 characters long', 4,
                   HTML_QuickForm2_Rule::CLIENT);
?>

it is not recommended unless you perform the same validation server-side using some other rule.