summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2014-01-06 09:57:05 +0100
committerAndrey Andreev <narf@devilix.net>2014-01-06 09:57:05 +0100
commit04535c7169aa9401a3cf09c256df8319a67b778e (patch)
tree68502d4113be68a6bedd15a961193bad4b2ce9f0 /user_guide_src/source/libraries
parentfd7d9caa71e960f2bec806da423eb8d93419e24c (diff)
[ci skip] Update the Input library and Cookie helper docs
Diffstat (limited to 'user_guide_src/source/libraries')
-rw-r--r--user_guide_src/source/libraries/input.rst396
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