View source for Secure coding guidelines

==Getting Data from the Request== <!--T:2-->
{{JVer|3.x}} Starting with Joomla version 3.0, [[Retrieving_request_data_using_JInput|JInput]] should be used instead of [https://api.joomla.org/cms-3/classes/JRequest.html JRequest].


<!--T:3-->
All input originating from a user must be considered potentially dangerous and must be cleaned before being used. You should always use the Joomla [[Retrieving_request_data_using_JInput|JInput]] class to retrieve data from the request, rather than the raw $_GET, $_POST or $_REQUEST variables as the [[Retrieving_request_data_using_JInput|JInput]] methods apply input filtering by default. JInput deals with all aspects of the user request in a way that is independent of the request method used. It can also be used to retrieve cookie data and even server and environment variables. However, it is important to use the correct [[Retrieving_request_data_using_JInput|JInput]] method to ensure maximum security. It is very easy to just use the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] method with default parameters and ignore the fact that in many cases it is possible to apply a more stringent requirement on user input.

<!--T:4-->
It very important to understand that the [[Retrieving_request_data_using_JInput|JInput]] methods are not SQL-aware and further work is required to guard against SQL injection attacks.There is no default value that will be returned if no default is specified in the call the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]]. If no default is specified and the argument is not present in the request variable then it will return undefined.

<!--T:5-->
Using [[Retrieving_request_data_using_JInput|JInput]] also obviates the need to pay attention to the setting of magic_quotes_gpc. [[Retrieving_request_data_using_JInput|JInput]] does the right thing, regardless of whether magic_quotes_gpc is on or off. See http://php.net/manual/en/security.magicquotes.php for further information.

