Development Wiki

Function.request var

From phpBB Development Wiki

Revision as of 05:46, 15 March 2010 by Chiron (Talk | contribs)

request_var –– Get passed variables from $_GET, $_POST, or $_COOKIE


  1. mixed request_var ( $var_name , $default [, $multibyte [, $cookie ]] )

Input variables provided to the script via the GET, POST, and COOKIE input mechanisms, cannot be trusted. Make use of the request_var() function for anything except for submit or single checking params. The request_var function determines the type (see type casting) to set from the second parameter (which determines the default value as well). If you need to get a scalar variable type, you need to tell this to the request_var function explicitly.


Parameter Usage
var_name The name of the variable to pull (i.e. $_REQUEST['var'] is the same as request_var('var', '');)
default The default parameter has a dual purpose. The first is to cast the variable type, and the second is to set a default value if the requested var does not exist.
multibyte (optional, default is false) request_var does allow multibyte characters to return in requests unless you explicitly set this to true for the variable you request.
cookie (optional, default is false) Get the value of a variable from a cookie. ($_COOKIE['var'])

Return Values

Mixed - Returns the value from the requested variable if set, otherwise, returns the value of the default parameter, returned variable is type casted to the default parameter.


Example #1 Old method, do not use it

This was the method used within phpBB2; it is no longer valid within phpBB3.

$start = (isset($HTTP_GET_VARS['start'])) ? intval($HTTP_GET_VARS['start']) : intval($HTTP_POST_VARS['start']);
$submit = (isset($HTTP_POST_VARS['submit'])) ? true false;

Example #2 set default and type cast to integer

Use request var and define a default variable (use the correct type)

$start request_var('start'0);

// because we only determine if the variable isset, and only a $_POST variable, this is permitted
$submit = (isset($_POST['submit'])) ? true false;

Example #3 Incorrectly setting variable type

Because $start is an int, the following use of request_var is not allowed. This is a common mistake and could result in an SQL Injection if the variable is expected to be an integer and is inserted into a Database Query without proper sanitisation.

$start request_var('start''0');

Example #4 Getting Arrays - value casted to int

Getting an array, keys are integers, value defaults to 0

$mark_array request_var('mark', array(0));

Example #5 Getting Arrays - value casted to string

Getting an array, keys are strings, value defaults to 0

$action_ary request_var('action', array('' => 0));

Example #6 Getting Multibyte chars

Requesting a multibyte string

$message utf8_normalize_nfc(request_var('message'''true));

Example #7 Getting a Decimal (float)

Requesting a float variable -- also known as a double or decimal

$price request_var('price'0.0);

Example #8 Getting variable from a cookie

To get a variable that is hold in a cookie you'll have to set the forth parameter to true

$cookie request_var('cookie_time'0falsetrue);


Unicode (UTF-8) Support

With request_var() you can either allow all UCS characters in user input or restrict user input to ASCII characters. This feature is controlled by the function's third parameter called $multibyte. You should allow multibyte characters in posts, PMs, topic titles, forum names, etc. but it's not necessary for internal uses like a $mode variable which should only hold a predefined list of ASCII strings anyway.

Unicode Normalisation

If you retrieve user input with multibyte characters you should additionally normalize the string using utf8_normalize_nfc() before you work with it. This is necessary to make sure that equal characters can only occur in one particular binary representation. For example the character Å can be represented either as U+00C5 (LATIN CAPITAL LETTER A WITH RING ABOVE) or as U+212B (ANGSTROM SIGN). phpBB uses Normalization Form Canonical Composition (NFC) for all text. So the correct version of the above example would look like this:
$_REQUEST['multibyte_string'] = 'Käse';

// normalize multibyte strings
echo utf8_normalize_nfc(request_var('multibyte_string'''true));
// ASCII strings do not need to be normalized
echo request_var('multibyte_string''');

See Also