Description and download Unit test and UT source Library source code

Description

superGlobals is a PHP library that transparently injects into a superglobal or global variable while keeping all functionality of a regular array, but extending it with type casting and URI parsing into that array.

It can use memcached for additional performance and can interact with custom DB abstractions (mostly PEAR).

It may filter, cast, or validate variables as: boolean, integer, float, string, array, object, IPv4 address, IPv6 address, regular expression, URL, URL encoded string, HTML escaped string, or SQL escaped string.

It is possible to pass a function name callback as a casting or validation method. Also, it is possible to pass multiple casting methods for each variable, which is useful for array processing.

Easiest way to start using

Using of this library is very simple. Just put this library into your project directory and add these lines at the beginning of your script: require_once('superglobals.php');
superGlobal::start();
Congratulations ! Now you have library installed and running, so you can access all $_GET variables with modifiers or tune instance\register additional params, as described below.

Info on usage

Casting methods

After injecting it provides several casting methods for all of array variables, which should be defined in requesting variable name and separated from it by semicolon: Fetch variable as boolean (returns boolean): $_SUPERGLOBAL['bool:key'] Fetch variable as integer (returns integer): $_SUPERGLOBAL['int:key'] Fetch variable as float (returns float): $_SUPERGLOBAL['float:key'] Fetch variable as regular string (returns string): $_SUPERGLOBAL['string:key'] Fetch variable as array (returns array): $_SUPERGLOBAL['array:key'] Fetch variable as IP address (IPv6 or IPv4) (returns string): $_SUPERGLOBAL['ip:key'] Fetch variable as IP address (IPv4 or IPv6), only from public networks (returns string): $_SUPERGLOBAL['ippub:key'] Fetch variable as IP address (only IPv4) (returns string): $_SUPERGLOBAL['ipv4:key'] Fetch variable as IP address (only IPv6) (returns string): $_SUPERGLOBAL['ipv6:key'] Fetch variable as regular expression (returns string): $_SUPERGLOBAL['regexp:key'] Fetch variable as correct URL (returns string): $_SUPERGLOBAL['url:key'] Fetch variable as URL encoded string (returns string): $_SUPERGLOBAL['encode:key'] Fetch variable as HTML escaped string (returns string): $_SUPERGLOBAL['escape:key'] Fetch variable as regular object (returns object): $_SUPERGLOBAL['object:key'] Fetch variable as SQL escaped string (returns string): $_SUPERGLOBAL['sql:key'] It is possible to pass function name callback as casting method, for example, next will return trimmed value of $_SUPERGLOBAL['key']. $_SUPERGLOBAL['trim:key'] Also, it is possible to pass multiple casting methods, which is useful for array processing, next will return an array with all matching values for $_SUPERGLOBAL['key'] casted to float and then cos() function applied. $_SUPERGLOBAL['array:float:cos:key']

Tuning and instantiating

Init library and inject into $_GET. Useful when you do not want to register additional parameters superGlobal::start(); Set DB instance for all DB-related operations. superGlobal::db($instance); Set Memcache instance to enable built-in cache superGlobal::memcached($instance) Inject superGlobal functionality into global or superglobal variable. If additional parameters passed with registerParam or registerSQLParam overlaps already existing parameters in array, initial value will be stored in parameter array, which is accessible as $array['array:param'].

If pointed variable contains string, it will be stored as URI for future parsing by registerParam or registerSQLParam methods.
superGlobal::inject($array_name|$string_name); Inject into $_GET (if was not injected previously), then parse URI parameters into all of injected global arrays and only $_GET superglobal array, so if URI string parameter (REQUEST_URI for $_GET or manually provided for other arrays) contains parameter from values array provided or provided callback function will return something different from false, this piece will be stored in resulting array with name key. superGlobal::registerParam('name', 'callback');
superGlobal::registerParam('name', array(values));
Same as previous example, except URI parameter will be additionally casted into provided type. superGlobal::registerParam('type:name', 'callback');
superGlobal::registerParam('type:name', array(values));
List of possible values for parameter will be fetched from SQL table 'table' from field 'field'. (DB abstraction instance should be provided and getCol method should be implemented) superGlobal::registerSQLParam('name', 'table', 'field');
superGlobal::registerSQLParam('type:name', 'table', 'field');
Register param into only one array. Also allows to inject parameters into superglobal arrays different from $_GET. superGlobal::registerParam('name', array(values), $array);
superGlobal::registerParam('name', 'callback', $array);
superGlobal::registerSQLParam('name', 'table', 'field', $array);

Possible exceptions

May throw exceptions (Exception $e) with codes: 1: Trying to directly create an instance of class
100: DB driver is not set or method missing
200: There is no filter.so installed
300: Callback or casting (if enabled) exception
400: Trying to register variable that is not global
500: Incorrect use of registerParam or registerSQLParam functions
600: Memcache exception

Download

Download from ics.net.ua
FreshMeat project page


License

Copyright © 2009, Max S. Yarchevsky, Intercom Service
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.