<!--T:6-->
When considering user input you should think about the data type you are expecting to retrieve and apply the most stringent form of [[Retrieving_request_data_using_JInput#Getting_Values|JInput]] that is applicable in each case. In particular, avoid the lazy approach of using [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] as this will return an array that may contain entries that you did not expect and although each of those entries will have been cleaned, it is often the case that additional filtering could have been applied to some individual arguments. For example, the get method treats all arguments as strings, whereas it may be possible to restrict some arguments to be integers.

<!--T:7-->
The first three parameters of each of the JInput get methods are the same. Only the first parameter is mandatory. In general, the format is
<syntaxhighlight lang="php">
    JFactory::getApplication->input-><data-source>->get<type>( <name>, <default> )
</syntaxhighlight>
where

<!--T:8-->
{| class="wikitable" border="1"
| <type> || the data type to be retrieved (see below for the types available).
|-
| <name> || the name of the variable to be retrieved (for example, the name of an argument in a URL).
|-
| <default> || the default value.
|-
| &lt;data-source&gt; || specifies where the variable is to be retrieved from (see below).
|}

<!--T:9-->
The following values for &lt;data-source&gt; are supported:

<!--T:10-->
{| class="wikitable" border="1"
| get || Data submitted in the query part of the URL.
|-
| post || Data submitted from form fields.
|-
| method || The same as either GET or POST depending on how the request was made.
|-
| cookie || Data submitted in cookies.
|-
| request || All the GET, POST and COOKIE data combined. This is the default.
|-
| files || Information about files uploaded as part of a POST request.
|-
| env || Environment variables (platform-specific).
|-
| server || Web server variables (platform-specific).
|}

<!--T:11-->
Notice that the default is REQUEST, which includes cookie data.

<!--T:12-->
The following sections look at each of the data types in more detail.

===Integer=== <!--T:13-->
The following will accept an integer. An integer can include a leading minus sign, but a plus sign is not permitted.
<syntaxhighlight lang="php">
$integer = JFactory::getApplication->input->getInt( 'id' );
</syntaxhighlight>
will return the value of the "id" argument from the request (which by default includes all GET, POST and COOKIE data). The default value is zero.
<syntaxhighlight lang="php">
$integer = JFactory::getApplication->input->cookie->getInt( 'myId', 12 );
</syntaxhighlight>
will return the value of the "myId" variable from a cookie, with a default value of 12.

===Floating Point Number=== <!--T:14-->
A floating point number can include a leading minus sign, but not a plus sign. If the number includes a decimal point, then there must be at least one digit before the decimal point. For example,
<syntaxhighlight lang="php">
$float = JFactory::getApplication->input->getFloat( 'price' );
</syntaxhighlight>
will return the value of the 'price' argument from the request. The default is "0.0".
<syntaxhighlight lang="php">
$float = JFactory::getApplication->input->post->getFloat( 'total', 100.00 );
</syntaxhighlight>
will retrieve the value of the 'total' argument from a POST request (but not a GET), with a default value of 100.00.

===Boolean Value=== <!--T:15-->
Any non-zero value is regarded as true; zero is false.
<syntaxhighlight lang="php">
$boolean = JFactory::getApplication->input->getBool( 'show' );
</syntaxhighlight>
will return false if the value of the 'show' argument in the request is zero, or 1 (true) if the argument is anything else. The default is false. Note that any string argument will result in a return value of true, so calling the above with a URL containing "?show=false" will actually return true!
<syntaxhighlight lang="php">
$boolean = JFactory::getApplication->input->get->getBool( 'hide', true );
</syntaxhighlight>
will retrieve the value of the 'hide' argument from a GET request (but not a POST), with a default value of true.

===Word=== <!--T:16-->
A word is defined as a string of alphabetic characters. The underscore character is permitted as part of a word.
<syntaxhighlight lang="php">
$word = JFactory::getApplication->input->cookie->getWord( 'search-word' );
</syntaxhighlight>
will retrieve the value of the 'search-word' argument from the request. The default is an empty string.
<syntaxhighlight lang="php">
$word = JFactory::getApplication->input->cookie->getWord( 'keyword', '' );
</syntaxhighlight>
will retrieve the value of the 'keyword' variable from a cookie, with the default being an empty string.

===Command=== <!--T:17-->
A command is like a word but a wider range of characters is permitted. Allowed characters are: all alphanumeric characters, dot, dash (hyphen) and underscore.
<syntaxhighlight lang="php">
$command = JFactory::getApplication->input->getCmd( 'option' );
</syntaxhighlight>
will retrieve the value of the "option" argument from the request. The default value is an empty string.
<syntaxhighlight lang="php">
$command = JFactory::getApplication->input->post->getCmd( 'controller', 'view' );
</syntaxhighlight>
will retrieve the value of the "controller" argument from a POST request (but not a GET), with a default value of 'view'.

===String=== <!--T:18-->
The string type allows a much wider range of input characters. It also takes an optional fourth argument specifying some additional mask options. See [[#Filter options]] for information on the available masks.
<syntaxhighlight lang="php">
$string = JFactory::getApplication->input->getString( 'description' );
</syntaxhighlight>
will retrieve the value of the "description" argument from the request. The default value is an empty string. The input will have whitespace removed from the left and right ends and any HTML tags will be removed.
<syntaxhighlight lang="php">
$string = JFactory::getApplication->input->getString( 'text', '' );
</syntaxhighlight>
will retrieve the value of the "text" argument from the request. The default value is an empty string.
<syntaxhighlight lang="php">
$string = JFactory::getApplication->input->getString( 'template', '<html />' );
</syntaxhighlight>
will retrieve the value of the "template" argument from the request. The default value is '<html />'.

===JSON String=== <!--T:19-->
<syntaxhighlight lang="php">
$json = JFactory::getApplication->input->json->get( 'var_name' );
</syntaxhighlight>

===Generic and other data types=== <!--T:20-->
If the above methods do not meet your needs, there is a small number of additional filter types which you can use by calling the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] method directly. The syntax is:
<syntaxhighlight lang="php">
JFactory::getApplication->input->get( <name>, <default>, <type> );
</syntaxhighlight>
where:

<!--T:21-->
{| class="wikitable" border="1"
| <name> || the name of the variable to be retrieved (for example, the name of an argument in a URL).
|-
| <default> || the default value. There is no default value that will be returned if no default is specified in the call the [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]]. If no default is specified and the argument is not present in the request variable then it will return undefined.
|-
| <type> || specifies the data type expected (see below).
|}

<!--T:22-->
The first three arguments are the same as for the more specific methods described earlier. Only the first argument is mandatory.

<!--T:23-->
Allowed values of the <type>, which is case-insensitive, are as follows:

<!--T:24-->
{| class="wikitable" border="1"
| INT, INTEGER || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getInt]].
|-
| UINT || Get an unsigned integer. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getUint]].
|-
| FLOAT, DOUBLE || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getFloat]].
|-
| BOOL, BOOLEAN || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getBool]].
|-
| WORD || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getWord]].
|-
| ALNUM || Allow only alphanumeric characters (a-z, A-Z, 0-9). Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getAlnum]].
|-
| CMD || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getCmd]].
|-
| BASE64 || Allow only those characters that could be present in a base64-encoded string (ie. a-z, A-Z, 0-9, /, + and =). Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getBase64]].
|-
| STRING || Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getString]].
|-
| ARRAY || Source is not filtered but is cast to array type. When using this type you should use JFilterInput directly to filter the values in your data array.
|-
| HTML || A sanitised string. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getHtml]].
|-
| PATH || Valid pathname regex that filters out common attacks. For example, any path beginning with a "/" will return an empty string. Simliarly, any path containing "/./" or "/../" will return an empty string. Dots within filenames are okay though. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getPath]].
|-
| USERNAME || Removes control characters (0x00 - 0x1F), 0x7F, <, >, ", ', % and &. Equivalent to [[Retrieving_request_data_using_JInput#Getting_Values|JInput->getUsername]].
|}

