ircmaxell/filterus

A library for filtering variables in PHP

1.0.0 2016-08-15 20:09 UTC

This package is auto-updated.

Last update: 2024-09-20 01:06:35 UTC


README

Filter Methods:

Each filter class has two primary methods:

  • $filter->filter($var) - returns a modified version of $var filtered to the options. If it cannot be safely modified, a default value will be returned.
  • $filter->validate($var) - Returns a boolean identifying if the value is valid.

Simple Filters (with options):

  • alnum - Alpha numeric
    • min - 0 - Minimum length
    • max - PHP_INT_MAX - Maximum length
    • default - '' - Default return value
  • array - Array matching
    • min - 0 - Minimum size
    • maximum - PHP_INT_MAX - Maximum size
    • keys - null - Filter to run on the keys
    • values - null - Filter to run on the values
    • default - array() - Default return value
  • bool - Boolean matching
    • default - null - Default return value
  • email - Matches emails
  • float - Floating point numbers
    • min - null - Minimum length
    • max - null - Maximum length
    • default - 0.0 - Default return value
  • int - Integers numbers
    • min - null - Minimum length
    • max - null - Maximum length
    • default - 0 - Default return value
  • ip - Matches IP addresses
    • ipv4 - true - Boolean to match IPv4 addresses
    • ipv6 - true - Boolean to match IPv6 addresses
    • private - true - Include private addresses?
    • reserved - true - Include reserved addresses?
  • object - Objects
    • class - '' - Required class or interface name
    • default - null - The default value
    • defaultFactory - null - A callback to instantiate a return value
  • raw - Returns whatever is passed in
  • regex - Matches strings via a regex
    • min - 0 - Minimum length
    • max - PHP_INT_MAX - Maximum length
    • default - '' - Default return value
    • regex - /.?/ - The regex to run
  • string - Matches strings
    • min - 0 - Minimum length
    • max - PHP_INT_MAX - Maximum length
    • default - '' - Default return value
  • url - Matches URLs
    • path - false - Force a path to be present
    • query - false - Force a query string to be present

Complex Filters

  • Filter::map(array()) - "maps" several filters over key-value pairs. Useful for filtering associative arrays or stdclass objects.
  • Filter::chain($filter1, $filter2...) - Chains multiple filters together to run on the same value (similar to AND joining filters).
  • Filter::pool($filter1, $filter2...) - Runs the same value through multiple filters using the first valid return (similar to OR joining filters)

Usage:

Simple filters can be specified using a comma-separated-value list. So a filter specifying a string with minimum length of 5 could be represented as:

$filter = Filter::factory('string,min:5');

Or

$filter = new Filters\String(array('min' => 5));

If you pass a filter to Filter::factory(), it will be returned unmodified. So you can write functions like:

function foo($bar, $filter) {
    // do something with $bar and set in $baz
    return Filter::factory($filter)->filter($baz);
}

Complex chaining can also be supported. So if you wanted to check if an array with a minimum size of 4, with numeric keys and containing strings of minimum length 5, that could be built like so:

$filter = Filter::array('min:4', 'int', 'string,min:5');

If we wanted to validate an associative array, we would use a "map" filter:

$array = array(
    'foo' => 2,
    'bar' => 'test',
);

$filter = Filter::map(array(
    'foo' => 'int',
    'bar' => 'string,min:4',
));

var_dump($filter->validate($array)); // true

Procedural Interface

Filterus also ships with a procedural interface for calling filters.

\Filterus\filter($var, $filter);

And

\Filterus\validate($var, $filter);

Any filter is supported (both are basically simple wrappers):

function \Filterus\filter($var, $filter) {
    return \Filterus\Filter::factory($filter)->filter($var);
}

Both are just convenience functions.

Security Vulnerabilities

If you have found a security issue, please contact the author directly at me@ircmaxell.com.