From 04535c7169aa9401a3cf09c256df8319a67b778e Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 6 Jan 2014 10:57:05 +0200 Subject: [ci skip] Update the Input library and Cookie helper docs --- user_guide_src/source/libraries/input.rst | 396 +++++++++++++++++------------- 1 file changed, 227 insertions(+), 169 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 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 + +
+ 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 ` 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 ` 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() `_ + 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() `_ -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 -- cgit v1.2.3-24-g4f1b From 88ebdf7ad98c2d24f9ba6b9839ab50c98cf0eb65 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Wed, 8 Jan 2014 17:28:02 +0200 Subject: [ci skip] Update the Input library and Cookie helper docs default value is now NULL --- user_guide_src/source/libraries/input.rst | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 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 39a0d0628..4d8fdaf15 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -105,7 +105,7 @@ Class Reference .. class:: CI_Input - .. method:: post([$index = NULL[, $xss_clean = FALSE]]) + .. method:: post([$index = NULL[, $xss_clean = NULL]]) :param string $index: POST parameter name :param bool $xss_clean: Whether to apply XSS filtering @@ -120,7 +120,8 @@ Class Reference 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. + 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); @@ -132,9 +133,9 @@ Class Reference :: $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, FALSE); // returns all POST items without XSS filter - .. method:: get([$index = NULL[, $xss_clean = FALSE]]) + .. method:: get([$index = NULL[, $xss_clean = NULL]]) :param string $index: GET parameter name :param bool $xss_clean: Whether to apply XSS filtering @@ -152,9 +153,9 @@ Class Reference :: $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, FALSE); // returns all GET items without XSS filtering - .. method:: get_post([$index = ''[, $xss_clean = FALSE]]) + .. method:: get_post([$index = ''[, $xss_clean = NULL]]) :param string $index: GET/POST parameter name :param bool $xss_clean: Whether to apply XSS filtering @@ -166,7 +167,7 @@ Class Reference $this->input->get_post('some_data', TRUE); - .. method:: cookie([$index = ''[, $xss_clean = FALSE]]) + .. method:: cookie([$index = ''[, $xss_clean = NULL]]) :param string $index: COOKIE parameter name :param bool $xss_clean: Whether to apply XSS filtering @@ -178,7 +179,7 @@ Class Reference $this->input->cookie('some_cookie'); $this->input->cookie('some_cookie, TRUE); // with XSS filter - .. method:: server([$index = ''[, $xss_clean = FALSE]]) + .. method:: server([$index = ''[, $xss_clean = NULL]]) :param string $index: Value name :param bool $xss_clean: Whether to apply XSS filtering @@ -189,7 +190,7 @@ Class Reference $this->input->server('some_data'); - .. method:: input_stream([$index = ''[, $xss_clean = FALSE]]) + .. method:: input_stream([$index = ''[, $xss_clean = NULL]]) :param string $index: Key name :param bool $xss_clean: Whether to apply XSS filtering -- cgit v1.2.3-24-g4f1b From 75b3fb26a324c71ff18fa19b2a3caa357f8133ec Mon Sep 17 00:00:00 2001 From: Connor Tumbleson Date: Sat, 11 Jan 2014 06:58:43 -0600 Subject: cleanup warnings Signed-off-by: Connor Tumbleson --- user_guide_src/source/libraries/input.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 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 4d8fdaf15..f5ab04883 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -215,8 +215,7 @@ Class Reference pass information to this method so that a cookie can be set: Array Method, and Discrete Parameters: - Array Method - ^^^^^^^^^^^^ + **Array Method** Using this method, an associative array is passed to the first parameter:: @@ -255,8 +254,7 @@ Class Reference The secure boolean is only needed if you want to make it a secure cookie by setting it to TRUE. - Discrete Parameters - ^^^^^^^^^^^^^^^^^^^ + **Discrete Parameters** If you prefer, you can set the cookie by passing data using individual parameters:: -- cgit v1.2.3-24-g4f1b From 28c2c975b118016d07212ed8e7c22ff280309f82 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 8 Feb 2014 04:27:48 +0200 Subject: [ci skip] Add return types to library docs --- user_guide_src/source/libraries/input.rst | 115 +++++++++++++++++------------- 1 file changed, 65 insertions(+), 50 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 8a83207af..7ebf0e1c7 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -68,10 +68,10 @@ With CodeIgniter's built in methods you can simply do this:: The main methods are: -- $this->input->post() -- $this->input->get() -- $this->input->cookie() -- $this->input->server() +- ``$this->input->post()`` +- ``$this->input->get()`` +- ``$this->input->cookie()`` +- ``$this->input->server()`` Using the php://input stream ============================ @@ -108,9 +108,10 @@ Class Reference .. method:: post([$index = NULL[, $xss_clean = NULL]]) - :param string $index: POST parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $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:: @@ -138,9 +139,10 @@ Class Reference .. method:: get([$index = NULL[, $xss_clean = NULL]]) - :param string $index: GET parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $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. :: @@ -158,9 +160,10 @@ Class Reference .. method:: post_get([$index = ''[, $xss_clean = NULL]]) - :param string $index: POST/GET parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :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 the same way as ``post()`` and ``get()``, only combined. It will search through both POST and GET streams for data, looking in POST @@ -170,9 +173,10 @@ Class Reference .. method:: get_post([$index = ''[, $xss_clean = NULL]]) - :param string $index: GET/POST parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :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. @@ -184,9 +188,10 @@ Class Reference .. method:: cookie([$index = ''[, $xss_clean = NULL]]) - :param string $index: COOKIE parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: COOKIE parameter 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:: @@ -196,9 +201,10 @@ Class Reference .. method:: server([$index = ''[, $xss_clean = NULL]]) - :param string $index: Value name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $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``):: @@ -207,24 +213,26 @@ Class Reference .. method:: input_stream([$index = ''[, $xss_clean = NULL]]) - :param string $index: Key name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $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. .. 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 + :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 @@ -247,7 +255,7 @@ Class Reference $this->input->set_cookie($cookie); - **Notes:** + **Notes** Only the name and value are required. To delete a cookie set it with the expiration blank. @@ -276,10 +284,10 @@ Class Reference $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure); - .. method:: ip_address() - :returns: string + :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':: @@ -293,9 +301,10 @@ Class Reference .. method:: valid_ip($ip[, $which = '']) - :param string $ip: IP address - :param string $which: IP protocol ('ipv4' or 'ipv6') - :returns: bool + :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. @@ -319,7 +328,8 @@ Class Reference .. method:: user_agent() - :returns: string + :returns: User agent string or NULL if not set + :rtype: mixed Returns the user agent string (web browser) being used by the current user, or NULL if it's not available. @@ -332,8 +342,9 @@ Class Reference .. method:: request_headers([$xss_clean = FALSE]) - :param bool $xss_clean: Whether to apply XSS filtering - :returns: array + :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 @@ -345,9 +356,10 @@ Class Reference .. 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 + :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. @@ -357,14 +369,16 @@ Class Reference .. method:: is_ajax_request() - :returns: bool + :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. .. method:: is_cli_request() - :returns: bool + :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. @@ -382,8 +396,9 @@ Class Reference .. method:: method([$upper = FALSE]) - :param bool $upper: Whether to return the request method name in upper or lower case - :returns: string + :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. -- cgit v1.2.3-24-g4f1b From 7c60b12da3260cb3046f3f500431a1b7a5fb766d Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 8 Feb 2014 18:47:19 +0200 Subject: CI_Input tweaks - Make get_post(), post_get() and server()'s parameter mandatory. - Change default value of parameter to NULL for cookie(), input_stream() and _fetch_from_array() (for consistency with get(), post()). - Delegate Array-vs-single and parameter detection to _fetch_from_array() to overall simplify the code. --- user_guide_src/source/libraries/input.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 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 7ebf0e1c7..6162a6664 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -158,20 +158,20 @@ Class Reference $this->input->get(NULL, TRUE); // returns all GET items with XSS filter $this->input->get(NULL, FALSE); // returns all GET items without XSS filtering - .. method:: post_get([$index = ''[, $xss_clean = NULL]]) + .. 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 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 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); - .. method:: get_post([$index = ''[, $xss_clean = NULL]]) + .. method:: get_post($index[, $xss_clean = NULL]) :param string $index: GET/POST parameter name :param bool $xss_clean: Whether to apply XSS filtering @@ -186,7 +186,7 @@ Class Reference .. note:: This method used to act EXACTLY like ``post_get()``, but it's behavior has changed in CodeIgniter 3.0. - .. method:: cookie([$index = ''[, $xss_clean = NULL]]) + .. method:: cookie([$index = NULL[, $xss_clean = NULL]]) :param string $index: COOKIE parameter name :param bool $xss_clean: Whether to apply XSS filtering @@ -199,19 +199,19 @@ Class Reference $this->input->cookie('some_cookie'); $this->input->cookie('some_cookie, TRUE); // with XSS filter - .. method:: server([$index = ''[, $xss_clean = NULL]]) + .. method:: server($index[, $xss_clean = NULL]) :param string $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 method is identical to the ``post()``, ``get()`` and ``cookie()`` + methods, only it fetches server data (``$_SERVER``):: $this->input->server('some_data'); - .. method:: input_stream([$index = ''[, $xss_clean = NULL]]) + .. method:: input_stream([$index = NULL[, $xss_clean = NULL]]) :param string $index: Key name :param bool $xss_clean: Whether to apply XSS filtering -- cgit v1.2.3-24-g4f1b