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 From 8831d115b5223b982650acb1bdb6c39fb25e199e Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 15:57:02 -0500 Subject: fixed code block spacing on Input lib docs --- user_guide_src/source/libraries/input.rst | 37 ++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) (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 index fd3cb57a6..bcf117358 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -53,7 +53,14 @@ 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']; } + if ( ! isset($_POST['something'])) + { + $something = FALSE; + } + else + { + $something = $_POST['something']; + } With CodeIgniter's built in functions you can simply do this:: @@ -92,7 +99,8 @@ 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->post(NULL, TRUE); // returns all POST items with XSS filter + $this->input->post(); // returns all POST items without XSS filter $this->input->get() =================== @@ -111,7 +119,9 @@ 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(NULL, TRUE); // returns all GET items with XSS filter + $this->input->get(); // returns all GET items without XSS filtering + $this->input->get_post() ========================= @@ -150,7 +160,17 @@ 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); + $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:** @@ -220,7 +240,14 @@ validates the IP automatically. :: - if ( ! $this->input->valid_ip($ip)) {      echo 'Not Valid'; } else {      echo 'Valid'; } + if ( ! $this->input->valid_ip($ip)) + { + echo 'Not Valid'; + } + else + { + echo 'Valid'; + } $this->input->user_agent() =========================== -- cgit v1.2.3-24-g4f1b From be0ca26c9006981eced5d938060ba5bad4145e3b Mon Sep 17 00:00:00 2001 From: Michiel Vugteveen Date: Wed, 7 Mar 2012 19:09:51 +0100 Subject: added method() and is_method() --- user_guide_src/source/libraries/input.rst | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) (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 index bcf117358..96d1f07e1 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -99,7 +99,7 @@ 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(NULL, TRUE); // returns all POST items with XSS filter $this->input->post(); // returns all POST items without XSS filter $this->input->get() @@ -119,9 +119,9 @@ 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(NULL, TRUE); // returns all GET items with XSS filter $this->input->get(); // returns all GET items without XSS filtering - + $this->input->get_post() ========================= @@ -298,3 +298,28 @@ see if PHP is being run on the command line. $this->input->is_cli_request() +$this->input->method(); +===================================== + +Returns the $_SERVER['REQUEST_METHOD'] in lowercase. + +:: + + $this->input->method(); + +$this->input->is_method($method); +===================================== + +Returns TRUE if given method equals $_SERVER['REQUEST_METHOD'], otherwise returns FALSE. + +:: + + if ( ! $this->input->is_method('post')) + { + echo 'This is NOT a POST request'; + } + else + { + echo 'This is a POST request'; + } + -- cgit v1.2.3-24-g4f1b From dc900df67972ed1c961fc3e4173db98047bdbd1b Mon Sep 17 00:00:00 2001 From: Michiel Vugteveen Date: Wed, 7 Mar 2012 20:41:37 +0100 Subject: removed is_method --- user_guide_src/source/libraries/input.rst | 23 ++++------------------- 1 file changed, 4 insertions(+), 19 deletions(-) (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 index 96d1f07e1..c63c627db 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -301,25 +301,10 @@ see if PHP is being run on the command line. $this->input->method(); ===================================== -Returns the $_SERVER['REQUEST_METHOD'] in lowercase. +Returns the $_SERVER['REQUEST_METHOD'], optional set uppercase or lowercase (standard lowercase). :: - $this->input->method(); - -$this->input->is_method($method); -===================================== - -Returns TRUE if given method equals $_SERVER['REQUEST_METHOD'], otherwise returns FALSE. - -:: - - if ( ! $this->input->is_method('post')) - { - echo 'This is NOT a POST request'; - } - else - { - echo 'This is a POST request'; - } - + echo $this->input->method(TRUE); // Outputs: POST + echo $this->input->method(FALSE); // Outputs: post + echo $this->input->method(); // Outputs: post -- cgit v1.2.3-24-g4f1b From 1e9fb49a9eb5cebbe2e3cdf106892d9af72cfdc5 Mon Sep 17 00:00:00 2001 From: Michiel Vugteveen Date: Wed, 7 Mar 2012 20:51:25 +0100 Subject: userguide fix --- user_guide_src/source/libraries/input.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (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 index c63c627db..1f2ea650a 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -301,7 +301,7 @@ see if PHP is being run on the command line. $this->input->method(); ===================================== -Returns the $_SERVER['REQUEST_METHOD'], optional set uppercase or lowercase (standard lowercase). +Returns the $_SERVER['REQUEST_METHOD'], optional set uppercase or lowercase (default lowercase). :: -- cgit v1.2.3-24-g4f1b From 55a6ddb0c7bab1149bb1ddfa3a1aff46612c91d4 Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Wed, 23 May 2012 18:37:24 +0100 Subject: Input, Session and Cookie get's will return NULL. Read more about this change here: http://codeigniter.com/forums/viewthread/215833 --- user_guide_src/source/libraries/input.rst | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) (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 index 1f2ea650a..432bac3c7 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -18,7 +18,7 @@ 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 +- 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. @@ -53,14 +53,7 @@ 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']; - } + $something = isset($_POST['something']) ? $_POST['something'] : NULL; With CodeIgniter's built in functions you can simply do this:: @@ -95,7 +88,7 @@ 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. +The function returns NULL if there are no items in the POST. :: @@ -115,7 +108,7 @@ 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. +The function returns NULL if there are no items in the GET. :: @@ -210,7 +203,7 @@ the cookie you are looking for (including any prefixes):: cookie('some_cookie'); -The function returns FALSE (boolean) if the item you are attempting to +The function 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 -- cgit v1.2.3-24-g4f1b From 5a257187c4ca09ea61c19999bf061cec3f224cc2 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sun, 10 Jun 2012 06:18:14 +0300 Subject: Merge branch 2.1-stable into develop --- user_guide_src/source/libraries/input.rst | 3 +++ 1 file changed, 3 insertions(+) (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 index 432bac3c7..7f995f050 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -242,6 +242,9 @@ validates the IP automatically. echo 'Valid'; } +Accepts an optional second string parameter of 'ipv4' or 'ipv6' to specify +an IP format. The default checks for both formats. + $this->input->user_agent() =========================== -- cgit v1.2.3-24-g4f1b From 9cf12d1de76c2696233a437e0cdc7266bb846ae6 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Wed, 13 Jun 2012 10:19:59 +0300 Subject: Fix docs for Input library (issue #1465) --- user_guide_src/source/libraries/input.rst | 37 +++++++++---------------------- 1 file changed, 10 insertions(+), 27 deletions(-) (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 index 7f995f050..8c6f7c849 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -42,14 +42,14 @@ this:: Please refer to the :doc:`Security class ` documentation for information on using XSS Filtering in your application. -Using POST, COOKIE, or SERVER Data -================================== +Using POST, GET, COOKIE, or SERVER Data +======================================= -CodeIgniter comes with three helper functions that let you fetch POST, +CodeIgniter comes with four helper methods that let you fetch POST, GET, 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 +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:: @@ -73,8 +73,8 @@ looking for:: $this->input->post('some_data'); -The function returns FALSE (boolean) if the item you are attempting to -retrieve does not exist. +The function 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; @@ -130,7 +130,9 @@ $this->input->cookie() This function is identical to the post function, only it fetches cookie data:: - $this->input->cookie('some_data', TRUE); + $this->input->cookie('some_cookie'); + $this->input->cookie('some_cookie, TRUE); // with XSS filter + $this->input->server() ====================== @@ -195,25 +197,6 @@ 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 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; - -:: - - cookie('some_cookie', TRUE); - - $this->input->ip_address() =========================== -- cgit v1.2.3-24-g4f1b From 22c3e73573d2828cec6183866b162359f873a949 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Wed, 13 Jun 2012 10:21:36 +0300 Subject: Another input library docs fix --- user_guide_src/source/libraries/input.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (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 index 8c6f7c849..c0b9c6589 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -59,9 +59,10 @@ With CodeIgniter's built in functions you can simply do this:: $something = $this->input->post('something'); -The three functions are: +The four methods are: - $this->input->post() +- $this->input->get() - $this->input->cookie() - $this->input->server() -- cgit v1.2.3-24-g4f1b