RequestCleaner

Usage

Create a new request cleaner:

$rc = new RequestCleaner(sources, use_modes, error_mode) – where:

sources is a comma separated string OR an array with one or more of: GET, POST, REQUEST
use_modes is the bitwise OR of
- RequestCleaner::USE_HTMLENTITIES – process each parameter with htmlentities() [default]
- RequestCleaner::USE_HTMLSPECIALCHARS – process each parameter with htmlspecialchars()
- RequestCleaner::USE_NL2BR – process each parameter with nl2br()
error_mode – determines how the beast responds to errors – such as non-existing query parameters. Use one of:
- RequestCleaner::RETURN_NULL – returns NULL [default]
- RequestCleaner::RETURN_FALSE – returns FALSE – can be distinguished from NULL by ’=’ and ’!’
- RequestCleaner::THROW_EXCEPTION – throws an exception

For example:

$rc = new RequestCleaner(‘POST’, RequestCleaner::USE_HTMLENTITIES | RequestCleaner::USE_NL2BR,
RequestCleaner::THROW_EXCEPTION);

To get a ‘cleaned’ query parameter, use ’$rc->parm’, where parm is the parameter name. For example, if ‘foo’ is a POST parameter, then ’$rc->foo’ will return the value of ‘foo’ from after running the ‘cleaning’ routines on it.

Fine points

All Cleaned data is cached in a RequestCleaner Class Variable, as are the sources, use and error modes. This means that a top level PHP program can set up the method of cleaning and allowed sources and all included code which uses any instance of a RequestCleaner will use the same methods and cache.

Consequently, you can either create a RequestCleaner instance at top level OR in any included or required file which needs to access query parameters. It doesn’t matter.

Attempts to access undefined attributes generate an error – as specified by error_mode.

Query parameters which return arrays – as in <input type=... name=“foo[]” ...> – are turned into arrays of cleaned strings which can be processed using normal loops and array_…() functions.

Extensive use of Magic Methods are used to implement the following operations [presume that $rc is an instance of RequestCleaner]:

$rc->foo – returns the cleaned value of the request parameter foo if it exists. It is cached, if not already cached, to make lookeup and cleaning more efficient. The cleaning is as is implemented in the First instantiaion of RequestCleaner [normally in the controller] If foo is not defined, then the failure method chosen when this instance of RequestCleaner was created is invoked.
$rc->foo = bar – generates an error return – using the method specified for this instance of rc
unset($rc->foo) – removes foo from the cache; attempts to remove foo from the source variable arrays [$_POST, $_GET, $_REQUEST] [which will fail as of PHP 5.2.9]; removes foo from $GLOBALS; and marks foo as ‘unset’ in a local array so it will not be retrieved in future invocations of $rc->foo [attempting to retrieve $rc->foo will result in the action specified for any other no-existant parameter]
isset($rc->foo) – returns TRUE if $rc->foo will return something; FALSE if it will invoke the failure method specified.

Instance Methods

dump() – returns a string giving all passed parameters – after cleaning – in the form of ‘parameter => value’
param_array(names = NULL) – returns an associative array of EITHER all the parameters or those specified in names. names may be an array of key names or a comma separated list in a string. The returned set is trimmed to only those parameters which actually exist, so optional parameters may be specified without causing an error.

ERROR_MODE_MASK = 3.

RETURN_NULL = 1.

RETURN_FALSE = 2.

THROW_EXCEPTION = 3.

USE_HTMLENTITIES = 1.

USE_HTMLSPECIALCHARS = 2.

USE_NL2BR = 4.