Download the PHP package gobline/filter without Composer

Filter component

The Filter component is used to sanitize and/or validate variables. Its power lies in the ability to define "filter funnels" which allow to filter a variable through multiple (built-in or custom) sanitizers and validators easily at once.

There are two kinds of filters:

• Sanitizers sanitize the data. They may alter the data like removing undesired characters.
• Validators validate the data. They return true if the data is valid, false otherwise.

Sanitizers

Example:

Built-in Sanitizers

• Cast
• Lower
• LTrim
• RTrim
• StripTags
• Trim
• Upper

Validators

Example:

Built-in Validators

• Alpha
• Alphanum
• Between
• Boolean ('', '0', '1', 0 and 1 are considered valid booleans)
• Email
• Float (numeric strings are considered valid integers)
• Int (numeric strings are considered valid integers)
• Length
• Max
• Min
• NoTags
• Required
• Regex
• Value
• Scalar

Note:

A distinction can been made between two groups of validators:

• data validators check if the data meets certain qualifications.
• data type validators check if the variable is of a certain data type.

This is because it is important to know that data validators may expect the variable to filter to be of a specific type, and will consequently throw an exception if the type is unexpected (e.g. Length validator expects a string), whereas data type validators will never throw exceptions.

Data type validators include: Alpha, Alphanum, Boolean, Email, Float, Int, Scalar

Data validators include: Between, Length, Max, Min, NoTags, Required, Regex, Value

Error messages

It is possible to retrieve the validator's error messages in case data failed validating.

Customization of error messages is supported:

Note that you can use placeholders as %value% above. Each validator has its own placeholders (all of the built-in validators have at least %value%). For example, the validator Between who checks if a number is between two numbers provides 3 placeholders: %value%, %min% and %max%. Its default message is: The input is not between "%min%" and "%max%" (inclusively).

Translator

You can add a translator for your error messages globally

or for an instance

Filter Funnels

The real value of the component is its ability to create filter funnels. Filter funnels allow you to filter a variable through multiple sanitizers and/or validators at once.

Below is an example that trims the variable and checks if it contains a valid age (between 0 and 110). Eventually it will cast the variable to an integer.

If one of the validators invalidates data, the funnel will return (and will not execute the sanitizers and validators that follow).

It is possible to register filters in a class map in order to reference the filters by classname when using the funnel. Built-in filters are registered in the class map by default. The example above could be rewritten as follows:

The above could also be written like:

or

or

Optional Values

or

If is an empty string or null, the filter funnel will return null without any error messages as the field is optional.

Adding Custom Filters

To add your own custom filters into the class map, use the factory class:

You can still set custom messages for validators when using funnels:

Note that should directly follow an call or an exception will be thrown.

Object Filters

You can filter an object's properties by implementing the interface.

Installation

You can install the Filter component using the dependency management tool Composer. Run the require command to resolve and download the dependencies: