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.

Download

 * Validator0.2.zip 28.75 KB
 * Validator0.2.7z 23.63 KB

Subversion downloads
You can also download the code directly via SVN from the MediaWiki source code repository, at http://svn.wikimedia.org/svnroot/mediawiki/tags/extensions/Validator/REL_0_2. From a command line, you can call the following:

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/tags/extensions/Validator/REL_0_2 Validator

Package downloads
Validator comes bundled with every release of Maps and Semantic Maps.

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

 * Add hook for parameter types.


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


 * Version 0.2 (2009-12-25)
 * Version 0.2.1 (2010-02-01)
 * Version 0.2.2 (2010-03-01)


 * Version 0.1 (2009-12-17)

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

Parameter definition
This section contains detailed explanations of how each parameter definition element works. These examples can give you an idea of what a realistic parameter definition looks like:

A simple integer parameter named 'zoom' that only accepts values in the range [0, 15[. 'zoom' => array(	'type' => 'integer',	'criteria' => array( 'in_range' => array(0, 15) )	),

The most complex parameter definition found in the Maps extension, of a parameter that accepts a list of strings that need to be in an array fetched by self::getControlNames, need to be outputted as a list enumeration with a comma as delimiter and ' as wrapper, and has as default items $egMapsGMapControls. 'controls' => array(	'type' => array('string', 'list'),	'criteria' => array( 'in_array' => self::getControlNames ),	'default' => $egMapsGMapControls,	'output-type' => array('list', ',', '\'')	),

All parameter definition elements are optional. You can define a parameter without any extra information, like done below, without any problem.

'style' => array,

Aliases
Key:

The aliases element allows you to define synonyms for the main parameter name, which is hold as the key of your parameter definition. For example, if you define a 'centre' parameter, with 'center' as an alias, both parameters will be treated as if they where the same.

'centre' => array(	'aliases' => array('center'),	),

The value assigned to the aliases key should be an array containing all aliases as strings. When the aliases definition is omitted, Validator will assume there are no aliases for your parameter.

Required
Key:

The required element allows you to indicate if the parameter is required. If it is not required, and the parameter is not provided, the default value will be assigned. If it is however required, Validator will add a 'missing required parameter' error.

The value assigned to the required key should be a boolean. When the required definition is omitted, Validator will assume your parameter is not required.

Example:

'centre' => array(	'required' => true,	),

Default value
Key:

Obviously, the default element allows you to set a default value for your parameter. This value will be used to correct the values of invalid parameters, and to set those of not provide, non-required, parameters.

The type of the default value depends on the parameter type being a list or not. If it's a list, the default needs to be an array. If it's not a list, the default needs to be a single value.

Integer example:

'zoom' => array(	'default' => 10,

List of string example:

'layers' => array(	'default' => array('a', 'b', 'c'),

Type
Key:

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.

Example of an integer type definition 'type' =>'integer'

Lists
Key: part of

Since version 0.2, you can specify lists of a certain type. For example, you can have a list of integers, or a list of strings.

You can specify a parameter is a list of a type, instead of just a single value of a type, by changing your type definition into an array, and adding the list identifier as second element. The underneath examples demonstrate how to define a list of integers.

Integer list type definition 'type' => array('integer', 'list')

You can also specify the delimiter for the list, by adding it as third element to your type definition array. When omitted, comma will be assumed.

Integer list type definition with custom delimiter 'type' => array('integer', 'list', ';')

Criteria
Key:

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.

These criteria look at single values. If the type of the parameter is a list, every list item of the value will be checked against these criteria. If you want to validate a list as a whole however, you need to use list criteria.



List criteria
Key:

List criteria are criteria that look at a list as a whole, not the individual values. Like regular criteria, you can add your own custom ones, see how to hook a criteria type.

Output type
Key:  or

The output type element allows you to specify additional formatting that needs to be done with the parameter value, before it is retrieved from Validator. Important to know is that validator holds all values in string form. List types are hold in an array of strings. The obvious use of the output type is to convert these representations to something directly usable by your code.

The underneath table contains the build in output types. You can also add your own custom types.

If you only need to do one manipulation, you can use the  key. However, when you need to do multiple, you should use. The only difference between  and   is that   will expect an array of output types. This array can be empty or contain only one item, still, it needs to be an array. Keep in mind that when working with multiple output types, the ones defined first will get executed first.

Example showing how you can set the output type to 'list'. 'output-type' => 'list'

This example does the same as the above one, by using the  key. 'output-types' => array('list')

This example demonstrates how you can add multiple output types. 'output-types' => array('list')

You can also specify extra parameters for certain output types, to change the behaviour of the manipulation they perform. A good example is the list format, which accepts an optional delimiter and optional wrapper. Simply change the output type name into an array that holds the output type name as first element, and the parameters as successive ones. The amount, optionality, and order of these parameters is entirely defined by the output type.

This example is identical to the first one. 'output-type' => array('list')

Here you have 2 extra parameters added, the first one is the delimiter, the second one is the wrapper. 'output-type' => array('list', ';', '\'')

A similar example, but for. 'output-types' => array(    array('boolstr')     array('list', ';', '\'')     )

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.
 * $acceptOverriding: (boolean) Indicates whether parameters that are provided more then once should be accepted, and use the first provided value, or not, and generate an error. The default is false.
 * $perItemValidation: (boolean) Indicates if errors in list items should cause the item to be omitted, versus having the whole list be set to it's default. The default is true.

Hooking parameter types
Validator does not support this yet. This is planned for Validator 0.3.

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.

An usage example of the Maps extension:

To add a list validation function, which means, a validation function that validates a list as a whole, not the individual values, you need to use the addListValidationFunction function, which works identical to addValidationFunction.

A fictional example:

Hooking output types
You can add new output types to Validator using the static addOutputFormat method of the Validator class. You can use this function to override existing output type handlers. It has 2 parameters:
 * $formatName: (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.

An usage example of the Maps extension:

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 is a setting defined by Validator that indicates in which situations errors should be shown, and how extensive they should be. Validator uses this setting internally in the ValidationManager class to generate error messages. Extensions using Validator can also use this setting in their own code, if not all error handling goes via Validator. An example of such an implementation can be found in the Maps extension, where maps will not be shown when there are no valid coordinates. Maps will only show a warning when the error level is equal to or above Validator_ERRORS_MINIMAL.

The error level can be set by changing the value of $egValidatorErrorLevel in LocalSettings.php, after the inclusion of Validator. The default is Validator_ERRORS_SHOW.

The possible error level values are discussed below. Note that the described behaviours are implemented in Validator, but not necessary in all extensions using Validator. The later is the task of the authors of the extensions using Validator.

None
Value:

No errors will be shown under any circumstances, including these where no output can be shown for the input of which the parameters got validated.

Minimal
Value:

The only instance where an error can be shown is when no output can be shown for the input of which the parameters got validated. In all other circumstances, any present errors will be treated as best as they can, by means of defaulting.

Warn
Value:

A warning will be shown when there are errors present. Any present errors will be treated as best as they can, by means of defaulting.

Show


Value:

All present errors will be reported in the form of a list. Any present errors will be treated as best as they can, by means of defaulting.

Strict
Value:

All present errors will be reported in the form of a list. If there is at least one error, even if it can be solved by means of defaulting, the regular output will not be generated and shown. To see the regular output, the user will first have to fix the reported errors.

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)