## What is Inspekt
Inspekt is an input filtering and validation library for PHP4 and PHP5.
### Driving principles behind Inspekt
1. Accessing user input via the PHP superglobals is inherently dangerous, because the "default" action is to retrieve raw, potentially dangerous data
2. Piecemeal, "inline" filtering/validation done at various places in an application's source code is too error-prone to be effective
3. The purpose of a library or framework is to make a programmer's job easier. Verbose and/or complex solutions should be avoided unless they are the *only* solution
### Features of Inspekt
* 'Cage' objects that encapsulate input and require the coder to use the provided filtering and validation methods to access input data
* Automatic application of filtering as defined in a configuration file
* A library of static filtering and validation methods
* A simple, clear API
* No external dependencies
## Basic Usage
Here's a simple example of the most common way to use Inspekt. Here we:
1. Require the library
2. create an [`Inspekt_Supercage`](#supercage) to wrap all input inside [`Inspekt_Cage`](#cage) objects
3. check to see if the 'userid' value from the POST input is an integer
* If so, $userid is assigned the value and it's inserted into a database
* If not, an error is triggered
####Example

## Filtering and Validating Input with Input Cages
`Inspekt_Cage` objects take an array of data and encapsulate it, so the values in the array can only be accessed through the methods of the `Input_Cage` object. The original array is destroyed by default, so the data *must* be accessed via the cage object's methods.
#####Example

// make a supercage and assign it to $input
$input = Inspekt::makeSuperCage();
// get email_addr from $_GET if it is a valid email, or trigger an error
if ($email_addr = $input->get->testEmail('email_addr')) {
echo "valid email address";
} else {
trigger_error('invalid email address', E_USER_ERROR);
}

### Predefined filtering with configuration files
The `Inspekt::makeSuperCage()` method optionally takes a path to a configuration file. The config file defines a set of filters to apply globally and/or to a specific input parameter. Filters defined in a configuration file are applied immediately, and are *destructive* – they will alter the value stored inside the Supercage.
#####Example

### "Array Path" queries for multidimensional arrays
Inspekt uses a special kind of formatting to make it easier to grab an arbitrary key from a deep multidimensional array. Let's take a form example like this:
#####Example

Notes on array path querying:
* The forward slash "/" is the separator, so you can't access keys where you're using that character
* Any numeric keys are converted to integers, so you can't access keys that are numeric strings
* All queries must include the full path from the root of the array
* Leading and trailing slashes are ignored. These are all equivalent:
'/x/woot/booyah/'
'/x/woot/booyah'
'x/woot/booyah/'
'x/woot/booyah'
### Dealing with different scopes
PHP's superglobals are convenient in that they maintain a global scope without the need to declare then as globals in each function. PHP unfortunately does not allow user-defined superglobals,
All of the `Inspekt::make*Cage()` methods utilize a singleton pattern. This means the developer does not have to pass the cage object to and from functions, or use the global keyword, to access it outside the global scope. Just use the make*Cage() method to access the same object you created in a different scope.
#####Example

## Using static methods
Inspekt also provides a library of filtering and validation methods that can be called statically. In cases where a simple one-off check makes more sense, you can use these instead of creating an `Inspekt_Cage` or `Inspekt_Supercage` object.
#####Example