Extension:ParamProcessor/1.0

This page is meant to give an overview of the workflow of Validator 1.0, which is significantly different then the previous version (0.4.x). The picture drawn here is conceptual, some implementation details are ignored, and the method names used might not be correct or refer to a single actual method, but should still make you understand how it works.

Some further architectural changes are being made on the ValueHandler level, however the workflow in Validator should end up being similar to what's described here.

Validator is a parameter processor that takes a list of parameter definitions and parameter values, and parses, validates and formats the later based on the former.

Validator/Validator

The Validator class, which would be better named ParameterProcessor, takes a list of parameter definitions and parameter values. Processing can be invoked via some method, after which the processed values and other results of the processing (ie errors and warnings) can be obtained via various methods.

Validator/Validator::process( $definitions, $values, $options )

This method is the entry point for the whole processing procedure. It invokes several methods in the Validator class which take care of high level parameter management, such as resolving of aliases (for parameter names) and resolving of dependencies. After that is done, a method loops over the parameters and handles the task of processing to the Param class of each.

Validator/Param

The Param class holds the value of a parameter as well as it's definition (see next section). It's created in the Validator class and is only used internally for processing (although it can be obtained via Validator afterwards if one wishes to). Creating set the parameter value and it's definition in the object.

Validator/Param::process

It does the following steps in provided order:

• Value cleanup
• Value parsing
• (if successful) Value validation
• Value formatting

Details of these steps depend on the parameters definition.

If there is an error during parsing or validation, the next steps are not done. In case a default value is provided for the parameter, such an error will result in the value being set to the default. The default is also set when no value was provided for the parameter. The default can still go through the value formatting step if so specified in the definition.

Validator/Param::cleanup

This does things such as trimming and lowercasing of the value.

Validator/Param::parsing

This method passes the value to a ValueParser object (which is obtained via the definition). The result of this method contains either the parsed value or a list of errors. If it's the parsed value, this is the value that's used later on for validation and formatting.

Validator/Param::validation

This consists of three steps:

• If set, the value is passed to a validation callback.
• This method passes the value to a ValueValidator object (which is obtained via the definition). The result contains a list of errors (which on success is empty).
• The result is passed to a ListValidator object (which derives from ValueValidator and is obtained via the definition). The result contains a list of errors (which on success is empty).

The validation callback is useful for trivial validation. For instance checking if something is a boolean can be done passing 'is_bool' and does not require it's own class.

The ValueValidator and ListValidator implementing objects (those interfaces are defined in ValueHandler, see below) validate the individual values of lists and lists as a whole, respectively. For non-list values, only the ValueValidator is used. For lists, the ValueValidator is applied to each element, and the ListValidator is used afterwards.

Validator/Param::format

Additional formatting via the parameter definition.

Validator/ParamDefinition

This class defines a parameter. This includes how it should be parsed, how it should be validated, how it should be formatted, how it should be displayed, a text description, ect. A lot of this behavior is specified by the parameters type, which by default is string. For instance, integers need to be parsed from string to integer (if you have string parameters). So types indicate the ValueParser and ValueValidator to use. In case of an integer, an IntegerValidator is used. Different ValueValidators (and thus different types) accept different options. For instance, an IntegerValidator allows specifying upper and lower bounds, while a StringValidator allows setting min and max length.

Parameter definitions are typically specified as associative arrays with specific format, which are then transformed into actual ParamDefinition objects. This is done via a factory, ParamDefinitionFactory, which resolves the type, instantiates the correct ParamDefinition class and sets the parser and validator specified by the type.

Example definition:

$params['includesubject'] = array(
        'type' => 'boolean',
        'message' => 'srf-paramdesc-includesubject',
        'default' => false,
);

ValueHandler

Separate library extension with low level param handling components.

ValueHandler/ValueParser

interface ValueParser {
 
        /**
         * Parses a value.
         *
         * @since 0.1
         *
         * @param mixed $value The value to parse
         *
         * @return ValueParserResult
         */
        public function parse( $value );
 
}

interface ValueParserResult {
 
        /**
         * @since 0.1
         *
         * @return mixed
         */
        public function getValue();
 
        /**
         * @since 0.1
         *
         * @return boolean
         */
        public function isValid();
 
        /**
         * Returns error in case the value is invalid or null otherwise.
         *
         * @since 0.1
         *
         * @return ValueHandlerError|null
         */
        public function getError();
 
}

ValueHandler/ValueValidator

interface ValueValidator {
 
        /**
         * Parses a value.
         *
         * @since 0.1
         *
         * @param mixed $value The value to validate
         *
         * @return ValueValidatorResult
         */
        public function validate( $value );
 
        /**
         * Takes an associative array with options and sets those known to the ValueValidator.
         *
         * @since 0.1
         *
         * @param array $options
         */
        public function setOptions( array $options );
 
}

interface ValueValidatorResult {
 
        /**
         * Returns if the value was found to be valid or not.
         *
         * @since 0.1
         *
         * @return boolean
         */
        public function isValid();
 
        /**
         * Returns an array with the errors that occurred during validation.
         *
         * @since 0.1
         *
         * @return array of ValueHandlerError
         */
        public function getErrors();
 
}