From 1887ec69c9230ff3fbde63f209b50ce69b28fc62 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 27 Oct 2012 16:22:07 +0300 Subject: Input class improvements - Disable register_globals replication on PHP 5.4+ (no longer exists). - DocBlock improvements. - Add missing changelog entry. - Change user_agent() to return NULL when no value is found (for consistency with other fetcher methods). --- system/core/Input.php | 228 +++++++++++++++++++++++++++----------------------- 1 file changed, 121 insertions(+), 107 deletions(-) (limited to 'system/core/Input.php') diff --git a/system/core/Input.php b/system/core/Input.php index ec935d531..18406fe43 100644 --- a/system/core/Input.php +++ b/system/core/Input.php @@ -41,59 +41,68 @@ class CI_Input { /** * IP address of the current user * - * @var string + * @var string */ - public $ip_address = FALSE; + public $ip_address = FALSE; /** - * user agent (web browser) being used by the current user + * User agent strin * - * @var string + * @var string */ - public $user_agent = FALSE; + public $user_agent = FALSE; /** - * If FALSE, then $_GET will be set to an empty array + * Allow GET array flag * - * @var bool + * If set to FALSE, then $_GET will be set to an empty array. + * + * @var bool */ - protected $_allow_get_array = TRUE; + protected $_allow_get_array = TRUE; /** - * If TRUE, then newlines are standardized + * Standartize new lines flag + * + * If set to TRUE, then newlines are standardized. * - * @var bool + * @var bool */ - protected $_standardize_newlines = TRUE; + protected $_standardize_newlines = TRUE; /** - * Determines whether the XSS filter is always active when GET, POST or COOKIE data is encountered - * Set automatically based on config setting + * Enable XSS flag + * + * Determines whether the XSS filter is always active when + * GET, POST or COOKIE data is encountered. + * Set automatically based on config setting. * - * @var bool + * @var bool */ - protected $_enable_xss = FALSE; + protected $_enable_xss = FALSE; /** + * Enable CSRF flag + * * Enables a CSRF cookie token to be set. - * Set automatically based on config setting + * Set automatically based on config setting. * - * @var bool + * @var bool */ - protected $_enable_csrf = FALSE; + protected $_enable_csrf = FALSE; /** * List of all HTTP request headers * * @var array */ - protected $headers = array(); + protected $headers = array(); /** - * Constructor + * Class constructor * - * Sets whether to globally enable the XSS processing - * and whether to allow the $_GET array + * Determines whether to globally enable the XSS processing + * and whether to allow the $_GET array. * * @return void */ @@ -124,12 +133,12 @@ class CI_Input { /** * Fetch from array * - * This is a helper function to retrieve values from global arrays + * Internal method used to retrieve values from global arrays. * - * @param array - * @param string - * @param bool - * @return string + * @param array &$array $_GET, $_POST, $_COOKIE, $_SERVER, etc. + * @param string $index Index for item to be fetched from $array + * @param bool $xss_clean Whether to apply XSS filtering + * @return mixed */ protected function _fetch_from_array(&$array, $index = '', $xss_clean = FALSE) { @@ -151,9 +160,9 @@ class CI_Input { /** * Fetch an item from the GET array * - * @param string - * @param bool - * @return string + * @param string $index Index for item to be fetched from $_GET + * @param bool $xss_clean Whether to apply XSS filtering + * @return mixed */ public function get($index = NULL, $xss_clean = FALSE) { @@ -178,9 +187,9 @@ class CI_Input { /** * Fetch an item from the POST array * - * @param string - * @param bool - * @return string + * @param string $index Index for item to be fetched from $_POST + * @param bool $xss_clean Whether to apply XSS filtering + * @return mixed */ public function post($index = NULL, $xss_clean = FALSE) { @@ -204,11 +213,11 @@ class CI_Input { // -------------------------------------------------------------------- /** - * Fetch an item from either the GET array or the POST + * Fetch an item from POST data with fallback to GET * - * @param string The index key - * @param bool XSS cleaning - * @return string + * @param string $index Index for item to be fetched from $_POST or $_GET + * @param bool $xss_clean Whether to apply XSS filtering + * @return mixed */ public function get_post($index = '', $xss_clean = FALSE) { @@ -222,31 +231,45 @@ class CI_Input { /** * Fetch an item from the COOKIE array * - * @param string - * @param bool - * @return string + * @param string $index Index for item to be fetched from $_COOKIE + * @param bool $xss_clean Whether to apply XSS filtering + * @return mixed */ public function cookie($index = '', $xss_clean = FALSE) { return $this->_fetch_from_array($_COOKIE, $index, $xss_clean); } + // -------------------------------------------------------------------- + + /** + * Fetch an item from the SERVER array + * + * @param string $index Index for item to be fetched from $_SERVER + * @param bool $xss_clean Whether to apply XSS filtering + * @return mixed + */ + public function server($index = '', $xss_clean = FALSE) + { + return $this->_fetch_from_array($_SERVER, $index, $xss_clean); + } + // ------------------------------------------------------------------------ /** * Set cookie * - * Accepts seven parameters, or you can submit an associative + * Accepts an arbitrary number of parameters (up to 7) or an associative * array in the first parameter containing all the values. * - * @param mixed - * @param string the value of the cookie - * @param string the number of seconds until expiration - * @param string the cookie domain. Usually: .yourdomain.com - * @param string the cookie path - * @param string the cookie prefix - * @param bool true makes the cookie secure - * @param bool true makes the cookie accessible via http(s) only (no javascript) + * @param string|mixed[] $name Cookie name or an array containing parameters + * @param string $value Cookie value + * @param int $expire Cookie expiration time in seconds + * @param string $domain Cookie domain (e.g.: '.yourdomain.com') + * @param string $path Cookie path (default: '/') + * @param string $prefix Cookie name prefix + * @param bool $secure Whether to only transfer cookies via SSL + * @param bool $httponly Whether to only makes the cookie accessible via HTTP (no javascript) * @return void */ public function set_cookie($name = '', $value = '', $expire = '', $domain = '', $path = '/', $prefix = '', $secure = FALSE, $httponly = FALSE) @@ -302,24 +325,12 @@ class CI_Input { // -------------------------------------------------------------------- - /** - * Fetch an item from the SERVER array - * - * @param string - * @param bool - * @return string - */ - public function server($index = '', $xss_clean = FALSE) - { - return $this->_fetch_from_array($_SERVER, $index, $xss_clean); - } - - // -------------------------------------------------------------------- - /** * Fetch the IP Address * - * @return string + * Determines and validates the visitor's IP address. + * + * @return string IP address */ public function ip_address() { @@ -458,8 +469,8 @@ class CI_Input { /** * Validate IP Address * - * @param string - * @param string 'ipv4' or 'ipv6' + * @param string $ip IP address + * @param string $which IP protocol: 'ipv4' or 'ipv6' * @return bool */ public function valid_ip($ip, $which = '') @@ -483,9 +494,9 @@ class CI_Input { // -------------------------------------------------------------------- /** - * User Agent + * Fetch User Agent string * - * @return string + * @return string|null User Agent string or NULL if it doesn't exist */ public function user_agent() { @@ -494,7 +505,7 @@ class CI_Input { return $this->user_agent; } - return $this->user_agent = isset($_SERVER['HTTP_USER_AGENT']) ? $_SERVER['HTTP_USER_AGENT'] : FALSE; + return $this->user_agent = isset($_SERVER['HTTP_USER_AGENT']) ? $_SERVER['HTTP_USER_AGENT'] : NULL; } // -------------------------------------------------------------------- @@ -502,11 +513,12 @@ class CI_Input { /** * Sanitize Globals * - * This function does the following: + * Internal method serving for the following purposes: * - * - Unsets $_GET data (if query strings are not enabled) - * - Unsets all globals if register_globals is enabled - * - Standardizes newline characters to \n + * - Unsets $_GET data (if query strings are not enabled) + * - Unsets all globals if register_globals is enabled + * - Cleans POST, COOKIE and SERVER data + * - Standardizes newline characters to PHP_EOL * * @return void */ @@ -534,25 +546,29 @@ class CI_Input { 'IN' ); - // Unset globals for securiy. + // Unset globals for security. // This is effectively the same as register_globals = off - foreach (array($_GET, $_POST, $_COOKIE) as $global) + // PHP 5.4 no longer has the register_globals functionality. + if ( ! is_php('5.4')) { - if (is_array($global)) + foreach (array($_GET, $_POST, $_COOKIE) as $global) { - foreach ($global as $key => $val) + if (is_array($global)) { - if ( ! in_array($key, $protected)) + foreach ($global as $key => $val) { - global $$key; - $$key = NULL; + if ( ! in_array($key, $protected)) + { + global $$key; + $$key = NULL; + } } } - } - elseif ( ! in_array($global, $protected)) - { - global $$global; - $$global = NULL; + elseif ( ! in_array($global, $protected)) + { + global $$global; + $$global = NULL; + } } } @@ -613,10 +629,10 @@ class CI_Input { /** * Clean Input Data * - * This is a helper function. It escapes data and - * standardizes newline characters to \n + * Internal method that aids in escaping data and + * standardizing newline characters to PHP_EOL. * - * @param string + * @param string|string[] $str Input string(s) * @return string */ protected function _clean_input_data($str) @@ -624,9 +640,9 @@ class CI_Input { if (is_array($str)) { $new_array = array(); - foreach ($str as $key => $val) + foreach (array_keys($str) as $key) { - $new_array[$this->_clean_input_keys($key)] = $this->_clean_input_data($val); + $new_array[$this->_clean_input_keys($key)] = $this->_clean_input_data($str[$key]); } return $new_array; } @@ -670,11 +686,11 @@ class CI_Input { /** * Clean Keys * - * This is a helper function. To prevent malicious users + * Internal method that helps to prevent malicious users * from trying to exploit keys we make sure that keys are * only named with alpha-numeric text and a few other items. * - * @param string + * @param string $str Input string * @return string */ protected function _clean_input_keys($str) @@ -699,15 +715,12 @@ class CI_Input { /** * Request Headers * - * In Apache, you can simply call apache_request_headers(), however for - * people running other webservers the function is undefined. - * - * @param bool XSS cleaning + * @param bool $xss_clean Whether to apply XSS filtering * @return array */ public function request_headers($xss_clean = FALSE) { - // Look at Apache go! + // In Apache, you can simply call apache_request_headers() if (function_exists('apache_request_headers')) { $headers = apache_request_headers(); @@ -744,9 +757,9 @@ class CI_Input { * * Returns the value of a single member of the headers class member * - * @param string array key for $this->headers - * @param bool XSS Clean or not - * @return mixed FALSE on failure, string on success + * @param string $index Header name + * @param bool $xss_clean Whether to apply XSS filtering + * @return string|bool The requested header on success or FALSE on failure */ public function get_request_header($index, $xss_clean = FALSE) { @@ -768,9 +781,9 @@ class CI_Input { // -------------------------------------------------------------------- /** - * Is ajax Request? + * Is AJAX request? * - * Test to see if a request contains the HTTP_X_REQUESTED_WITH header + * Test to see if a request contains the HTTP_X_REQUESTED_WITH header. * * @return bool */ @@ -782,9 +795,9 @@ class CI_Input { // -------------------------------------------------------------------- /** - * Is cli Request? + * Is CLI request? * - * Test to see if a request was made from the command line + * Test to see if a request was made from the command line. * * @return bool */ @@ -798,10 +811,11 @@ class CI_Input { /** * Get Request Method * - * Return the Request Method + * Return the request method * - * @param bool uppercase or lowercase - * @return bool + * @param bool $upper Whether to return in upper or lower case + * (default: FALSE) + * @return string */ public function method($upper = FALSE) { -- cgit v1.2.3-24-g4f1b