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).

1 files changed, 121 insertions, 107 deletions

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)
@@ -303,23 +326,11 @@ 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)
 	{