475 lines
15 KiB
ReStructuredText
475 lines
15 KiB
ReStructuredText
###########
|
|
Input Class
|
|
###########
|
|
|
|
The Input Class serves two purposes:
|
|
|
|
#. It pre-processes global input data for security.
|
|
#. It provides some helper methods for fetching input data and pre-processing it.
|
|
|
|
.. note:: This class is initialized automatically by the system so there
|
|
is no need to do it manually.
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
.. raw:: html
|
|
|
|
<div class="custom-index container"></div>
|
|
|
|
***************
|
|
Input Filtering
|
|
***************
|
|
|
|
Security Filtering
|
|
==================
|
|
|
|
The security filtering method is called automatically when a new
|
|
:doc:`controller <../general/controllers>` is invoked. It does the
|
|
following:
|
|
|
|
- If ``$config['allow_get_array']`` is FALSE (default is TRUE), destroys
|
|
the global GET array.
|
|
- Destroys all global variables in the event register_globals is
|
|
turned on.
|
|
- Filters the GET/POST/COOKIE array keys, permitting only alpha-numeric
|
|
(and a few other) characters.
|
|
- Provides XSS (Cross-site Scripting Hacks) filtering. This can be
|
|
enabled globally, or upon request.
|
|
- Standardizes newline characters to ``PHP_EOL`` (\\n in UNIX-based OSes,
|
|
\\r\\n under Windows). This is configurable.
|
|
|
|
XSS Filtering
|
|
=============
|
|
|
|
The Input class has the ability to filter input automatically to prevent
|
|
cross-site scripting attacks. If you want the filter to run
|
|
automatically every time it encounters POST or COOKIE data you can
|
|
enable it by opening your *application/config/config.php* file and setting
|
|
this::
|
|
|
|
$config['global_xss_filtering'] = TRUE;
|
|
|
|
Please refer to the :doc:`Security class <security>` documentation for
|
|
information on using XSS Filtering in your application.
|
|
|
|
.. important:: The 'global_xss_filtering' setting is DEPRECATED and kept
|
|
solely for backwards-compatibility purposes. XSS escaping should
|
|
be performed on *output*, not *input*!
|
|
|
|
*******************
|
|
Accessing form data
|
|
*******************
|
|
|
|
Using POST, GET, COOKIE, or SERVER Data
|
|
=======================================
|
|
|
|
CodeIgniter comes with helper methods that let you fetch POST, GET,
|
|
COOKIE or SERVER items. The main advantage of using the provided
|
|
methods rather than fetching an item directly (``$_POST['something']``)
|
|
is that the methods will check to see if the item is set and return
|
|
NULL if not. This lets you conveniently use data without
|
|
having to test whether an item exists first. In other words, normally
|
|
you might do something like this::
|
|
|
|
$something = isset($_POST['something']) ? $_POST['something'] : NULL;
|
|
|
|
With CodeIgniter's built in methods you can simply do this::
|
|
|
|
$something = $this->input->post('something');
|
|
|
|
The main methods are:
|
|
|
|
- ``$this->input->post()``
|
|
- ``$this->input->get()``
|
|
- ``$this->input->cookie()``
|
|
- ``$this->input->server()``
|
|
|
|
Using the php://input stream
|
|
============================
|
|
|
|
If you want to utilize the PUT, DELETE, PATCH or other exotic request
|
|
methods, they can only be accessed via a special input stream, that
|
|
can only be read once. This isn't as easy as just reading from e.g.
|
|
the ``$_POST`` array, because it will always exist and you can try
|
|
and access multiple variables without caring that you might only have
|
|
one shot at all of the POST data.
|
|
|
|
CodeIgniter will take care of that for you, and you can read the data
|
|
from the **php://input** stream at any time, just by using the
|
|
``$raw_input_stream`` property::
|
|
|
|
$this->input->raw_input_stream;
|
|
|
|
Additionally if the input stream is form-encoded like $_POST you can
|
|
access its values by calling the
|
|
``input_stream()`` method::
|
|
|
|
$this->input->input_stream('key');
|
|
|
|
Similar to other methods such as ``get()`` and ``post()``, if the
|
|
requested data is not found, it will return NULL and you can also
|
|
decide whether to run the data through ``xss_clean()`` by passing
|
|
a boolean value as the second parameter::
|
|
|
|
$this->input->input_stream('key', TRUE); // XSS Clean
|
|
$this->input->input_stream('key', FALSE); // No XSS filter
|
|
|
|
.. note:: You can utilize ``method()`` in order to know if you're reading
|
|
PUT, DELETE or PATCH data.
|
|
|
|
***************
|
|
Class Reference
|
|
***************
|
|
|
|
.. php:class:: CI_Input
|
|
|
|
.. attribute:: $raw_input_stream
|
|
|
|
Read only property that will return php://input data as is.
|
|
|
|
The property can be read multiple times.
|
|
|
|
.. php:method:: post([$index = NULL[, $xss_clean = NULL]])
|
|
|
|
:param mixed $index: POST parameter name
|
|
:param bool $xss_clean: Whether to apply XSS filtering
|
|
:returns: $_POST if no parameters supplied, otherwise the POST value if found or NULL if not
|
|
:rtype: mixed
|
|
|
|
The first parameter will contain the name of the POST item you are
|
|
looking for::
|
|
|
|
$this->input->post('some_data');
|
|
|
|
The method returns NULL if the item you are attempting to retrieve
|
|
does not exist.
|
|
|
|
The second optional parameter lets you run the data through the XSS
|
|
filter. It's enabled by setting the second parameter to boolean TRUE
|
|
or by setting your ``$config['global_xss_filtering']`` to TRUE.
|
|
::
|
|
|
|
$this->input->post('some_data', TRUE);
|
|
|
|
To return an array of all POST items call without any parameters.
|
|
|
|
To return all POST items and pass them through the XSS filter set the
|
|
first parameter NULL while setting the second parameter to boolean TRUE.
|
|
::
|
|
|
|
$this->input->post(NULL, TRUE); // returns all POST items with XSS filter
|
|
$this->input->post(NULL, FALSE); // returns all POST items without XSS filter
|
|
|
|
To return an array of multiple POST parameters, pass all the required keys
|
|
as an array.
|
|
::
|
|
|
|
$this->input->post(array('field1', 'field2'));
|
|
|
|
Same rule applied here, to retrieve the parameters with XSS filtering enabled, set the
|
|
second parameter to boolean TRUE.
|
|
::
|
|
|
|
$this->input->post(array('field1', 'field2'), TRUE);
|
|
|
|
.. php:method:: get([$index = NULL[, $xss_clean = NULL]])
|
|
|
|
:param mixed $index: GET parameter name
|
|
:param bool $xss_clean: Whether to apply XSS filtering
|
|
:returns: $_GET if no parameters supplied, otherwise the GET value if found or NULL if not
|
|
:rtype: mixed
|
|
|
|
This method is identical to ``post()``, only it fetches GET data.
|
|
::
|
|
|
|
$this->input->get('some_data', TRUE);
|
|
|
|
To return an array of all GET items call without any parameters.
|
|
|
|
To return all GET items and pass them through the XSS filter set the
|
|
first parameter NULL while setting the second parameter to boolean TRUE.
|
|
::
|
|
|
|
$this->input->get(NULL, TRUE); // returns all GET items with XSS filter
|
|
$this->input->get(NULL, FALSE); // returns all GET items without XSS filtering
|
|
|
|
To return an array of multiple GET parameters, pass all the required keys
|
|
as an array.
|
|
::
|
|
|
|
$this->input->get(array('field1', 'field2'));
|
|
|
|
Same rule applied here, to retrieve the parameters with XSS filtering enabled, set the
|
|
second parameter to boolean TRUE.
|
|
::
|
|
|
|
$this->input->get(array('field1', 'field2'), TRUE);
|
|
|
|
.. php:method:: post_get($index[, $xss_clean = NULL])
|
|
|
|
:param string $index: POST/GET parameter name
|
|
:param bool $xss_clean: Whether to apply XSS filtering
|
|
:returns: POST/GET value if found, NULL if not
|
|
:rtype: mixed
|
|
|
|
This method works pretty much the same way as ``post()`` and ``get()``,
|
|
only combined. It will search through both POST and GET streams for data,
|
|
looking in POST first, and then in GET::
|
|
|
|
$this->input->post_get('some_data', TRUE);
|
|
|
|
.. php:method:: get_post($index[, $xss_clean = NULL])
|
|
|
|
:param string $index: GET/POST parameter name
|
|
:param bool $xss_clean: Whether to apply XSS filtering
|
|
:returns: GET/POST value if found, NULL if not
|
|
:rtype: mixed
|
|
|
|
This method works the same way as ``post_get()`` only it looks for GET
|
|
data first.
|
|
|
|
$this->input->get_post('some_data', TRUE);
|
|
|
|
.. note:: This method used to act EXACTLY like ``post_get()``, but it's
|
|
behavior has changed in CodeIgniter 3.0.
|
|
|
|
.. php:method:: cookie([$index = NULL[, $xss_clean = NULL]])
|
|
|
|
:param mixed $index: COOKIE name
|
|
:param bool $xss_clean: Whether to apply XSS filtering
|
|
:returns: $_COOKIE if no parameters supplied, otherwise the COOKIE value if found or NULL if not
|
|
:rtype: mixed
|
|
|
|
This method is identical to ``post()`` and ``get()``, only it fetches cookie
|
|
data::
|
|
|
|
$this->input->cookie('some_cookie');
|
|
$this->input->cookie('some_cookie', TRUE); // with XSS filter
|
|
|
|
To return an array of multiple cookie values, pass all the required keys
|
|
as an array.
|
|
::
|
|
|
|
$this->input->cookie(array('some_cookie', 'some_cookie2'));
|
|
|
|
.. note:: Unlike the :doc:`Cookie Helper <../helpers/cookie_helper>`
|
|
function :php:func:`get_cookie()`, this method does NOT prepend
|
|
your configured ``$config['cookie_prefix']`` value.
|
|
|
|
.. php:method:: server($index[, $xss_clean = NULL])
|
|
|
|
:param mixed $index: Value name
|
|
:param bool $xss_clean: Whether to apply XSS filtering
|
|
:returns: $_SERVER item value if found, NULL if not
|
|
:rtype: mixed
|
|
|
|
This method is identical to the ``post()``, ``get()`` and ``cookie()``
|
|
methods, only it fetches server data (``$_SERVER``)::
|
|
|
|
$this->input->server('some_data');
|
|
|
|
To return an array of multiple ``$_SERVER`` values, pass all the required keys
|
|
as an array.
|
|
::
|
|
|
|
$this->input->server(array('SERVER_PROTOCOL', 'REQUEST_URI'));
|
|
|
|
.. php:method:: input_stream([$index = NULL[, $xss_clean = NULL]])
|
|
|
|
:param mixed $index: Key name
|
|
:param bool $xss_clean: Whether to apply XSS filtering
|
|
:returns: Input stream array if no parameters supplied, otherwise the specified value if found or NULL if not
|
|
:rtype: mixed
|
|
|
|
This method is identical to ``get()``, ``post()`` and ``cookie()``,
|
|
only it fetches the *php://input* stream data.
|
|
|
|
.. php:method:: set_cookie($name = ''[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = NULL[, $httponly = NULL]]]]]]])
|
|
|
|
:param mixed $name: Cookie name or an array of parameters
|
|
:param string $value: Cookie value
|
|
:param int $expire: Cookie expiration time in seconds
|
|
:param string $domain: Cookie domain
|
|
:param string $path: Cookie path
|
|
:param string $prefix: Cookie name prefix
|
|
:param bool $secure: Whether to only transfer the cookie through HTTPS
|
|
:param bool $httponly: Whether to only make the cookie accessible for HTTP requests (no JavaScript)
|
|
:rtype: void
|
|
|
|
|
|
Sets a cookie containing the values you specify. There are two ways to
|
|
pass information to this method so that a cookie can be set: Array
|
|
Method, and Discrete Parameters:
|
|
|
|
**Array Method**
|
|
|
|
Using this method, an associative array is passed to the first
|
|
parameter::
|
|
|
|
$cookie = array(
|
|
'name' => 'The Cookie Name',
|
|
'value' => 'The Value',
|
|
'expire' => '86500',
|
|
'domain' => '.some-domain.com',
|
|
'path' => '/',
|
|
'prefix' => 'myprefix_',
|
|
'secure' => TRUE
|
|
);
|
|
|
|
$this->input->set_cookie($cookie);
|
|
|
|
**Notes**
|
|
|
|
Only the name and value are required. To delete a cookie set it with the
|
|
expiration blank.
|
|
|
|
The expiration is set in **seconds**, which will be added to the current
|
|
time. Do not include the time, but rather only the number of seconds
|
|
from *now* that you wish the cookie to be valid. If the expiration is
|
|
set to zero the cookie will only last as long as the browser is open.
|
|
|
|
For site-wide cookies regardless of how your site is requested, add your
|
|
URL to the **domain** starting with a period, like this:
|
|
.your-domain.com
|
|
|
|
The path is usually not needed since the method sets a root path.
|
|
|
|
The prefix is only needed if you need to avoid name collisions with
|
|
other identically named cookies for your server.
|
|
|
|
The *httponly* and *secure* flags, when omitted, will default to your
|
|
``$config['cookie_httponly']`` and ``$config['cookie_secure']`` settings.
|
|
|
|
**Discrete Parameters**
|
|
|
|
If you prefer, you can set the cookie by passing data using individual
|
|
parameters::
|
|
|
|
$this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure);
|
|
|
|
.. php:method:: ip_address()
|
|
|
|
:returns: Visitor's IP address or '0.0.0.0' if not valid
|
|
:rtype: string
|
|
|
|
Returns the IP address for the current user. If the IP address is not
|
|
valid, the method will return '0.0.0.0'::
|
|
|
|
echo $this->input->ip_address();
|
|
|
|
.. important:: This method takes into account the ``$config['proxy_ips']``
|
|
setting and will return the reported HTTP_X_FORWARDED_FOR,
|
|
HTTP_CLIENT_IP, HTTP_X_CLIENT_IP or HTTP_X_CLUSTER_CLIENT_IP
|
|
address for the allowed IP addresses.
|
|
|
|
.. php:method:: valid_ip($ip[, $which = ''])
|
|
|
|
:param string $ip: IP address
|
|
:param string $which: IP protocol ('ipv4' or 'ipv6')
|
|
:returns: TRUE if the address is valid, FALSE if not
|
|
:rtype: bool
|
|
|
|
Takes an IP address as input and returns TRUE or FALSE (boolean) depending
|
|
on whether it is valid or not.
|
|
|
|
.. note:: The $this->input->ip_address() method above automatically
|
|
validates the IP address.
|
|
|
|
::
|
|
|
|
if ( ! $this->input->valid_ip($ip))
|
|
{
|
|
echo 'Not Valid';
|
|
}
|
|
else
|
|
{
|
|
echo 'Valid';
|
|
}
|
|
|
|
Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify
|
|
an IP format. The default checks for both formats.
|
|
|
|
.. php:method:: user_agent([$xss_clean = NULL])
|
|
|
|
:returns: User agent string or NULL if not set
|
|
:param bool $xss_clean: Whether to apply XSS filtering
|
|
:rtype: mixed
|
|
|
|
Returns the user agent string (web browser) being used by the current user,
|
|
or NULL if it's not available.
|
|
::
|
|
|
|
echo $this->input->user_agent();
|
|
|
|
See the :doc:`User Agent Class <user_agent>` for methods which extract
|
|
information from the user agent string.
|
|
|
|
.. php:method:: request_headers([$xss_clean = FALSE])
|
|
|
|
:param bool $xss_clean: Whether to apply XSS filtering
|
|
:returns: An array of HTTP request headers
|
|
:rtype: array
|
|
|
|
Returns an array of HTTP request headers.
|
|
Useful if running in a non-Apache environment where
|
|
`apache_request_headers() <http://php.net/apache_request_headers>`_
|
|
will not be supported.
|
|
::
|
|
|
|
$headers = $this->input->request_headers();
|
|
|
|
.. php:method:: get_request_header($index[, $xss_clean = FALSE])
|
|
|
|
:param string $index: HTTP request header name
|
|
:param bool $xss_clean: Whether to apply XSS filtering
|
|
:returns: An HTTP request header or NULL if not found
|
|
:rtype: string
|
|
|
|
Returns a single member of the request headers array or NULL
|
|
if the searched header is not found.
|
|
::
|
|
|
|
$this->input->get_request_header('some-header', TRUE);
|
|
|
|
.. php:method:: is_ajax_request()
|
|
|
|
:returns: TRUE if it is an Ajax request, FALSE if not
|
|
:rtype: bool
|
|
|
|
Checks to see if the HTTP_X_REQUESTED_WITH server header has been
|
|
set, and returns boolean TRUE if it is or FALSE if not.
|
|
|
|
.. php:method:: is_cli_request()
|
|
|
|
:returns: TRUE if it is a CLI request, FALSE if not
|
|
:rtype: bool
|
|
|
|
Checks to see if the application was run from the command-line
|
|
interface.
|
|
|
|
.. note:: This method checks both the PHP SAPI name currently in use
|
|
and if the ``STDIN`` constant is defined, which is usually a
|
|
failsafe way to see if PHP is being run via the command line.
|
|
|
|
::
|
|
|
|
$this->input->is_cli_request()
|
|
|
|
.. note:: This method is DEPRECATED and is now just an alias for the
|
|
:func:`is_cli()` function.
|
|
|
|
.. php:method:: method([$upper = FALSE])
|
|
|
|
:param bool $upper: Whether to return the request method name in upper or lower case
|
|
:returns: HTTP request method
|
|
:rtype: string
|
|
|
|
Returns the ``$_SERVER['REQUEST_METHOD']``, with the option to set it
|
|
in uppercase or lowercase.
|
|
::
|
|
|
|
echo $this->input->method(TRUE); // Outputs: POST
|
|
echo $this->input->method(FALSE); // Outputs: post
|
|
echo $this->input->method(); // Outputs: post
|