summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/input.rst
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2017-06-19 10:33:58 +0200
committerAndrey Andreev <narf@devilix.net>2017-06-19 10:33:58 +0200
commit6c7a4266410070d30f8f6bcdf9c9e67f3d6478e3 (patch)
treef0aab8f6f5e781d5947b1a5553b6648eb7b7a4ab /user_guide_src/source/libraries/input.rst
parent2459285b91d6fc4f5099f9f597529cce1059cb33 (diff)
[ci skip] 3.1.5 release
Diffstat (limited to 'user_guide_src/source/libraries/input.rst')
-rw-r--r--user_guide_src/source/libraries/input.rst474
1 files changed, 0 insertions, 474 deletions
diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst
deleted file mode 100644
index e7107fa06..000000000
--- a/user_guide_src/source/libraries/input.rst
+++ /dev/null
@@ -1,474 +0,0 @@
-###########
-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