param-processor/param-processor

Parameter processing library

Sunday, June 10, 2018
by Jeroen De Dauw
Repository
4 Watchers
15 Stars
195,803 Installations

PHP
6 Dependents
0 Suggesters
6 Forks
8 Open issues
17 Versions
4 % Grown

The README.md

ParamProcessor

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., _(*1)

Also see ParserHooks, a library that builds on top of ParamProcessor and provides MediaWiki integration., _(*2)

, _(*3)

On Packagist: , _(*4)

Installation

The recommended way to use this library is via Composer., _(*5)

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:, _(*6)

{
    "require": {
        "param-processor/param-processor": "~1.0"
    }
}

Manual

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., _(*7)

Concept

The goal of the ParamProcessor library is to make parameter handling simple and consistent., _(*8)

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., _(*9)

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)., _(*10)

Implementation structure

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., _(*11)

Processing is done via ParamProcessor\Processor., _(*12)

Defining parameters

Array definition schema

These fields are supported:, _(*13)

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, _(*14)

Core parameter types

Name	PHP return type	Description
string	string	Default type Supported options: length: int or false (overrides minlength and maxlength) minlength: int or false maxlength: int or false regex: string
boolean	boolean	Accepts "yes", "no", "on", "off", "true" and "false"
float	float	Supported options: lowerbound: int, float or false upperbound: int, float or false range: [lowerbound, upperbound] withinrange: [float $point, float $deviation]
integer	integer	Supported options: same as for float
dimension	string	Value for a width or height attribute in HTML Supported options: allowauto: bool maxpercentage: int minpercentage: int units: array of string defaultunit: string lowerbound: int, float or false upperbound: int, float or false

Defining parameter types

string-parser Name of a class that implements the ValueParsers\ValueParser interface
validation-callback Callback that gets the raw value as only parameter and returns a boolean
validator Name of a class that implements the ValueValidators\ValueValidator interface

As an example, the Maps MediaWiki extension defines a coordinate parameter type that turns the input into a DataValues\LatLongValue value object., _(*15)

Usage example

Defining parameters

$parameterDefinitions = [
    'username' => [
        'minlength' => 1,
        'maxlength' => 20
    ],
    'job' => [
        'default' => 'unknown',
        'values' => [ 'Developer', 'Designer', 'Peasant' ]
    ],
    'favourite-numbers' => [
        'type' => 'int',
        'islist' => true,
        'default' => []
    ]
]

Processing input using defined parameters

$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:, _(*16)

$processor->setFunctionParams(
    [
        'username = Jeroen',
        'favourite-numbers=42, 1337, not a number',
    ],
    $paramDefinitions
);

Contributing

Authors

ParamProcessor has been written by Jeroen De Dauw to support the Maps and Semantic MediaWiki projects., _(*17)

Release notes

1.12.0 (2021-05-04)

Allowed installation with PHP 8.x

1.11.0 (2021-03-18)

Allowed installation with new DataValue library versions

1.10.0 (2019-08-03)

Removed DimensionParam
Fixed bug in parsing of parameters of type dimension

1.9.0 (2019-08-03)

Added ParamDefinitionFactory::newDefinitionsFromArrays

1.8.0 (2019-08-03)

Removed ParamDefinitionFactory::getComponentForType
Added ParamDefinitionFactory constructor
Added ParameterTypes constructor
Added ParameterTypes::addType
Added ParameterTypes::newCoreTypes
Added ProcessingResult::getParameterArray

1.7.0 (2019-08-02)

Added ParameterTypes public constants: BOOLEAN, FLOAT, INTEGER, STRING, DIMENSION
Deprecated ParamDefinition::getCleanDefinitions in favour of ParamDefinitionFactory
Deprecated ParamDefinition::setDefault in favour of constructor parameter
Deprecated Processor::getParameterValues in favour of processParameters and ProcessingResult
Deprecated Processor::getErrors in favour of processParameters and ProcessingResult
Deprecated Processor::getErrorMessages in favour of processParameters and ProcessingResult
Deprecated Processor::hasErrors in favour of processParameters and ProcessingResult
Deprecated Processor::hasFatalError in favour of processParameters and ProcessingResult
Deprecated parameter dependencies
- Deprecated ParamDefinition::hasDependency
- Deprecated ParamDefinition::addDependencies
- Deprecated ParamDefinition::getDependencies
- Deprecated dependencies key in ParamDefinition::setArrayValues parameter
- Deprecated TopologicalSort
- Deprecated TSNode
Deprecated extending ParamDefinition
Deprecated StringParam
Deprecated DimensionParam
Deprecated ParamDefinition::setArrayValues
Deprecated ParamDefinition::$acceptOverriding
Deprecated ParamDefinition::$accumulateParameterErrors
Deprecated Param::$accumulateParameterErrors
Deprecated Settings
Deprecated Options::setRawStringInputs
Deprecated Options::isStringlyTyped

