Extension:Validator

Description
Validator is an extension that makes parameter validation functionality available to other extensions. This enables other extensions to validate parameters, set them to their defaults, and generate error messages, while only defining the parameters and their criteria. The goal of this extension is to facilitate the handling of parameters in other extension, and generalize the error output. By itself, it does not add any functionality to the user end.

Functionality overview

 * Parameter validation: Parameters that are provided in an array where the keys represent their name, and the values their value, can easily be validated against a set of criteria. During this validation, errors and their types will be stored, and invalid parameters will be separated from valid ones. The only thing an other extension needs to do is define the criteria to validate against. A set of criteria types (which include check to see if something is a number, is within a range, or in an array) is provided by Validator, and can be used without any extra coding. When a criteria type that is not supported is required, you can hook into the Validator criteria types and add your own validation functions.


 * Default value handling: Parameters that are invalid, or simply not provided, can be set to their default values. These default values need to be specified by the extension the parameters belong to.


 * Error handling: Since the errors and their types are stored during validation, you can create error messages by retrieving this data and parsing it. Validator also provides a manager class that can provide you with a list of internationalized and specific errors. Via a validation level setting Validator provides, you can determine how the errors should be reflected on your wiki page. This can go from completely ignoring any errors to showing a complete list of all errors underneath the regular output, or even hiding the regular output and only showing the errors.

Installation
Once you have downloaded the code, place the 'Validator' directory within your MediaWiki 'extensions' directory. Then add the following code to your LocalSettings.php file:

Note that you need to place this code before the inclusion of any extensions depending on Validator.

Version
Validator is currently not yet released.

Planned features
The underneath list contains a list of planned features:

Version 0.2

 * Add hook for parameter types.
 * Add per-item-validation and per-item-defaulting for lists.
 * Add hook for validation types error messages.

Change log
This list only contains the versions and their release dates. For a list of all changes made, view the change log.

Supported languages
Validator has support for English, Belarusian, Breton, Lower Sorbian, Spanish, French, Galician, Swiss German, Upper Sorbian, Hungarian, Interlingua, Indonesian, Japanese, Ripoarisch, Macedonian, Dutch, Piedmontese, Portuguese, Russian, Swedish, Vietnamese and others.

Parameter definition
Integer example:

$yourParameters['parameterName'] = array (	'aliases' => array('parameter-name', 'paramName'),	'required' => true,	'type' => 'integer',	'criteria' => array( 'in_range' => array(0, 99), 'is_prime' => array ),	'default' => 42 );

List example:

$yourParameters['parameterName'] = array (	'type' => 'list',	'delimiter' => ',',	'criteria' => array( 'all_in_array' => array('possible value', 'another one'), ), );

Keys:


 * aliases: Optional. Array. When omitted, empty array will be assumed.
 * required: Optional. Boolean. When omitted, false will be assumed.
 * type: Optional. String. Values like string, integer, list, ect. When omitted, string will be assumed. The type will be used to create adittional criteria. New types can be added via Validator class hook.
 * criteria: Optional. Associative Array. When omitted, empty array will be assumed. Each array element has the criteria name as it's key, and criteria specifications in an array as value. New criteria definitions can be added via Validator class hook.
 * default: Optional. Mixed. When omitted, empty string will be assumed.

Parameter types
The underneath table contains all build in parameter types. If you want do add your own type with custom behaviour, look at how to hook a parameter type.

Table columns:
 * Example: An example of a value of this type.
 * Default type: This is the php variable type of the default value you can set.
 * Result type: The php variable type of the parameter after it has been gone through Validator.
 * Version: The version in which the last change to this type's behaviour was made.

Parameter criteria
The underneath table contains all build in parameter criteria types. If you want do add your own type with custom criteria, look at how to hook a criteria type.

Validator class
This class provides the methods required to validate your parameters, track the errors and set any default values. In most cases you'll want to do parameter validation via class ValidatorManager, which will create an instance of a Validator. You are entirely free to directly call the Validator class to do any custom interaction, like error message generation.

For an example of how to interact with this class, see the source of ValidatorManager.

Validator settings
Validator allows you to set certain behaviours by changing a static field.
 * $storeUnknownParameters: (boolean) Indicates whether parameters not found in the criteria list be stored in case they are not accepted. The default is false.
 * $accumulateParameterErrors: (boolean) Indicates whether parameters not found in the criteria list should be stored in case they are not accepted. The default is false.

Hooking parameter types
Validator does not support this yet.

Hooking criteria types
You can add new criteria types to Validator using the static addValidationFunction method of the Validator class. You can use this function to override existing criteria type handlers. It has 2 parameters:
 * $criteriaName: (string) The name of the cirteria.
 * $functionName: (array) The functions location. If it's a global function, only the name, if it's in a class, first the class name, then the method name.

ValidatorManager class
The ValidatorManager class contains wrapper functions for the most common interaction with the Validator class. It contains 2 methods:


 * manageMapparameters: Validates the provided parameters, and corrects them depending on the error level. Returns the valid parameters or false when the output should not be shown. The later is determined by the current $egValidatorErrorLevel.
 * getErrorList: Returns a string containing an HTML error list, or an empty string when there are no errors.

This is a simplified version of how the Maps extension uses the ValidatorManager class:

Error level
The error level can be set by changing the value of $egValidatorErrorLevel in LocalSettings.php. The possible values are:


 * Validator_ERRORS_NONE: Validator will not show any errors, and make the best of the input it got.
 * Validator_ERRORS_WARN: Validator will make the best of the input it got, but will show a warning that there are errors.
 * Validator_ERRORS_SHOW: Validator will make the best of the input it got, but will show a list of all errors.
 * Validator_ERRORS_STRICT: Validator will only show regular output when there are no errors, if there are, a list of them will be shown.

The default is Validator_ERRORS_SHOW.

Bugs and patches
If you found some bug and fixed it, please create a patch by going to the "Validator" directory, and typing:

svn diff >descriptivename.patch

Then add the patch to the bugs page. Bug reports should also be added here. You can also send them to Jeroen De Dauw, jeroendedauw -at- gmail.com.

Feature requests
Feel free to add feature requests to the discussion page.

Translating
Translation of Maps is done through translatewiki.net. The translation for this extension can be found here. To add language values or change existing ones, you should create an account on translatewiki.net, then request permission from the administrators to translate a certain language or languages on this page (this is a very simple process). Once you have permission for a given language, you can log in and add or edit whatever messages you want to in that language.

Translations for this documentation, especially the extension description, are also welcome.

Extensions that use Validator

 * Maps (Since 0.5)
 * Semantic Maps (Since 0.5)