Built-in validation Rules

Built-in validation Rules – List of built-in validation Rules

Registered Rules

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:


<?php
// these calls are identical
$username->addRule('minlength', 'Username should be at least 4 characters long', 4);
$username->addRule('length', 'Username should be at least 4 characters long', array('min' => 4));

// as are these
$start->addRule('lt', 'Start should be less than finish', $finish);
$start->addRule('compare', 'Start should be less than finish',
                array('operator' => '<', 'operand' => $finish));
?>

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	Operand. The values are compared as strings.
`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.
`email`	HTML_QuickForm2_Rule_Email	Checks that the field value is a valid email address. Currently the most common address format is recognised, support for additional RFC 5321 features and DNS checks is planned.
`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.

Registering new rules

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.


<?php
// registers a callback rule with a specific callback
HTML_QuickForm2_Factory::registerRule(
    'inarray', 'HTML_QuickForm2_Rule_Callback', null,
    array('callback' => 'in_array')
);

$field->addRule('inarray', 'wrong variable name!', array('foo', 'bar', 'baz'));
?>