[ci skip] Update the Input library and Cookie helper docs

1 files changed, 227 insertions, 169 deletions

diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst
index 177f5cb64..39a0d0628 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.
@@ -33,7 +40,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 +51,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,262 +65,313 @@ 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()
-====================
+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 = FALSE]])
 
-::
+		:param string $index: POST parameter name
+		:param bool $xss_clean: Whether to apply XSS filtering
+		:returns: 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.
+		::
 
-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(); // 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 = FALSE]])
 
+		:param string $index: GET parameter name
+		:param bool $xss_clean: Whether to apply XSS filtering
+		:returns: mixed
 
-$this->input->get_post()
-========================
+		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->get_post('some_data', TRUE);
+		To return an array of all GET items call without any parameters.
 
-$this->input->cookie()
-======================
+		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 is identical to the post method, only it fetches cookie data
-::
+			$this->input->get(NULL, TRUE); // returns all GET items with XSS filter
+			$this->input->get(); // returns all GET items without XSS filtering
 
-	$this->input->cookie('some_cookie');
-	$this->input->cookie('some_cookie, TRUE); // with XSS filter
+	.. 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->input->server()
-======================
+		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 method is identical to the above methods, only it fetches server
-server data::
+			$this->input->get_post('some_data', TRUE);
 
-	$this->input->server('some_data');
+	.. method:: cookie([$index = ''[, $xss_clean = FALSE]])
 
-Using the php://input stream
-============================
+		:param string $index: COOKIE parameter name
+		:param bool $xss_clean: Whether to apply XSS filtering
+		:returns: mixed
 
-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 method is identical to ``post()`` and ``get()``, only it fetches cookie
+		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::
+			$this->input->cookie('some_cookie');
+			$this->input->cookie('some_cookie, TRUE); // with XSS filter
 
-	$this->input->input_stream('key');
+	.. method:: server([$index = ''[, $xss_clean = FALSE]])
 
-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::
+		:param string $index: Value name
+		:param bool $xss_clean: Whether to apply XSS filtering
+		:returns: mixed
 
-	$this->input->input_stream('key', TRUE); // XSS Clean
-	$this->input->input_stream('key', FALSE); // No XSS filter
+		This method is identical to the ``post()``, ``get()`` and ``cookie()`` methods,
+		only it fetches server data (``$_SERVER``)::
 
-.. note:: You can utilize method() in order to know if you're reading
-	PUT, DELETE or PATCH data.
+			$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()
-==========================
+			$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.
 
-The secure boolean is only needed if you want to make it a secure cookie
-by setting it to TRUE.
+	.. method:: ip_address()
 
-Discrete Parameters
-^^^^^^^^^^^^^^^^^^^
+		:returns: string
 
-If you prefer, you can set the cookie by passing data using individual
-parameters::
+		Returns the IP address for the current user. If the IP address is not
+		valid, the method will return '0.0.0.0'::
 
-	$this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure);
+			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.
 
-$this->input->ip_address()
-==========================
+	.. method:: valid_ip($ip[, $which = ''])
 
-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
+		: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.
 
-	echo $this->input->ip_address();
+		.. note:: The $this->input->ip_address() method above automatically
+			validates the IP address.
 
-$this->input->valid_ip($ip)
-===========================
+		::
 
-Takes an IP address as input and returns TRUE or FALSE (boolean) if 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.
 
-::
+	.. method:: user_agent()
 
-	if ( ! $this->input->valid_ip($ip))
-	{
-	     echo 'Not Valid';
-	}
-	else
-	{
-	     echo 'Valid';
-	}
+		:returns: string
 
-Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify
-an IP format. The default checks for both formats.
+		Returns the user agent string (web browser) being used by the current user,
+		or NULL if it's not available.
+		::
 
-$this->input->user_agent()
-==========================
+			echo $this->input->user_agent();
 
-Returns the user agent (web browser) being used by the current user.
-Returns FALSE if it's not available.
+		See the :doc:`User Agent Class <user_agent>` for methods which extract
+		information from the user agent string.
 
-::
+	.. method:: request_headers([$xss_clean = FALSE])
 
-	echo $this->input->user_agent();
+		:param bool $xss_clean: Whether to apply XSS filtering
+		:returns: array
 
-See the :doc:`User Agent Class <user_agent>` for methods which extract
-information from the user agent string.
+		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.
+		::
 
-$this->input->request_headers()
-===============================
+			$headers = $this->input->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 an array of headers.
+	.. 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: string
 
-	$headers = $this->input->request_headers();
+		Returns a single member of the request headers array or NULL
+		if the searched header is not found.
+		::
 
-$this->input->get_request_header()
-==================================
+			$this->input->get_request_header('some-header', TRUE);
 
-Returns a single member of the request headers array.
+	.. method:: is_ajax_request()
 
-::
+		:returns: bool
 
-	$this->input->get_request_header('some-header', TRUE);
+		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_ajax_request()
-===============================
+	.. method:: is_cli_request()
 
-Checks to see if the HTTP_X_REQUESTED_WITH server header has been
-set, and returns a boolean response.
+		:returns: bool
 
-$this->input->is_cli_request()
-==============================
+		Checks to see if the application was run from the command-line
+		interface.
 
-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.
+		.. 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()
+			$this->input->is_cli_request()
 
-$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: 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