|Failed to load latest commit information.|
Peregrine - A PHP Security/Caging Class Copyright (c) 2009-2011, Michael Botsko Botsko.net, LLC http://www.botsko.net/peregrine Introduction ============================ Peregrine is a PHP object that aims to improve PHP superglobal security by transferring the raw incoming values to private member variables. You may then access the data using a wide range of more secure filtering functions. You may also pass in arrays of custom data to build a custom cage. The filters available range from integers, alpha-numeric, emails, url, IP, phone, etc. All methods come in an is__ and get__ flavor, returning boolean or valid values respectively. It's very easy to work with Peregrine and to integrate it into your framework or application. Features ============================ - Provides common filtering to securely access data - Wipes original "unsafe" data - Easily integrated into existing code, minimal code - Sanitize custom data, and/or PHP superglobals - Allows both is/get functionality for all methods - get__ methods allow custom default values in case nothing is passed - Combine multiple fields to validate as group - for dates, phone numbers, etc - Growing number of methods for non-standard filtering: names, valid html element id types, etc Basics ============================ First, simply create an instance after including the class file in your code. $peregrine = new Peregrine; To automatically copy and destroy the existing superglobals so that you're forced to access them through the secure cages, simply call the init function: $peregrine->init(); For example, to access an incoming GET value that needs to be an integer, simply call: $peregrine->get->getInt('user_id'); Method Types ============================ All of the available functions may be called with either a get__() or is__() format. For example, to simply test if an array element is a certain value, simply run: $peregrine->get->isInt('user_id'); // will return (bool) You'll get a boolean return telling if it *is* an integer or not. If you want to return the value if it meets your criteria, or at least the characters that do, you may call the get__() version: $peregrine->get->getInt('user_id'); // might equal (int)1 For a complete list of methods, take a look at the peregrine class. Custom Cages ============================ 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: $clean->getName('myname'); Combining Fields ============================ 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('year','month','day'), 'getDate', array('Y-m-d')); The first argument is our template string, which is 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 the fourth is any arguments which need to be passed to the validation method. Known Issues ============================ - The session superglobal is the only one not destroyed because dealing with it is tricky. Since the $_SESSION array is frequently modified by applications, it can refresh it by running: $peregrine->refreshCage('session'); We're working to improve this so that the original session may not be used. Comments or suggestions are appreciated. - Because of how the magic is/get functions work, they pass additional arguments no matter what and those are going to be NULL unless you've set them. The methods were designed to default any additional arguments that are NULL back to their real defaults. If you want a real NULL returned as the default, you'll have to use the real methods with your own condition logic.