fRequest

static class, v1.0.0b20

Provides request-related methods

This class is implemented to use the UTF-8 character encoding. Please see http://flourishlib.com/docs/UTF-8 for more information.

Please also note that using this class in a PUT or DELETE request will cause the php://input stream to be consumed, and thus no longer available.

Changes:

1.0.0b20	Added `isHead()`, fixed ability to call `set()` on `HEAD` requests 11/23/11
1.0.0b19	Added the `$use_default_for_blank` parameter to `get()` 6/3/11
1.0.0b18	Backwards Compatibility Break - `getBestAcceptType()` and `getBestAcceptLanguage()` now return either `NULL`, `FALSE` or a string instead of `NULL` or a string, both methods are more robust in handling edge cases 2/6/11
1.0.0b17	Fixed support for 3+ dimensional input arrays, added a fixed for the PHP DoS float bug #53632, added support for type-casted arrays in `get()` 1/9/11
1.0.0b16	Backwards Compatibility Break - changed `get()` to remove binary characters when casting to a `string`, changed `int` and `integer` to cast to a real integer when possible, added new types of `binary` and `integer!` 11/30/10
1.0.0b15	Added documentation about `[sub-key]` syntax, added `[sub-key]` support to `check()` 9/12/10
1.0.0b14	Rewrote `set()` to not require recursion for array syntax 9/12/10
1.0.0b13	Fixed `set()` to work with `PUT` requests 6/30/10
1.0.0b12	Fixed a bug with `getBestAcceptLanguage()` returning the second-best language 5/27/10
1.0.0b11	Added `isAjax()` 3/15/10
1.0.0b10	Fixed `get()` to not truncate integers to the 32bit integer limit 3/5/10
1.0.0b9	Updated class to use new fSession API 10/23/09
1.0.0b8	Casting to an integer or string in `get()` now properly casts when the `$key` isn't present in the request, added support for date, time, timestamp and `?` casts 8/25/09
1.0.0b7	Fixed a bug with `filter()` not properly creating new `$_FILES` entries 7/2/09
1.0.0b6	`filter()` now works with empty prefixes and filtering the `$_FILES` superglobal has been fixed 7/2/09
1.0.0b5	Changed `filter()` so that it can be called multiple times for multi-level filtering 6/2/09
1.0.0b4	Added the HTML escaping functions `encode()` and `prepare()` 5/27/09
1.0.0b3	Updated class to use new fSession API 5/8/09
1.0.0b2	Added `generateCSRFToken()` from fCRUDgenerateRequestToken() and `validateCSRFToken()` from fCRUD::validateRequestToken() 5/8/09
1.0.0b	The initial implementation 6/14/07

Static Methods

::check() public

Indicated if the parameter specified is set in the $_GET or $_POST superglobals or in the post data of a PUT or DELETE request

Signature

boolean check( string $key )

Parameters

string $key The key to check - array elements can be checked via [sub-key] syntax

Returns

If the parameter is set

::encode() public

Gets a value from get() and passes it through fHTML::encode()

Signature

string encode( string $key, string $cast_to=NULL, mixed $default_value=NULL )

Parameters

string	$key	The key to get the value of - array elements can be accessed via `[sub-key]` syntax
string	$cast_to	Cast the value to this data type
mixed	$default_value	If the parameter is not set in the `DELETE`/`PUT` post data, `$_POST` or `$_GET`, use this value instead

Returns

The encoded value

::filter() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Parses through $_FILES, $_GET, $_POST and the PUT/DELETE post data and filters out everything that doesn't match the prefix and key, also removes the prefix from the field name

Signature

void filter( string $prefix, mixed $key )

Parameters

string	$prefix	The prefix to filter by
mixed	$key	If the field is an array, get the value corresponding to this key

::generateCSRFToken() public

Returns a request token that should be placed in each HTML form to prevent cross-site request forgery

This method will return a random 15 character string that should be placed in a hidden input element on every HTML form. When the form contents are being processed, the token should be retrieved and passed into validateCSRFToken().

The value returned by this method is stored in the session and then checked by the validate method, which helps prevent cross site request forgeries and (naive) automated form submissions.

Tokens generated by this method are single use, so a user must request the page that generates the token at least once per submission.

Signature

string generateCSRFToken( string $url=NULL )

Parameters

string

$url

The URL to generate a token for, default to the current page

Returns

The token to be submitted with the form

::get() public

Gets a value from the DELETE/PUT post data, $_POST or $_GET superglobals (in that order)

A value that exactly equals '' and is not cast to a specific type will become NULL.

Valid $cast_to types include:

'string'
'binary'
'int'
'integer'
'bool'
'boolean'
'array'
'date'
'time'
'timestamp'

It is possible to append a ? to a data type to return NULL whenever the $key was not specified in the request, or if the value was a blank string.

The array and unspecified $cast_to types allow for multi-dimensional arrays of string data. It is possible to cast an input value as a single-dimensional array of a specific type by appending [] to the $cast_to.

All string, array or unspecified $cast_to will result in the value(s) being interpreted as UTF-8 string and appropriately cleaned of invalid byte sequences. Also, all low-byte, non-printable characters will be stripped from the value. This includes all bytes less than the value of 32 (Space) other than Tab (\t), Newline (\n) and Cariage Return (\r).

To preserve low-byte, non-printable characters, or get the raw value without cleaning invalid UTF-8 byte sequences, plase use the value of binary for the $cast_to parameter.

Any integers that are beyond the range of 32bit storage will be returned as a string. The returned value can be forced to always be a real integer, which may cause truncation of the value, by passing integer! as the $cast_to.

Signature

