Retrieving Request Data Using Input

The Joomla Input class allows you to retrieve the parameters which were sent in the HTTP request. It doesn't matter whether the parameters are GET parameters or POST parameters, both can be accessible with the help of the Input Class.

You can specify a filter to be applied to the parameter value, so that what you receive is sanitised and in the form which you expect.

For example, if you expect a parameter p1 to be an integer, then you can apply an "INTEGER" filter when you get its value. Then, if someone specifies ?p1=82abc5 in the URL string, you will get back the value 82.

First create an object of the Input class by using this code:

use Joomla\CMS\Factory;
$input = Factory::getApplication()->input;

Then, to get the value of a specific parameter use

$val = $input->get(param_name, default_value, filter);

where,

param_name is a string containing the name of the parameter.
default_value is the value you want returned if the parameter is not found. It may be a string, integer, array, null, or any other.
filter is a string specifying one of the filters. If you don't specify this parameter, then a default of "cmd" is used.

For example, the code below shows how to get the value of a parameter p1. The value of the parameter is passed through a "string" filter which will remove html tags and the like. If the parameter doesn't exist then the string "xyz" is returned.

use Joomla\CMS\Factory;
$app = Factory::getApplication();
$input = $app->input;
$p1 = $input->get('p1', 'xyz', 'string');

The Input class returns an array of filtered entries if the user input is an array. Calling the above example with ?p1[]=xyz will return $p1 as array with one element 'xyz' filter as string.

The method exists() can also be used to check if a parameter exists, but in practice this isn't often used, as using the default_value parameter usually covers adequately the case when a parameter is absent.

Available Filters

Filters can be specified in either lower or upper case.

"INT", "INTEGER"

It returns the first integer found in the parameter value.

// Only use the first integer value
preg_match('/-?[0-9]+/', (string) $source, $matches);

"UINT"

It returns an unsigned int. For example, if the parameter is specified ?p1=-2 then this filter will discard the minus sign and you will get the value 2 returned as the value of p1.

// Only use the first integer value
preg_match('/-?[0-9]+/', (string) $source, $matches);

"FLOAT", "DOUBLE"

It returns the first float found.

// Only use the first floating point value
preg_match('/-?[0-9]+(\.[0-9]+)?/', (string) $source, $matches);

"BOOL", "BOOLEAN"

Be careful with this filter. If you specify in the URL ?p1=false then the value of p1 is actually the string "false" and as this is a non-empty string (bool) p1 will return true.

"WORD"

// Only allow characters a-z, and underscores
$result = (string) preg_replace('/[^A-Z_]/i', '', $source);

"ALNUM"

alphanumeric

// Allow a-z and 0-9 only
$result = (string) preg_replace('/[^A-Z0-9]/i', '', $source);

"CMD"

It is used often when obtaining the ?option=controller.task parameter in Joomla components. This is the default filter.

// Allow a-z, 0-9, underscore, dot, dash. Also remove leading dots from result.
$result = (string) preg_replace('/[^A-Z0-9_\.-]/i', '', $source);
$result = ltrim($result, '.');

"BASE64"

The base64 can be used to encode a URL as a string of text, which is then stored in a request parameter. For example, if a user accesses a URL which is protected then he or she may be redirected to the URL of the login page, with the original URL being base64 encoded and stored as a (return) parameter within the redirected URL.

Once the user has logged in correctly the return parameter is retrieved and he or she is redirected back to the original URL accessed. You still have to decode the base64 yourself, the filter doesn't do this.

// Allow a-z, 0-9, slash, plus, equals.
$result = (string) preg_replace('/[^A-Z0-9\/+=]/i', '', $source);

"STRING"

// Converts the input to a plain text string; strips all tags / attributes.
$result = (string) $this->_remove($this->_decode((string) $source));

"HTML"

// Converts the input to a string; strips all HTML tags / attributes.
$result = (string) $this->_remove($this->_decode((string) $source));

"ARRAY"

// Attempts to convert the input to an array.
$result = (array) $source;

"PATH"

It converts the input into a string and validates it as a path. For example, path/to/file.png or path/to/dir

It does not accept absolute paths, or paths ending in a trailing slash.

"RAW"

Be careful using this, to avoid injection attacks on your website.

// The raw input. No sanitisation provided.
$result = $source;

"USERNAME"

// Strips all invalid username characters.
$result = (string) preg_replace('/[\x00-\x1F\x7F<>"\'%&]/', '', $source)

Getting Multiple Values

To retrieve a number of values, you can use the getArray() method. For example,

$fooValues = $input->getArray(array('p1' => '', 'p2' => '', 'p3' => ''));

If you want to determine the data to get step by step:

$fooArray = array();
$fooArray['p1'] = '';
$fooArray['p2'] = '';
$fooArray['p3'] = '';
$fooValues = $input->getArray($fooArray);

The $fooValues will be an array that consists of the same keys as used in $fooArray, but with values attached.

You can also specify different filters for each of the inputs:

$fooValues = $input->getArray(array(
 'p1' => 'int',
 'p2' => 'float',
 'p3' => 'word'
));

Getting Super Global Values

You can retrieve values relating specifically to the PHP $_GET, $_POST and $_SERVER global variables:

$val = $input->get->get(param_name, default_value, filter);
$val = $input->post->get(param_name, default_value, filter);
$val = $input->server->get(param_name, default_value, filter);

Getting JSON String from Request

This is available since Joomla version 3.0.

$json = $input->json->get(param_name);

Setting Values

The functions set() and def() allow you to set input parameters and their values.

$input->set('p2', "someval");

It sets the value of parameter p2 to the string "someval" (creating p2 if it doesn't already exist).

$input->def('p2', "someval");

It creates a parameter p2 and sets its value to the string "someval", but only if p2 doesn't already exist. If p2 already exists then def('p2', "someval"); does nothing.