summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/input.rst
diff options
context:
space:
mode:
authorBrennan Thompson <brenjt@gmail.com>2014-02-14 20:03:57 +0100
committerBrennan Thompson <brenjt@gmail.com>2014-02-14 20:03:57 +0100
commit6949f95f6e21980f36095490bf38fc8a172dbc0f (patch)
treeb3141f390acd0051396cda6a3da51c1f98384cca /user_guide_src/source/libraries/input.rst
parent68a02a01a086bbb1b8128ea2744439de84873d11 (diff)
parent81f036753272391360ba5b64e6dd93c4101a8733 (diff)
Merge remote-tracking branch 'upstream/develop' into develop
Conflicts: system/helpers/form_helper.php
Diffstat (limited to 'user_guide_src/source/libraries/input.rst')
-rw-r--r--user_guide_src/source/libraries/input.rst440
1 files changed, 261 insertions, 179 deletions
diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst
index fb245d7cd..6162a6664 100644
--- a/user_guide_src/source/libraries/input.rst
+++ b/user_guide_src/source/libraries/input.rst
@@ -10,6 +10,13 @@ The Input Class serves two purposes:
.. 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>
+
Security Filtering
==================
@@ -17,7 +24,7 @@ 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
+- 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.
@@ -25,7 +32,8 @@ following:
(and a few other) characters.
- Provides XSS (Cross-site Scripting Hacks) filtering. This can be
enabled globally, or upon request.
-- Standardizes newline characters to \\n(In Windows \\r\\n)
+- Standardizes newline characters to ``PHP_EOL`` (\\n in UNIX-based OSes,
+ \\r\\n under Windows). This is configurable.
XSS Filtering
=============
@@ -33,7 +41,7 @@ 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
+enable it by opening your *application/config/config.php* file and setting
this::
$config['global_xss_filtering'] = TRUE;
@@ -44,7 +52,7 @@ information on using XSS Filtering in your application.
Using POST, GET, COOKIE, or SERVER Data
=======================================
-CodeIgniter comes with four helper methods that let you fetch POST, GET,
+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
@@ -58,270 +66,344 @@ With CodeIgniter's built in methods you can simply do this::
$something = $this->input->post('something');
-The four methods are:
+The main methods are:
-- $this->input->post()
-- $this->input->get()
-- $this->input->cookie()
-- $this->input->server()
+- ``$this->input->post()``
+- ``$this->input->get()``
+- ``$this->input->cookie()``
+- ``$this->input->server()``
-$this->input->post()
-====================
+Using the php://input stream
+============================
-The first parameter will contain the name of the POST item you are
-looking for::
+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.
- $this->input->post('some_data');
+CodeIgniter will take care of that for you, and you can access data
+from the **php://input** stream at any time, just by calling the
+``input_stream()`` method::
-The method returns NULL if the item you are attempting to retrieve
-does not exist.
+ $this->input->input_stream('key');
-The second optional parameter lets you run the data through the XSS
-filter. It's enabled by setting the second parameter to boolean TRUE;
+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
- $this->input->post('some_data', TRUE);
+.. note:: You can utilize ``method()`` in order to know if you're reading
+ PUT, DELETE or PATCH data.
-To return an array of all POST items call without any parameters.
+***************
+Class Reference
+***************
-To return all POST items and pass them through the XSS filter set the
-first parameter NULL while setting the second parameter to boolean;
+.. class:: CI_Input
-The method returns NULL if there are no items in the POST.
+ .. method:: post([$index = NULL[, $xss_clean = NULL]])
-::
+ :param string $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
- $this->input->post(NULL, TRUE); // returns all POST items with XSS filter
- $this->input->post(); // returns all POST items without XSS filter
+ The first parameter will contain the name of the POST item you are
+ looking for::
-$this->input->get()
-===================
+ $this->input->post('some_data');
-This method is identical to the POST method, only it fetches GET data
-::
+ The method returns NULL if the item you are attempting to retrieve
+ does not exist.
- $this->input->get('some_data', TRUE);
+ 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.
+ ::
-To return an array of all GET items call without any parameters.
+ $this->input->post('some_data', TRUE);
-To return all GET items and pass them through the XSS filter set the
-first parameter NULL while setting the second parameter to boolean;
+ To return an array of all POST items call without any parameters.
-The method returns NULL if there are no items in the GET.
+ 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
- $this->input->get(NULL, TRUE); // returns all GET items with XSS filter
- $this->input->get(); // returns all GET items without XSS filtering
+ .. method:: get([$index = NULL[, $xss_clean = NULL]])
+ :param string $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->input->post_get()
-========================
+ This method is identical to ``post()``, only it fetches GET data.
+ ::
-This method will search through both the POST and GET streams for
-data, looking first in POST, and then in GET::
+ $this->input->get('some_data', TRUE);
- $this->input->post_get('some_data', TRUE);
+ To return an array of all GET items call without any parameters.
-$this->input->get_post()
-========================
+ 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 method will search through both the POST and GET streams for
-data, looking first in GET, and then in POST::
+ $this->input->get(NULL, TRUE); // returns all GET items with XSS filter
+ $this->input->get(NULL, FALSE); // returns all GET items without XSS filtering
- $this->input->get_post('some_data', TRUE);
+ .. method:: post_get($index[, $xss_clean = NULL])
-$this->input->cookie()
-======================
+ :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 is identical to the POST method, only it fetches cookie data
-::
+ 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->cookie('some_cookie');
- $this->input->cookie('some_cookie, TRUE); // with XSS filter
+ $this->input->post_get('some_data', TRUE);
+ .. method:: get_post($index[, $xss_clean = NULL])
-$this->input->server()
-======================
+ :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 is identical to the above methods, only it fetches server
-server data::
+ This method works the same way as ``post_get()`` only it looks for GET
+ data first.
- $this->input->server('some_data');
+ $this->input->get_post('some_data', TRUE);
-Using the php://input stream
-============================
+ .. note:: This method used to act EXACTLY like ``post_get()``, but it's
+ behavior has changed in CodeIgniter 3.0.
-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.
+ .. method:: cookie([$index = NULL[, $xss_clean = NULL]])
-CodeIgniter will take care of that for you, and you can access data
-from the **php://input** stream at any time, just by calling the
-``input_stream()`` method::
+ :param string $index: COOKIE parameter 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->input->input_stream('key');
+ This method is identical to ``post()`` and ``get()``, only it fetches cookie
+ data::
-Similar to the methods above, 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->cookie('some_cookie');
+ $this->input->cookie('some_cookie, TRUE); // with XSS filter
- $this->input->input_stream('key', TRUE); // XSS Clean
- $this->input->input_stream('key', FALSE); // No XSS filter
+ .. method:: server($index[, $xss_clean = NULL])
-.. note:: You can utilize method() in order to know if you're reading
- PUT, DELETE or PATCH data.
+ :param string $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');
+
+ .. method:: input_stream([$index = NULL[, $xss_clean = NULL]])
+
+ :param string $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.
+
+ .. method:: set_cookie($name = ''[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = FALSE[, $httponly = FALSE]]]]]]])
+
+ :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()
-==========================
+ $this->input->set_cookie($cookie);
-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:
+ **Notes**
-Array Method
-^^^^^^^^^^^^
+ Only the name and value are required. To delete a cookie set it with the
+ expiration blank.
-Using this method, an associative array is passed to the first
-parameter::
+ 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.
- $cookie = array(
- 'name' => 'The Cookie Name',
- 'value' => 'The Value',
- 'expire' => '86500',
- 'domain' => '.some-domain.com',
- 'path' => '/',
- 'prefix' => 'myprefix_',
- 'secure' => TRUE
- );
+ 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
- $this->input->set_cookie($cookie);
+ The path is usually not needed since the method sets a root path.
-**Notes:**
+ The prefix is only needed if you need to avoid name collisions with
+ other identically named cookies for your server.
-Only the name and value are required. To delete a cookie set it with the
-expiration blank.
+ The secure boolean is only needed if you want to make it a secure cookie
+ by setting it to TRUE.
-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.
+ **Discrete Parameters**
-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
+ If you prefer, you can set the cookie by passing data using individual
+ parameters::
-The path is usually not needed since the method sets a root path.
+ $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure);
-The prefix is only needed if you need to avoid name collisions with
-other identically named cookies for your server.
+ .. method:: ip_address()
-The secure boolean is only needed if you want to make it a secure cookie
-by setting it to TRUE.
+ :returns: Visitor's IP address or '0.0.0.0' if not valid
+ :rtype: string
-Discrete Parameters
-^^^^^^^^^^^^^^^^^^^
+ Returns the IP address for the current user. If the IP address is not
+ valid, the method will return '0.0.0.0'::
-If you prefer, you can set the cookie by passing data using individual
-parameters::
+ echo $this->input->ip_address();
- $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure);
+ .. 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.
+ .. method:: valid_ip($ip[, $which = ''])
-$this->input->ip_address()
-==========================
+ :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
-Returns the IP address for the current user. If the IP address is not
-valid, the method will return an IP of: 0.0.0.0
+ 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.
- echo $this->input->ip_address();
+ ::
-$this->input->valid_ip($ip)
-===========================
+ if ( ! $this->input->valid_ip($ip))
+ {
+ echo 'Not Valid';
+ }
+ else
+ {
+ echo 'Valid';
+ }
-Takes an IP address as input and returns TRUE or FALSE (boolean) if it
-is valid or not.
+ Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify
+ an IP format. The default checks for both formats.
-.. note:: The $this->input->ip_address() method above automatically
- validates the IP address.
+ .. method:: user_agent()
-::
+ :returns: User agent string or NULL if not set
+ :rtype: mixed
- if ( ! $this->input->valid_ip($ip))
- {
- echo 'Not Valid';
- }
- else
- {
- echo 'Valid';
- }
+ Returns the user agent string (web browser) being used by the current user,
+ or NULL if it's not available.
+ ::
-Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify
-an IP format. The default checks for both formats.
+ echo $this->input->user_agent();
-$this->input->user_agent()
-==========================
+ See the :doc:`User Agent Class <user_agent>` for methods which extract
+ information from the user agent string.
-Returns the user agent (web browser) being used by the current user.
-Returns FALSE if it's not available.
+ .. method:: request_headers([$xss_clean = FALSE])
-::
+ :param bool $xss_clean: Whether to apply XSS filtering
+ :returns: An array of HTTP request headers
+ :rtype: array
- echo $this->input->user_agent();
+ 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.
+ ::
-See the :doc:`User Agent Class <user_agent>` for methods which extract
-information from the user agent string.
+ $headers = $this->input->request_headers();
-$this->input->request_headers()
-===============================
+ .. method:: get_request_header($index[, $xss_clean = FALSE])
-Useful if running in a non-Apache environment where
-`apache_request_headers() <http://php.net/apache_request_headers>`_
-will not be supported. Returns an array of headers.
+ :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.
+ ::
- $headers = $this->input->request_headers();
+ $this->input->get_request_header('some-header', TRUE);
-$this->input->get_request_header()
-==================================
+ .. method:: is_ajax_request()
-Returns a single member of the request headers array.
+ :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.
- $this->input->get_request_header('some-header', TRUE);
+ .. method:: is_cli_request()
-$this->input->is_ajax_request()
-===============================
+ :returns: TRUE if it is a CLI request, FALSE if not
+ :rtype: bool
-Checks to see if the HTTP_X_REQUESTED_WITH server header has been
-set, and returns a boolean response.
+ Checks to see if the application was run from the command-line
+ interface.
-$this->input->is_cli_request()
-==============================
+ .. 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.
-Checks to see if the STDIN constant is set, which is a failsafe way to
-see if PHP is being run on the command line.
+ ::
-::
+ $this->input->is_cli_request()
- $this->input->is_cli_request()
+ .. note:: This method is DEPRECATED and is now just an alias for the
+ :func:`is_cli()` function.
-$this->input->method()
-======================
+ .. method:: method([$upper = FALSE])
-Returns the $_SERVER['REQUEST_METHOD'], optional set uppercase or lowercase (default lowercase).
+ :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 \ No newline at end of file
+ echo $this->input->method(TRUE); // Outputs: POST
+ echo $this->input->method(FALSE); // Outputs: post
+ echo $this->input->method(); // Outputs: post \ No newline at end of file