ParamProcessor is a parameter processing library 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. For example, if one defines a parameter to
be an integer, in the range [0, 100]
, then ParamProcessor will verify the
input is an integer, in the specified range, and return it as an actual
integer variable.
Also see ParserHooks, a library that builds on top of ParamProcessor and provides MediaWiki integration.
On Packagist:
The recommended way to use this library is via Composer.
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
version 1.x of this package:
{
"require": {
"param-processor/param-processor": "~1.0"
}
}
Get the code of this package, 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. Then take care of autoloading the classes defined in the src directory.
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 preferred to use this
array format as the class itself is not stable yet.
Processing is done via ParamProcessor\Processor
.
These fields are supported:
Name | Type | Default | Description |
---|---|---|---|
name | string | required | |
type | string (enum) | string | |
default | mixed | null | If this value is null, the parameter has no default and is required |
aliases | array of string | empty array | Aliases for the name |
trim | boolean | inherited from processor options | If the value should be trimmed |
islist | boolean | false | |
delimiter | string | , | The delimiter between values if it is a list |
manipulatedefault | boolean | true | If the default value should also be manipulated |
values | array | Allowed values | |
message | string | required | |
post-format | callback | none | Takes the value as only parameter and returns the new value |
The requires fields currently are: name and message
Name | PHP return type | Description |
---|---|---|
string | string |
Default type Supported options:
|
boolean | boolean | Accepts "yes", "no", "on", "off", "true" and "false" |
float | float |
Supported options:
|
integer | integer | Supported options: same as for float |
dimension | string |
Value for a width or height attribute in HTML Supported options:
|
string-parser
Name of a class that implements the ValueParsers\ValueParser
interfacevalidation-callback
Callback that gets the raw value as only parameter and returns a booleanvalidator
Name of a class that implements the ValueValidators\ValueValidator
interfaceAs an example, the Maps MediaWiki extension defines a coordinate
parameter type that turns the input into a DataValues\LatLongValue
value object.
$parameterDefinitions = [
'username' => [
'minlength' => 1,
'maxlength' => 20
],
'job' => [
'default' => 'unknown',
'values' => [ 'Developer', 'Designer', 'Peasant' ]
],
'favourite-numbers' => [
'type' => 'int',
'islist' => true,
'default' => []
]
]
$processor = ParamProcessor\Processor::newDefault();
$processor->setParameters(
[
'username' => 'Jeroen',
'favourite-numbers' => '42, 1337, not a number',
],
$paramDefinitions
);
foreach ($processor->processParameters()->getParameters() $parameter) {
echo $parameter->getName();
var_dump($parameter->getValue());
};
// username: string(6) "Jeroen"
// job: string(7) "unknown"
// favourite-numbers: array(2) {[0]=>int(42), [1]=>int(1337)}
Alternative way to input parameters:
$processor->setFunctionParams(
[
'username = Jeroen',
'favourite-numbers=42, 1337, not a number',
],
$paramDefinitions
);
ParamProcessor has been written by Jeroen De Dauw to support the Maps and Semantic MediaWiki projects.
DimensionParam
dimension
ParamDefinitionFactory::newDefinitionsFromArrays
ParamDefinitionFactory::getComponentForType
ParamDefinitionFactory
constructorParameterTypes
constructorParameterTypes::addType
ParameterTypes::newCoreTypes
ProcessingResult::getParameterArray
ParameterTypes
public constants: BOOLEAN
, FLOAT
, INTEGER
, STRING
, DIMENSION
ParamDefinition::getCleanDefinitions
in favour of ParamDefinitionFactory
ParamDefinition::setDefault
in favour of constructor parameterProcessor::getParameterValues
in favour of processParameters
and ProcessingResult
Processor::getErrors
in favour of processParameters
and ProcessingResult
Processor::getErrorMessages
in favour of processParameters
and ProcessingResult
Processor::hasErrors
in favour of processParameters
and ProcessingResult
Processor::hasFatalError
in favour of processParameters
and ProcessingResult
ParamDefinition::hasDependency
ParamDefinition::addDependencies
ParamDefinition::getDependencies
dependencies
key in ParamDefinition::setArrayValues
parameterTopologicalSort
TSNode
ParamDefinition
StringParam
DimensionParam
ParamDefinition::setArrayValues
ParamDefinition::$acceptOverriding
ParamDefinition::$accumulateParameterErrors
Param::$accumulateParameterErrors
Settings
Options::setRawStringInputs
Options::isStringlyTyped
ParamDefinition
Processor::setParameterDefinitions
Processor::setParameters
in favour of setParameterDefinitions
Processor::setFunctionParams
in favour of setParameterDefinitions
ParamDefinitionFactory::newDefinitionFromArray
ParamDefinitionFactory::registerType
ParamDefinitionFactory::registerGlobals
typed-parser
key in parameter type definitionsParameterTypes
to allow gradual migration away from the now deprecated $wgParamDefinitions
$wgParamDefinitions
$egValidatorSettings
Processor
instanceParamDefinitionFactory
emitting a warning when initialized without the global wgParamDefinitions
being setParamDefinition::format
Processor::newProcessingResult
ParamDefinition::getAllowedValues
First release as standalone PHP library.