Peregrine is a PHP5 class known as a cage — a wrapper allowing you filtered access to raw data from superglobals or custom arrays. Available filters range from integer/digits, alpha-numeric, emails, url, IP, phone, name, element_id etc. All methods come in an is__ and get__ flavor, returning boolean or filtered values respectively.
It's very easy to work with Peregrine and to integrate it into your framework or application.
Getting to the Point
include the class in your web application and create an instance of
the object, you may call the
init method to automatically
cage the PHP superglobals -
$peregrine = new Peregrine; $peregrine->init();
Original arrays are destroyed so you're unable to access the data directly. You will now be able to use the filtering methods to securely retrieve your data. For example, a user id passed via GET would be safely returned as an integer.
Checking and Retrieving
Every filter has an is and get version. Peregrine saves a lot of code weight over similar tools
__call() to manage the dual versions for each method.
is returns a boolean if the value passes the filter successfully.
get returns all or part of the value (depending on method) if it passes the filter successfully.
Securing Any Array
You may pass your own arrays to Peregrine using the sanitize method. It will delete your original array so that the data only exists in the returned object.
$yourarray = array('myname'=>'Mike Botsko'); $clean = Peregrine::sanitize( $yourarray );
You may use Peregrine as usual:
Combined Field Validation
When designing a form, you'll often have a single piece of data separated into several fields. Dates and phone numbers are the most common. It's a pain to validate each field separately or to combine the data yourself, and then validate it. Peregrine provides an awesome method that does all of this for you.
For example, if we want to combine month/day/year fields and validate them all as a date, we can:
$p->combine('%s-%s-%s', array('area','prefix','suffix'), 'isPhone');
The first argument is a template string which determines how our fields are to be combined. The second is an array of field names.
The third is which method in Perergrine you want to use to validate the end result, and any additional arguments which need to be passed to the validation method.
For several years we've been primarily using two frameworks that have been developed internally and the excellent Inspekt class was our original choice for a cage object. Over the years we realized that we needed to have more flexibility and some features that were either incomplete or missing. Borrowing the idea and the more complicated regex strings, we created Peregrine.
Peregrine only has one file compared to several with Inspekt. We only have one function foreach filter which really helps keep code weight down. Peregrine allows for default values to be passed and does a better job of maintaining the exact type when multiple types are allowed.
From September 2009 - December 2010 we worked on this first release. That year allowed us to throroughly test the code in large projects.