===Filter options=== <!--T:25-->
All input values can be filtered using JFilterInput->clean.

<!--T:26-->
Filter an array of values.
<syntaxhighlight lang="php">
$data = JFactory::getApplication()->input->post->get('data', array(), 'array');
$filter = JFilterInput::getInstance();

<!--T:27-->
foreach ($data as $value)
{
	$array[] = $filter->clean($value, 'string');
}
</syntaxhighlight>
For more filter types see [https://github.com/joomla/joomla-cms/blob/master/libraries/joomla/filter/input.php#L115 JFilterInput source].

<!--T:28-->
Options listed bellow available only in deprecated [[JRequest]] library.
Allowed values of <options> are as follows (none of these are applied by default):

<!--T:29-->
{| class="wikitable" border="1"
| JREQUEST_NOTRIM || Does not remove whitespace from the start and ends of strings.
|-
| JREQUEST_ALLOWRAW || Does not do any filtering at all. Use with extreme caution.
|-
| JREQUEST_ALLOWHTML || Does not remove HTML from string inputs.
|}

<!--T:30-->
Masks can be combined by logically OR'ing them. If no filter options are specified, then by default, whitespace is trimmed and HTML is removed.

===File uploads=== <!--T:31-->
Web servers already have a good deal of security around handling file uploads, but it is still necessary to take additional steps to ensure that file names and paths cannot be abused. A simplified form which requests a file to be uploaded looks like this:
<syntaxhighlight lang="html4strict">
<form action="index.php?option=com_mycomponent/form_handler.php" method="post" enctype="multipart/form-data">
        <input type="file" name="Filedata" />
    <input type="submit" />
</form>
</syntaxhighlight>
On clicking the submit button, the browser will upload the file in a POST request, passing control to Joomla which will call "components/com_mycomponent/form_handler.php". This will include code like the following. The variable $somepath must be set to some path where the web server has permission to create files.
<syntaxhighlight lang="php">
// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die( 'Restricted access' );

<!--T:32-->
// Get the file data array from the request.
$file = JFactory::getApplication->input->get( 'Filedata', '', 'files', 'array' );

<!--T:33-->
// Make the file name safe.
jimport('joomla.filesystem.file');
$file['name'] = JFile::makeSafe($file['name']);

<!--T:34-->
// Move the uploaded file into a permanent location.
if (isset( $file['name'] )) {

    <!--T:35-->
// Make sure that the full file path is safe.
    $filepath = JPath::clean( $somepath.'/'.strtolower( $file['name'] ) );

    <!--T:36-->
// Move the uploaded file.
    JFile::upload( $file['tmp_name'], $filepath );
}
</syntaxhighlight>

===Saving a request variable into user state=== <!--T:37-->
Because setting a user state variable from a variable in the request is such a common operation, there is an API method to make the task easier. This is generally safe to use because it calls [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] to obtain the input from the request, but remember that none of the input filtering calls will protect against SQL injection attempts.
<syntaxhighlight lang="php">
$app = JFactory::getApplication();
$app->getUserStateFromRequest( <key>, <name>, <default>, <type> );
</syntaxhighlight>
where
{| class="wikitable" border="1"
| <key> || the name of the variable in the user state.
|-
| <name> || the name of the request variable (same as the first argument of a [[Retrieving_request_data_using_JInput#Getting_Values|JInput->get]] call).
|-
| <default> || the default value to be assigned to the user state variable if the request variable is absent. The default is null.
|-
| <type> || the type of variable expected.
|}

<!--T:38-->
For example, getting an integer variable called ''id'' from the request with a default value of 0, then saving it into a session variable called ''myid'' can be done like this:
<syntaxhighlight lang="php">
$app = JFactory::getApplication();
$app->getUserStateFromRequest( 'myid', 'id, 0, 'int' );
</syntaxhighlight>
instead of something like this:
<syntaxhighlight lang="php">
$app = JFactory::getApplication();
$app->setUserState( 'myid', $app->input->getInt( 'id', 0 ) );
</syntaxhighlight>