diff options
Diffstat (limited to 'user_guide_src/source/libraries/input.rst')
| -rw-r--r-- | user_guide_src/source/libraries/input.rst | 396 |
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 |