Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ircmaxell/filterus

A simple filtering library for PHP
https://github.com/ircmaxell/filterus

Last synced: 30 days ago
JSON representation

A simple filtering library for PHP

Lists

README 

        
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:



``` php

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

```



Or



``` php

$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:



``` php

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:



``` php

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

```



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



``` php

$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.



``` php

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

```



And



``` php

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

```



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



``` php

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 [[email protected]](mailto:[email protected]).