Download the PHP package flsouto/param without Composer

Param

Overview

This library allows you to extract, filter and validate individual fields from an associative array. It can be used, as an example, to validate request variables sent from a web browser. You give each parameter a "name", define the "context" and call "process"; the result will be the value extracted from the context or an error message in case of not conforming to one or more validation filters. Many predefined filters and validators are available from a "finger-friendly" API. You can also specify a fallback value to be returned in case of validation error.

Installation

Install via composer:

Usage

The example bellow creates a parameter and prints out its name

You can instantiate the parameter from the static get method which always returns the same instance for that name:

The output will be:

Processing Input

The process instance method receives a "context", which must be an associative array, and tries to extract the parameter value based on the parameter name.

The output of the above will be:

Predefined Contexts

You can set the context on the parameter instance before calling the process method:

If you want to set the context and be able to modify it later, I recommend you provide an instance of ArrayObject like in the example bellow:

Furthermore, you can work with the ParamContext class which allows you to factory parameters from a predefined context. Read more about it on the "ParamContext" section.

Namespaced Params

You can use square brackets for a fully qualified name. In the following example, the parameter 'email' is found inside the hierarchy user > contact:

The output of the above will be:

Validation

The param object uses an instance of the Pipe class which allows you to bind a series of filters and/or validators to the data:

Output:

The above snippet adds a filter that trims the parameter value, and also adds a validator that produces an error if the final value is empty. The printed error message is then captured inside the $result->error property.

Notice: the Param class actually provides a bunch of common filters and validatiors through the ParamFilters API. More on this subject in the "ParamFilters API" section.

Fallback values

You can specify a fallback value to be returned in the $result->output in case validation fails.

The output will be:

Setting up defaults

The library provides the static setup method which allows you to intercept all param instances upon their creation. In the example bellow we define the default context for every parameter in our application to be the $_REQUEST superglobal, and we also set all parameters to be trimmed by default:

The output from the above code will be:

Method chaining

Last but not least, all setters of the Param class return the instance itself, so it is possible to use method chaining:

ParamContext

The ParamContext allows you to create params out of a predefined context. It's actually a wrapper to the ArrayObject class that keeps track of added parameters:

The output will be an associative array with all the parameters extracted:

You can still process an individual param and get its output:

The output will be:

Validation

If there are any errors, these will be available as an associative array inside the ´$result->errors´ variable.

Output:

ParamFilters

The Param class has an instance method filters which returns an instance of ParamFilters. This class makes the process of filtering and validating data much easier.

The following sections are dedicated to showing the usage of each method in that object.

trim

Removes espaces from start and end of a string.

replace

The replace filter allows you to replace one string with another, similar to php's str_replace function:

replace using regex

If you wrap the search pattern between two slashes, a regular expression will be assumed.

Another example using regex with the "i" modifier:

strip

Matches a string or a regex pattern and remove it from the string:

required

Makes sure the value is not empty. If empty, an error message is produced.

All validators have default error messages that can be customized. Bellow is an example of redefining the default error message:

ifmatch

Produces an error when the string MATCHES A PATTERN:

Another example using regex modifiers:

Notice: This validator is only applied when the value is not empty:

If you want to make sure the value is not empty use the required filter before ifmatch.

ifnot

Produces an error when the string DOES NOT MATCH a pattern:

Notice: This validator is only applied when the value is not empty:

maxlen

Makes sure the length of the string doesn't exceed a maximum:

minlen

Makes sure the length of a string is at least certain characters long:

Notice: This validator is only applied when the value is not empty:

maxval

Makes sure an integer is not more than certain value:

minval

Makes sure the integer, if provided, is at least larger than X:

Notice: This validator is only applied when the value is not empty:

Chaining filters

Last but not least, you can use method chaning for adding multiple filters. The filters will be applied to the value in the same order they were added:

In the example above the data will be filtered before the validation constraints and the result will be: