From 8ede1a2ecbb62577afd32996956c5feaf7ddf9b6 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 13:34:52 -0500 Subject: replacing the old HTML user guide with a Sphinx-managed user guide --- user_guide_src/source/libraries/input.rst | 273 ++++++++++++++++++++++++++++++ 1 file changed, 273 insertions(+) create mode 100644 user_guide_src/source/libraries/input.rst (limited to 'user_guide_src/source/libraries/input.rst') diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst new file mode 100644 index 000000000..fd3cb57a6 --- /dev/null +++ b/user_guide_src/source/libraries/input.rst @@ -0,0 +1,273 @@ +########### +Input Class +########### + +The Input Class serves two purposes: + +#. It pre-processes global input data for security. +#. It provides some helper functions 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. + +Security Filtering +================== + +The security filtering function 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 \\n(In Windows \\r\\n) + +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 ` documentation for +information on using XSS Filtering in your application. + +Using POST, COOKIE, or SERVER Data +================================== + +CodeIgniter comes with three helper functions that let you fetch POST, +COOKIE or SERVER items. The main advantage of using the provided +functions rather than fetching an item directly ($_POST['something']) +is that the functions will check to see if the item is set and return +false (boolean) 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:: + + if ( ! isset($_POST['something'])) {     $something = FALSE; } else {     $something = $_POST['something']; } + +With CodeIgniter's built in functions you can simply do this:: + + $something = $this->input->post('something'); + +The three functions are: + +- $this->input->post() +- $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 function returns FALSE (boolean) 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 function returns FALSE (boolean) 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 function is identical to the post function, 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 function returns FALSE (boolean) 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 function 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 function is identical to the post function, only it fetches cookie +data:: + + $this->input->cookie('some_data', TRUE); + +$this->input->server() +====================== + +This function is identical to the above functions, only it fetches +server data:: + + $this->input->server('some_data'); + +$this->input->set_cookie() +=========================== + +Sets a cookie containing the values you specify. There are two ways to +pass information to this function 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 function 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->cookie() +====================== + +Lets you fetch a cookie. The first parameter will contain the name of +the cookie you are looking for (including any prefixes):: + + cookie('some_cookie'); + +The function returns FALSE (boolean) 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; + +:: + + cookie('some_cookie', TRUE); + + +$this->input->ip_address() +=========================== + +Returns the IP address for the current user. If the IP address is not +valid, the function will return an IP of: 0.0.0.0 + +:: + + echo $this->input->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. Note: The $this->input->ip_address() function above +validates the IP automatically. + +:: + + if ( ! $this->input->valid_ip($ip)) {      echo 'Not Valid'; } else {      echo 'Valid'; } + +$this->input->user_agent() +=========================== + +Returns the user agent (web browser) being used by the current user. +Returns FALSE if it's not available. + +:: + + echo $this->input->user_agent(); + +See the :doc:`User Agent Class ` for methods which extract +information from the user agent string. + +$this->input->request_headers() +================================ + +Useful if running in a non-Apache environment where +`apache_request_headers() `_ +will not be supported. Returns an array of headers. + +:: + + $headers = $this->input->request_headers(); + +$this->input->get_request_header(); +===================================== + +Returns a single member of the request headers array. + +:: + + $this->input->get_request_header('some-header', TRUE); + +$this->input->is_ajax_request() +================================= + +Checks to see if the HTTP_X_REQUESTED_WITH server header has been +set, and returns a boolean response. + +$this->input->is_cli_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. + +:: + + $this->input->is_cli_request() + -- cgit v1.2.3-24-g4f1b