[ci skip] Update the Input library and Cookie helper docs
diff --git a/user_guide_src/source/helpers/cookie_helper.rst b/user_guide_src/source/helpers/cookie_helper.rst
index e70893f..2e8db5f 100644
--- a/user_guide_src/source/helpers/cookie_helper.rst
+++ b/user_guide_src/source/helpers/cookie_helper.rst
@@ -25,18 +25,17 @@
The following functions are available:
-.. function:: set_cookie([$name = ''[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = FALSE[, $httponly = FALSE]]]]]]]])
+.. function:: set_cookie($name[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = FALSE[, $httponly = FALSE]]]]]]]])
- :param mixed $name: Cookie name *or* associative array of all of
- the parameters available to this function
- :param string $value: Cookie value
- :param int $expire: Number of seconds until expiration
- :param string $domain: Cookie domain (usually: .yourdomain.com)
- :param string $path: Cookie path
- :param string $prefix: Cookie name prefix
- :param bool $secure: Whether to only send the cookie through HTTPS
- :param bool $httponly: Whether to hide the cookie from JavaScript
- :returns: void
+ :param mixed $name: Cookie name *or* associative array of all of the parameters available to this function
+ :param string $value: Cookie value
+ :param int $expire: Number of seconds until expiration
+ :param string $domain: Cookie domain (usually: .yourdomain.com)
+ :param string $path: Cookie path
+ :param string $prefix: Cookie name prefix
+ :param bool $secure: Whether to only send the cookie through HTTPS
+ :param bool $httponly: Whether to hide the cookie from JavaScript
+ :returns: void
This helper function gives you view file friendly syntax to set browser
cookies. Refer to the :doc:`Input Library <../libraries/input>` for a
@@ -44,28 +43,27 @@
``CI_Input::set_cookie()``.
-.. function:: get_cookie([$index = ''[, $xss_clean = FALSE]])
+.. function:: get_cookie($index[, $xss_clean = FALSE]])
- :param string $index: Cookie name
- :param bool $xss_clean: Whether to apply XSS filtering to the returned value
- :returns: mixed
+ :param string $index: Cookie name
+ :param bool $xss_clean: Whether to apply XSS filtering to the returned value
+ :returns: mixed
This helper function gives you view file friendly syntax to get browser
cookies. Refer to the :doc:`Input Library <../libraries/input>` for a
description of its use, as this function is an alias for ``CI_Input::cookie()``.
-.. function:: delete_cookie([$name = ''[, $domain = ''[, $path = '/'[, $prefix = '']]]])
+.. function:: delete_cookie($name[, $domain = ''[, $path = '/'[, $prefix = '']]]])
- :param string $name: Cookie name
- :param string $domain: Cookie domain (usually: .yourdomain.com)
- :param string $path: Cookie path
- :param string $prefix: Cookie name prefix
+ :param string $name: Cookie name
+ :param string $domain: Cookie domain (usually: .yourdomain.com)
+ :param string $path: Cookie path
+ :param string $prefix: Cookie name prefix
:returns: void
Lets you delete a cookie. Unless you've set a custom path or other
values, only the name of the cookie is needed.
-
::
delete_cookie('name');
@@ -74,7 +72,6 @@
does not have the value and expiration parameters. You can submit an
array of values in the first parameter or you can set discrete
parameters.
-
::
delete_cookie($name, $domain, $path, $prefix)
\ No newline at end of file
diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst
index 177f5cb..39a0d06 100644
--- a/user_guide_src/source/libraries/input.rst
+++ b/user_guide_src/source/libraries/input.rst
@@ -10,6 +10,13 @@
.. 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 @@
: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.
@@ -33,7 +40,7 @@
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 +51,7 @@
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,90 +65,13 @@
$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()
-====================
-
-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;
-
-::
-
- $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;
-
-The method returns NULL if there are no items in the POST.
-
-::
-
- $this->input->post(NULL, TRUE); // returns all POST items with XSS filter
- $this->input->post(); // returns all POST items without XSS filter
-
-$this->input->get()
-===================
-
-This method is identical to the post method, 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;
-
-The method returns NULL if there are no items in the GET.
-
-::
-
- $this->input->get(NULL, TRUE); // returns all GET items with XSS filter
- $this->input->get(); // returns all GET items without XSS filtering
-
-
-$this->input->get_post()
-========================
-
-This method will search through both the post and get streams for
-data, looking first in post, and then in get::
-
- $this->input->get_post('some_data', TRUE);
-
-$this->input->cookie()
-======================
-
-This method is identical to the post method, only it fetches cookie data
-::
-
- $this->input->cookie('some_cookie');
- $this->input->cookie('some_cookie, TRUE); // with XSS filter
-
-
-$this->input->server()
-======================
-
-This method is identical to the above methods, only it fetches server
-server data::
-
- $this->input->server('some_data');
-
Using the php://input stream
============================
@@ -158,162 +88,290 @@
$this->input->input_stream('key');
-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::
+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
+.. note:: You can utilize ``method()`` in order to know if you're reading
PUT, DELETE or PATCH data.
-$this->input->set_cookie()
-==========================
+***************
+Class Reference
+***************
-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:
+.. class:: CI_Input
-Array Method
-^^^^^^^^^^^^
+ .. method:: post([$index = NULL[, $xss_clean = FALSE]])
-Using this method, an associative array is passed to the first
-parameter::
+ :param string $index: POST parameter name
+ :param bool $xss_clean: Whether to apply XSS filtering
+ :returns: mixed
- $cookie = array(
- 'name' => 'The Cookie Name',
- 'value' => 'The Value',
- 'expire' => '86500',
- 'domain' => '.some-domain.com',
- 'path' => '/',
- 'prefix' => 'myprefix_',
- 'secure' => TRUE
- );
+ The first parameter will contain the name of the POST item you are
+ looking for::
- $this->input->set_cookie($cookie);
+ $this->input->post('some_data');
-**Notes:**
+ The method returns NULL if the item you are attempting to retrieve
+ does not exist.
-Only the name and value are required. To delete a cookie set it with the
-expiration blank.
+ The second optional parameter lets you run the data through the XSS
+ filter. It's enabled by setting the second parameter to boolean 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.
+ $this->input->post('some_data', 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
+ To return an array of all POST items call without any parameters.
-The path is usually not needed since the method sets a root path.
+ 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.
+ ::
-The prefix is only needed if you need to avoid name collisions with
-other identically named cookies for your server.
+ $this->input->post(NULL, TRUE); // returns all POST items with XSS filter
+ $this->input->post(); // returns all POST items without XSS filter
-The secure boolean is only needed if you want to make it a secure cookie
-by setting it to TRUE.
+ .. method:: get([$index = NULL[, $xss_clean = FALSE]])
-Discrete Parameters
-^^^^^^^^^^^^^^^^^^^
+ :param string $index: GET parameter name
+ :param bool $xss_clean: Whether to apply XSS filtering
+ :returns: mixed
-If you prefer, you can set the cookie by passing data using individual
-parameters::
+ This method is identical to ``post()``, only it fetches GET data.
+ ::
- $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure);
+ $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(); // returns all GET items without XSS filtering
+
+ .. method:: get_post([$index = ''[, $xss_clean = FALSE]])
+
+ :param string $index: GET/POST parameter name
+ :param bool $xss_clean: Whether to apply XSS filtering
+ :returns: mixed
+
+ This method works the same way as ``post()`` and ``get()``, only combined.
+ It will search through both POST and GET streams for data, looking first
+ in POST, and then in GET::
+
+ $this->input->get_post('some_data', TRUE);
+
+ .. method:: cookie([$index = ''[, $xss_clean = FALSE]])
+
+ :param string $index: COOKIE parameter name
+ :param bool $xss_clean: Whether to apply XSS filtering
+ :returns: 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
+
+ .. method:: server([$index = ''[, $xss_clean = FALSE]])
+
+ :param string $index: Value name
+ :param bool $xss_clean: Whether to apply XSS filtering
+ :returns: 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 = ''[, $xss_clean = FALSE]])
+
+ :param string $index: Key name
+ :param bool $xss_clean: Whether to apply XSS filtering
+ :returns: 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)
+ :returns: 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 secure boolean is only needed if you want to make it a secure cookie
+ by setting it to TRUE.
+
+ 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);
-$this->input->ip_address()
-==========================
+ .. method:: ip_address()
-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
+ :returns: 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();
+ echo $this->input->ip_address();
-$this->input->valid_ip($ip)
-===========================
+ .. 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.
-Takes an IP address as input and returns TRUE or FALSE (boolean) if it
-is valid or not.
+ .. method:: valid_ip($ip[, $which = ''])
-.. note:: The $this->input->ip_address() method above automatically
- validates the IP address.
+ :param string $ip: IP address
+ :param string $which: IP protocol ('ipv4' or 'ipv6')
+ :returns: bool
-::
+ Takes an IP address as input and returns TRUE or FALSE (boolean) depending
+ on whether it is valid or not.
- if ( ! $this->input->valid_ip($ip))
- {
- echo 'Not Valid';
- }
- else
- {
- echo 'Valid';
- }
+ .. note:: The $this->input->ip_address() method above automatically
+ validates the IP address.
-Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify
-an IP format. The default checks for both formats.
+ ::
-$this->input->user_agent()
-==========================
+ if ( ! $this->input->valid_ip($ip))
+ {
+ echo 'Not Valid';
+ }
+ else
+ {
+ echo 'Valid';
+ }
-Returns the user agent (web browser) being used by the current user.
-Returns FALSE 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.
-::
+ .. method:: user_agent()
- echo $this->input->user_agent();
+ :returns: string
-See the :doc:`User Agent Class <user_agent>` for methods which extract
-information from the user agent string.
+ Returns the user agent string (web browser) being used by the current user,
+ or NULL if it's not available.
+ ::
-$this->input->request_headers()
-===============================
+ echo $this->input->user_agent();
-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.
+ See the :doc:`User Agent Class <user_agent>` for methods which extract
+ information from the user agent string.
-::
+ .. method:: request_headers([$xss_clean = FALSE])
- $headers = $this->input->request_headers();
+ :param bool $xss_clean: Whether to apply XSS filtering
+ :returns: array
-$this->input->get_request_header()
-==================================
+ 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.
+ ::
-Returns a single member of the request headers array.
+ $headers = $this->input->request_headers();
-::
+ .. method:: get_request_header($index[, $xss_clean = FALSE])
- $this->input->get_request_header('some-header', TRUE);
+ :param string $index: HTTP request header name
+ :param bool $xss_clean: Whether to apply XSS filtering
+ :returns: string
-$this->input->is_ajax_request()
-===============================
+ Returns a single member of the request headers array or NULL
+ if the searched header is not found.
+ ::
-Checks to see if the HTTP_X_REQUESTED_WITH server header has been
-set, and returns a boolean response.
+ $this->input->get_request_header('some-header', TRUE);
-$this->input->is_cli_request()
-==============================
+ .. method:: is_ajax_request()
-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.
+ :returns: 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->is_cli_request()
+ .. method:: is_cli_request()
-$this->input->method()
-======================
+ :returns: bool
-Returns the $_SERVER['REQUEST_METHOD'], optional set uppercase or lowercase (default lowercase).
+ 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.
- 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
+ ::
+
+ $this->input->is_cli_request()
+
+ .. method:: method([$upper = FALSE])
+
+ :param bool $upper: Whether to return the request method name in upper or lower case
+ :returns: 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