mixed get( string $key, string $cast_to=NULL, mixed $default_value=NULL, boolean $use_default_for_blank=FALSE )

Parameters

string	$key	The key to get the value of - array elements can be accessed via `[sub-key]` syntax
string	$cast_to	Cast the value to this data type - see method description for details
mixed	$default_value	If the parameter is not set in the `DELETE`/`PUT` post data, `$_POST` or `$_GET`, use this value instead. This value will get cast if a `$cast_to` is specified.
boolean	$use_default_for_blank	If the request value is a blank string and `$default_value` is specified, this flag will cause the `$default_value` to be returned

Returns

The value

::getAcceptLanguages() public

Returns the HTTP Accept-Languages sorted by their q values (from high to low)

Signature

array getAcceptLanguages( )

Returns

An associative array of {language} => {q value} sorted (in a stable-fashion) from highest to lowest q - if no header was sent, an empty array will be returned

::getAcceptTypes() public

Returns the HTTP Accept types sorted by their q values (from high to low)

Signature

array getAcceptTypes( )

Returns

An associative array of {type} => {q value} sorted (in a stable-fashion) from highest to lowest q - if no header was sent, an empty array will be returned

::getBestAcceptLanguage() public

Returns the best HTTP Accept-Language (based on q value) - can be filtered to only allow certain languages

Special conditions affecting the return value:

If no $filter is provided and the client does not send the Accept-Language header, NULL will be returned
If no $filter is provided and the client specifies * with the highest q, NULL will be returned
If $filter contains one or more values, but the Accept-Language header does not match any, FALSE will be returned
If $filter contains one or more values, but the client does not send the Accept-Language header, the first entry from $filter will be returned
If $filter contains two or more values, and two of the values have the same q value, the one listed first in $filter will be returned

Signatures

string|NULL|FALSE getBestAcceptLanguage( array $filter=array() )

string|NULL|FALSE getBestAcceptLanguage( string $language [, ... ] )

Parameters

array	$filter	An array of languages that are valid to return - these should be in the form `{language}-{territory}`, e.g. `en-us`
string	$language [, ... ]	A language that is valid to return

Returns

The best language listed in the Accept-Language header - see method description for edge cases

::getBestAcceptType() public

Returns the best HTTP Accept type (based on q value) - can be filtered to only allow certain types

Special conditions affecting the return value:

If no $filter is provided and the client does not send the Accept header, NULL will be returned
If no $filter is provided and the client specifies */* with the highest q, NULL will be returned
If $filter contains one or more values, but the Accept header does not match any, FALSE will be returned
If $filter contains one or more values, but the client does not send the Accept header, the first entry from $filter will be returned
If $filter contains two or more values, and two of the values have the same q value, the one listed first in $filter will be returned

Signatures

string|NULL|FALSE getBestAcceptType( array $filter=array() )

string|NULL|FALSE getBestAcceptType( string $type [, ... ] )

Parameters

array	$filter	An array of types that are valid to return
string	$type [, ... ]	A type that is valid to return

This method is primarily intended to be used for hanlding multiple submit buttons.

Signature

void overrideAction( string $redirect=NULL )

Parameters

string $redirect The url to redirect to if the action is overriden. %action% will be replaced with the overridden action.

::prepare() public

Gets a value from get() and passes it through fHTML::prepare()

Signature

string prepare( string $key, string $cast_to=NULL, mixed $default_value=NULL )

Parameters

string	$key	The key to get the value of - array elements can be accessed via `[sub-key]` syntax
string	$cast_to	Cast the value to this data type
mixed	$default_value	If the parameter is not set in the `DELETE`/`PUT` post data, `$_POST` or `$_GET`, use this value instead

Returns

The prepared value

::reset() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Resets the configuration and data of the class

Signature

void reset( )

::set() public

Sets a value into the appropriate $_GET or $_POST superglobal, or the local PUT/DELETE post data based on what HTTP method was used for the request

Signature

void set( string $key, mixed $value )

Parameters

string	$key	The key to set the value to - array elements can be modified via `[sub-key]` syntax
mixed	$value	The value to set

::unfilter() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

Returns $_GET, $_POST and $_FILES and the PUT/DELTE post data to the state they were at before filter() was called

Signature

void unfilter( )

::validateCSRFToken() public

Validates a request token generated by generateCSRFToken()

This method takes a request token and ensures it is valid, otherwise it will throw an fValidationException.

Signature

void validateCSRFToken( string $token, string $url=NULL )

Parameters

string	$token	The request token to validate
string	$url	The URL to validate the token for, default to the current page

Throws

fValidationException: When the CSRF token specified is invalid

fRequest

Class Resources

Static Methods

Uses

Used By

Static Methods

::check() public

Signature

Parameters

Returns

::encode() public

Signature

Parameters

Returns

::filter() internal public

Signature

Parameters

::generateCSRFToken() public

Signature

Parameters

Returns

::get() public

Signature

Parameters

Returns

::getAcceptLanguages() public

Signature

Returns

::getAcceptTypes() public

Signature

Returns

::getBestAcceptLanguage() public

Signatures

Parameters

Returns

::getBestAcceptType() public

Signatures

Parameters

Returns

::getValid() public

Signature

Parameters

Returns

::isAjax() public

Signature

Returns

::isDelete() public

Signature

Returns

::isGet() public

Signature

Returns

::isHead() public

Signature

Returns

::isPost() public

Signature

Returns

::isPut() public

Signature

Returns

::overrideAction() public

Signature

Parameters

::prepare() public

Signature

Parameters

Returns

::reset() internal public

Signature

::set() public

Signature

Parameters

::unfilter() internal public

Signature

::validateCSRFToken() public

Signature

Parameters

Throws