phpBB

Development Wiki

Difference between revisions of "Function.request var"

From phpBB Development Wiki

m (Category + See Also)
m (corrected formatting)
Line 2: Line 2:
  
 
==Description==
 
==Description==
<code>mixed '''request_var''' ( $var_name , $default [, $multibyte [, $cookie ]] )</code>
+
#<pre>mixed request_var ( $var_name , $default [, $multibyte [, $cookie ]] )</pre>
 
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.
 
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.
  
Line 62: Line 62:
 
==Notes==
 
==Notes==
 
===Unicode (UTF-8) Support===
 
===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.
+
: <div class="toc" style="padding:10px;">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.</div>
 
===Unicode Normalisation===
 
===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:
+
: <div class="toc" style="padding:10px;">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:<br><php>$_REQUEST['multibyte_string'] = 'Käse';
<php>$_REQUEST['multibyte_string'] = 'Käse';
+
  
 
// normalize multibyte strings
 
// normalize multibyte strings
 
echo utf8_normalize_nfc(request_var('multibyte_string', '', true));
 
echo utf8_normalize_nfc(request_var('multibyte_string', '', true));
 
// ASCII strings do not need to be normalized
 
// ASCII strings do not need to be normalized
echo request_var('multibyte_string', '');</php><br>
+
echo request_var('multibyte_string', '');</php></div><br>
  
 
==See Also==
 
==See Also==
 
* [[utf8_normalize_nfc]]
 
* [[utf8_normalize_nfc]]
 +
* [[type casting]]
 +
 
<br><br>
 
<br><br>
 
[[Category:Functions]]
 
[[Category:Functions]]

Revision as of 21:22, 21 September 2008

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

Description

  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.

Parameters

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.

Examples

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

$start is an int, the following use of request_var therefore 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);

Notes

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