The ParamProcessor MediaWiki extension, formerly known as Validator, is a parameter processing framework that provides a way to declaratively define a set of parameters and how they should be processed. It can take such declarations together with a list of raw parameters and provide the processed values.
On Packagist:
- PHP 5.3 or later
- MediaWiki 1.18 or later
- DataValues 0.1 or later
- DataValuesInterfaces 0.1 or later
- DataValuesCommon 0.1 or later
You can use Composer to download and install this package as well as its dependencies. Alternatively you can simply clone the git repository and take care of loading yourself.
To add this package as a local, per-project dependency to your project, simply add a
dependency on param-processor/param-processor to your project's composer.json file.
Here is a minimal example of a composer.json file that just defines a dependency on
ParamProcessor 1.0:
{
"require": {
"param-processor/param-processor": "1.0.*"
}
}
Get the ParamProcessor code, either via git, or some other means. Also get all dependencies. You can find a list of the dependencies in the "require" section of the composer.json file. Load all dependencies and the load the ParamProcessor library by including its entry point: ParamProcessor.php.
ParamProcessor can be installed as MediaWiki extension.
Simply include the entry point in your LocalSettings.php file:
require_once( "$IP/extensions/Validator/Validator.php" );
The goal of the ParamProcessor library is to make parameter handling simple and consistent.
In order to achieve this, a declarative API for defining parameters is provided. Passing in such parameter definitions together with a list of raw input into the processor leads to a processed list of parameters. Processing consists out of name and alias resolving, parsing, validation, formatting and defaulting.
If ones defines an "awesomeness" parameter of type "integer", one can be sure that at the end of the processing, there will be an integer value for the awesomeness parameter. If the user did not provide a value, or provided something that is invalid, while the parameter it is required, processing will abort with a fatal error. If on the other hand there is a default, the default will be set. If the value was invalid, a warning will be kept track of. In case the user provides a valid value, for instance "42" (string), it will be turned in the appropriate 42 (int).
Parameters are defined using the ParamProcessor\ParamDefinition class. Users can also use the array format to define parameters and not be bound to this class. At present, it is prefered to use this array format as the class itself is not stable yet.
Processing is done via ParamProcessor\Processor.
- type, string enum
- islist, boolean
- default, mixed, param will be required when null/omitted
- values, array, allowed values
- message, string, required for now
$paramDefintions = array();
$paramDefintions[] = array(
'name' => 'username',
);
$paramDefintions[] = array(
'name' => 'job',
'default' => 'unknown',
'values' => array( 'Developer', 'Designer', 'Manager', 'Tester' ),
);
$paramDefintions[] = array(
'name' => 'favourite-numbers',
'islist' => true,
'type' => 'int',
'default' => array(),
);$inputParams = array(
'username' => 'Jeroen',
'job' => 'Developer',
);
$processor = ParamProcessor\Processor::newDefault();
$processor->setParameters( $inputParams, $paramDefintions );
$processingResult = $processor->processParameters();
$processedParams = $processingResult->getParameters();This library comes with a set up PHPUnit tests that cover all non-trivial code. You can run these tests using the PHPUnit configuration file found in the root directory. The tests can also be run via TravisCI, as a TravisCI configuration file is also provided in the root directory.
ParamProcessor has been written by Jeroen De Dauw to support Maps and Semantic MediaWiki.
ParamProcessor 1.0 is currently in beta-quality and is not recommended for use in production until the actual release.
This release is primarily a redesign of many internal APIs aimed at greater stability and cleaner interfaces exposed to the outside.
- DataValues 0.1 or higher is now required
- DataValuesInterfaces 0.1 or higher is now required
- DataValuesCommon 0.1 or higher is now required
- Changed minimum MediaWiki version from 1.16 to 1.18.
- Full compatibility with MediaWiki 1.20, 1.21, 1.22 and forward-compatibility with 1.23.
- Added compatibility with PHP 5.4.x and PHP 5.5.x
- Dropped support for Validator 0.4.x parameter definitions, including Criteria and Manipulations
- Deprecated the ParserHook class
- New built-in parameter type 'title'. Accepts existing and non-existing page titles which are valid within the wiki.
-
ParserHook::$parser now is a reference to the original parser object, as one would suspect. Before this has only been the case for tag extension but not for parser function calls.
-
if SFH_OBJECT_ARGS and therefore object parser function arguments are available in the MW version used with Validator, ParserHook::$frame will not be null anymore. Therefore a new function ParserHook::renderFunctionObj() is introduced, handling these SFH_OBJECT_ARGS hooks.
-
ParserHook constructor now accepts a bitfield for flags to define further customization for registered Hooks. First option can be set via ParserHook::FH_NO_HASH to define that the function hook should be callable without leading hash ("{{plural:...}}"-like style).
-
Option for unnamed parameter handling to work without named fallback. This allows to ignore '=' within parameter values entirely, these parameters bust be set before any named parameter then. See Validator::setFunctionParams() and ParserHook::getParameterInfo() for details.
-
ParserHook Validation messages will now output text in global content language instead of users interface language.
- Internationalization fix in the describe parser hook.
- Fixed compatibility fallback in Parameter::getDescription.
- Fixed handling of list parameters in ParameterInput.
- Added language parameter to describe that allows setting the lang for the generated docs.
- Added getMessage method to ParserHook class for better i18n.
- Added setMessage and getMessage methods to Parameter class for better i18n.
- Added unit tests for the criteria.
- Fixed issue with handling floats in CriterionInRange.
- Added support for open limits in CriterionHasLength and CriterionItemCount.
- Added ParameterInput class to generate HTML inputs for parameters, based on code from SMWs Special:Ask.
- Added "$manipulate = true" as second parameter for Parameter::setDefault, which gets passed to Parameter::setDoManipulationOfDefault.
- Boolean manipulation now ignores values that are already a boolean.
- Removed ParamManipulationBoolstr.
- Added method to get the allowed values to CriterionInArray.
- Added automatic non-using of boolean manipulation when a boolean param was defaulted to a boolean value.
- Parameter fix in ListParameter::setDefault, follow up to change in 0.4.5.
- Escaping fix in the describe parser hook.
- Added string manipulation, applied by default on strings and chars.
- Tweaks to parser usage in the ParserHook class.
- Fixed incorrect output of nested pre-tags in the describe parser hook.
- Removed underscore and space switching behavior for tag extensions and parser functions.
- Added describe parser hook that enables automatic documentation generation of parser hooks defined via Validator.
- Modified the ParserHook and Parameter classes to allow specifying a description message.
- Fixed compatibility with MediaWiki 1.15.x.
- Removed the lowerCaseValue field in the Parameter class and replaced it's functionality with a ParameterManipulation.
- Made several small fixes and improvements.
- Added ParserHook class that allows for out-of-the-box parser function and tag extension creation with full Validator support.
- Added listerrors parser hook that allows you to list all validation errors that occurred at the point it's rendered.
- Added support for conditional parameter adding.
Basically everything got rewritten...
- Added Parameter and ListParameter classes to replace parameter definitions in array form.
- Added ParameterCriterion and ListParameterCriterion classes for better handling of parameter criteria.
- Added ParameterManipulation and ListParameterManipulation classes for more structured formatting of parameters.
- Added ValidationError class to better describe errors.
- Replaced the error level enum by ValidationError::SEVERITY_ and ValidationError::ACTION_, which are linked in $egErrorActions.
- Added support for 'tolower' argument in parameter info definitions.
- Fixed issue with the original parameter name (and in some cases also value) in error messages.
- Fixed issue with parameter reference that occurred in php 5.3 and later.
- Fixed escaping issue that caused parameter names in error messages to be shown incorrectly.
- Fixed small issue with parameter value trimming that caused problems when objects where passed.
- Fixed bug that caused notices when using the ValidatorManager::manageParsedParameters method in some cases.
- Added lower casing to parameter names, and optionally, but default on, lower-casing for parameter values.
- Added removal of default parameters from the default parameter queue when used as a named parameter.
- Added ValidatorManager::manageParsedParameters and Validator::setParameters.
- Added generic default parameter support.
- Added parameter dependency support.
- Added full meta data support for validation and formatting functions, enabling more advanced handling of parameters.
- Major refactoring to conform to MediaWiki convention.
- Fixed potential xss vectors.
- Minor code improvements.
- Changed the inclusion of the upper bound for range validation functions.
- Small language fixes.
- Added handling for lists of a type, instead of having list as a type. This includes per-item-validation and per-item-defaulting.
- Added list validation functions: item_count and unique_items
- Added boolean, number and char types.
- Added support for output types. The build in output types are lists, arrays, booleans and strings. Via a hook you can add your own output types.
- Added Validator_ERRORS_MINIMAL value for $egValidatorErrorLevel.
- Added warning message to ValidatorManager that will be shown for errors when egValidatorErrorLevel is Validator_ERRORS_WARN.
- Added criteria support for is_boolean, has_length and regex.
- Initial release, featuring parameter validation, defaulting and error generation.