README.md

Filterus - A flexible PHP 5.3 filter package

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.