Merge pull request #12736 from bancer/2.x-documentation

Improve documentation and code style

lib/Cake/Controller/Component/RequestHandlerComponent.php

@@ -271,8 +271,10 @@ class RequestHandlerComponent extends Component {
 		}
 		if (!empty($status)) {
 			$statusCode = $this->response->httpCodes($status);
-			$code = key($statusCode);
-			$this->response->statusCode($code);
+			if (is_array($statusCode)) {
+				$code = key($statusCode);
+				$this->response->statusCode($code);
+			}
 		}
 		$this->response->body($this->requestAction($url, array('return', 'bare' => false)));
 		$this->response->send();

lib/Cake/Controller/Controller.php

@@ -712,7 +712,7 @@ class Controller extends CakeObject implements CakeEventListener {
  *            800 => 'Unexpected Minotaur'
  *        )); // sets these new values, and returns true
  *
- * @return array Associative array of the HTTP codes as keys, and the message
+ * @return array|null|true Associative array of the HTTP codes as keys, and the message
  *    strings as values, or null of the given $code does not exist.
  * @deprecated 3.0.0 Since 2.4. Will be removed in 3.0. Use CakeResponse::httpCodes().
  */
@@ -757,7 +757,7 @@ class Controller extends CakeObject implements CakeEventListener {
  *
  * @param string|array $url A string or array-based URL pointing to another location within the app,
  *     or an absolute URL
- * @param int|array|null $status HTTP status code (eg: 301). Defaults to 302 when null is passed.
+ * @param int|array|null|string $status HTTP status code (eg: 301). Defaults to 302 when null is passed.
  * @param bool $exit If true, exit() will be called after the redirect
  * @return CakeResponse|null
  * @triggers Controller.beforeRedirect $this, array($url, $status, $exit)
@@ -905,7 +905,7 @@ class Controller extends CakeObject implements CakeEventListener {
  *
  * `$errors = $this->validateErrors($this->Article, $this->User);`
  *
- * @return array Validation errors, or false if none
+ * @return array|false Validation errors, or false if none
  * @deprecated 3.0.0 This method will be removed in 3.0
  */
 	public function validateErrors() {

lib/Cake/Network/CakeRequest.php

@@ -246,6 +246,7 @@ class CakeRequest implements ArrayAccess {
  * @return string URI The CakePHP request path that is being accessed.
  */
 	protected function _url() {
+		$uri = '';
 		if (!empty($_SERVER['PATH_INFO'])) {
 			return $_SERVER['PATH_INFO'];
 		} elseif (isset($_SERVER['REQUEST_URI']) && strpos($_SERVER['REQUEST_URI'], '://') === false) {

lib/Cake/Network/CakeResponse.php

@@ -331,7 +331,7 @@ class CakeResponse {
  * Content type to send. This can be an 'extension' that will be transformed using the $_mimetypes array
  * or a complete mime-type
  *
- * @var int
+ * @var string
  */
 	protected $_contentType = 'text/html';
 
@@ -374,7 +374,7 @@ class CakeResponse {
  * Holds all the cache directives that will be converted
  * into headers when sending the request
  *
- * @var string
+ * @var array
  */
 	protected $_cacheDirectives = array();
 
@@ -672,8 +672,9 @@ class CakeResponse {
  *
  *        For more on HTTP status codes see: http://www.w3.org/Protocols/rfc2616/rfc2616-sec6.html#sec6.1
  *
- * @return mixed associative array of the HTTP codes as keys, and the message
- *    strings as values, or null of the given $code does not exist.
+ * @return array|null|true associative array of the HTTP codes as keys, and the message
+ *    strings as values, or null of the given $code does not exist. `true` if `$code` is
+ *    an array of valid codes.
  * @throws CakeException If an attempt is made to add an invalid status code
  */
 	public function httpCodes($code = null) {
@@ -717,8 +718,8 @@ class CakeResponse {
  *
  * e.g `type(array('jpg' => 'text/plain'));`
  *
- * @param string $contentType Content type key.
- * @return mixed current content type or false if supplied an invalid content type
+ * @param array|string|null $contentType Content type key.
+ * @return string|false current content type or false if supplied an invalid content type
  */
 	public function type($contentType = null) {
 		if ($contentType === null) {
@@ -854,7 +855,7 @@ class CakeResponse {
 		}
 
 		$this->maxAge($time);
-		if (!$time) {
+		if ((int)$time === 0) {
 			$this->_setCacheControl();
 		}
 		return (bool)$public;
@@ -1160,7 +1161,11 @@ class CakeResponse {
  * @return bool whether the response was marked as not modified or not.
  */
 	public function checkNotModified(CakeRequest $request) {
-		$etags = preg_split('/\s*,\s*/', $request->header('If-None-Match'), null, PREG_SPLIT_NO_EMPTY);
+		$ifNoneMatchHeader = $request->header('If-None-Match');
+		$etags = array();
+		if (is_string($ifNoneMatchHeader)) {
+			$etags = preg_split('/\s*,\s*/', $ifNoneMatchHeader, null, PREG_SPLIT_NO_EMPTY);
+		}
 		$modifiedSince = $request->header('If-Modified-Since');
 		$checks = array();
 		if ($responseTag = $this->etag()) {
@@ -1224,7 +1229,7 @@ class CakeResponse {
  *
  * `$this->cookie((array) $options)`
  *
- * @param array $options Either null to get all cookies, string for a specific cookie
+ * @param array|string $options Either null to get all cookies, string for a specific cookie
  *  or array to set cookie.
  * @return mixed
  */
@@ -1312,11 +1317,7 @@ class CakeResponse {
 				$result[] = array('preg' => '@.@', 'original' => '*');
 				continue;
 			}
-
-			$original = $preg = $domain;
-			if (strpos($domain, '://') === false) {
-				$preg = ($requestIsSSL ? 'https://' : 'http://') . $domain;
-			}
+			$original = $domain;
 			$preg = '@' . str_replace('*', '.*', $domain) . '@';
 			$result[] = compact('original', 'preg');
 		}
@@ -1464,7 +1465,7 @@ class CakeResponse {
 		$file->open('rb');
 
 		$end = $start = false;
-		if ($range) {
+		if ($range && is_array($range)) {
 			list($start, $end) = $range;
 		}
 		if ($start !== false) {