1.6.1 (2019-07-28)

Fixed message defaulting bug in ParamDefinition

1.6.0 (2019-07-28)

Added Processor::setParameterDefinitions
Deprecated second parameter of Processor::setParameters in favour of setParameterDefinitions
Deprecated second parameter of Processor::setFunctionParams in favour of setParameterDefinitions
Deprecated second parameter of ParamDefinitionFactory::newDefinitionFromArray
Deprecated return value of ParamDefinitionFactory::registerType
Deprecated ParamDefinitionFactory::registerGlobals
Deprecated typed-parser key in parameter type definitions

1.5.0 (2019-07-28)

Improved code comments and added extra type checks

1.4.2 (2018-11-26)

Fixed defaulting behaviour of list parameters

1.4.1 (2018-11-26)

List parameters are no longer set to their default when a single value is invalid

1.4.0 (2018-11-25)

Dropped support for PHP older than 7.1
Added ParameterTypes to allow gradual migration away from the now deprecated $wgParamDefinitions
Deprecated $wgParamDefinitions
Deprecated $egValidatorSettings

1.3.4 (2018-05-05)

Fixed deprecation notice occurring with PHP 7.2+

1.3.3 (2017-09-28)

Installation together with DataValues 2.x is now allowed
Installation together with DataValues Common 0.4.x is now allowed

1.3.2 (2017-03-26)

Fixed clearing of processing errors when making multiple processing calls to one Processor instance

1.3.1 (2016-09-21)

Fixed ParamDefinitionFactory emitting a warning when initialized without the global wgParamDefinitions being set

1.3.0 (2016-07-15)

Dropped support for PHP 5.3 and PHP 5.4.
Fixed bug in ParamDefinition::format

1.2.5 (2016-05-23)

Fixed bug in Processor::newProcessingResult

1.2.4 (2016-05-15)

Fixed bug in ParamDefinition::getAllowedValues

1.2.3 (2016-04-04)

Installation together with DataValues Interfaces 0.2.x is now allowed
Installation together with DataValues Common 0.3.x is now allowed
The component is now also tested against PHP 7

1.2.2 (2014-10-24)

Installation together with DataValues 1.x is now allowed.

1.2.0 (2014-09-12)

Dropped dependency on DataValues Geo.

1.1.0 (2014-05-07)

Dropped dependency on DataValues Time.
Use PSR-4 based loading rather than PSR-0 based loading.
Fixed Windows compatibility in PHPUnit bootstrap

1.0.2 (2013-12-16)

Removed dependency on data-values/number
Updated required version of data-values/common from ~0.1 to ~0.2.

1.0.1 (2013-11-29)

Implemented ProcessingResult::hasFatal
Added ProcessingResultTest

1.0.0 (2013-11-21)

First release as standalone PHP library., _(*18)

library param-processor

Parameter processing library

param-processor/param-processor

The README.md

ParamProcessor

Installation

Composer

Manual

Concept

Implementation structure

Defining parameters

Array definition schema

Core parameter types

Defining parameter types

Usage example

Defining parameters

Processing input using defined parameters

Contributing

Authors

Release notes

1.12.0 (2021-05-04)

1.11.0 (2021-03-18)

1.10.0 (2019-08-03)

1.9.0 (2019-08-03)

1.8.0 (2019-08-03)

1.7.0 (2019-08-02)

1.6.1 (2019-07-28)

1.6.0 (2019-07-28)

1.5.0 (2019-07-28)

1.4.2 (2018-11-26)

1.4.1 (2018-11-26)

1.4.0 (2018-11-25)

1.3.4 (2018-05-05)

1.3.3 (2017-09-28)

1.3.2 (2017-03-26)

1.3.1 (2016-09-21)

1.3.0 (2016-07-15)

1.2.5 (2016-05-23)

1.2.4 (2016-05-15)

1.2.3 (2016-04-04)

1.2.2 (2014-10-24)

1.2.0 (2014-09-12)

1.1.0 (2014-05-07)

1.0.2 (2013-12-16)

1.0.1 (2013-11-29)

1.0.0 (2013-11-21)

Links

The Versions

dev-master

The Requires

The Development Requires

by Jeroen De Dauw

1.3.4

The Requires

The Development Requires

by Jeroen De Dauw

dev-fixdc

The Requires

The Development Requires

by Jeroen De Dauw

1.3.3

The Requires

The Development Requires

by Jeroen De Dauw

1.3.2

The Requires

The Development Requires

by Jeroen De Dauw

1.3.1

The Requires

The Development Requires

by Jeroen De Dauw

1.3.0

The Requires

The Development Requires

by Jeroen De Dauw

1.2.5

The Requires

by Jeroen De Dauw

1.2.4