Add undocumented properties (#12717)

See https://book.cakephp.org/2.0/en/controllers/request-response.html#accessing-request-parameters and https://api.cakephp.org/2.10/source-class-UpgradeShell.html#345-403

* Initialize $params to null
* Document more magic properties, trigger deprecated notices
* Use $controller->request->params instead $controller->params
* Remove unused variable
* Improve documentation, add type checks.
* It seems like $this->uses can also be of type false; however, parameter
$array of array_unshift() does only seem to accept array.
* Declare undeclared property
* Add extra type checks
* Adjust type check
* Improve documentation, initiate uninitialized variables.
* Improve documentation, reset variable

lib/Cake/Controller/Component/RequestHandlerComponent.php

@@ -72,6 +72,13 @@ class RequestHandlerComponent extends Component {
  */
 	public $ext = null;
 
+/**
+ * Array of parameters parsed from the URL.
+ *
+ * @var array|null
+ */
+	public $params = null;
+
 /**
  * The template to use when rendering the given content type.
  *
@@ -132,7 +139,7 @@ class RequestHandlerComponent extends Component {
 		if (empty($this->ext) || $this->ext === 'html') {
 			$this->_setExtension();
 		}
-		$this->params = $controller->params;
+		$this->params = $controller->request->params;
 		if (!empty($this->settings['viewClassMap'])) {
 			$this->viewClassMap($this->settings['viewClassMap']);
 		}

lib/Cake/Controller/Controller.php

@@ -48,11 +48,18 @@ App::uses('CakeEventManager', 'Event');
  * @property      AuthComponent $Auth
  * @property      CookieComponent $Cookie
  * @property      EmailComponent $Email
+ * @property      FlashComponent $Flash
  * @property      PaginatorComponent $Paginator
  * @property      RequestHandlerComponent $RequestHandler
  * @property      SecurityComponent $Security
  * @property      SessionComponent $Session
- * @property      FlashComponent $Flash
+ * @property      string $action  The action handling the current request. Deprecated, use CakeRequest::$action instead.
+ * @property      string $base    Base URL path. Deprecated, use CakeRequest::$base instead.
+ * @property      array $data     POST data. Deprecated, use CakeRequest::$data instead.
+ * @property      string $here    The full address to the current request. Deprecated, use CakeRequest::$here instead.
+ * @property      array $paginate Pagination settings.
+ * @property      array $params   Array of parameters parsed from the URL. Deprecated, use CakeRequest::$params instead.
+ * @property      string $webroot Webroot path segment for the request.
  * @link          https://book.cakephp.org/2.0/en/controllers.html
  */
 class Controller extends CakeObject implements CakeEventListener {
@@ -80,7 +87,7 @@ class Controller extends CakeObject implements CakeEventListener {
  *
  * The default value is `true`.
  *
- * @var mixed
+ * @var bool|array
  * @link https://book.cakephp.org/2.0/en/controllers.html#components-helpers-and-uses
  */
 	public $uses = true;
@@ -153,9 +160,9 @@ class Controller extends CakeObject implements CakeEventListener {
 /**
  * The name of the layout file to render the view inside of. The name specified
  * is the filename of the layout in /app/View/Layouts without the .ctp
- * extension.
+ * extension. If `false` then no layout is rendered.
  *
- * @var string
+ * @var string|bool
  */
 	public $layout = 'default';
 
@@ -287,8 +294,9 @@ class Controller extends CakeObject implements CakeEventListener {
 
 /**
  * Holds any validation errors produced by the last call of the validateErrors() method.
+ * Contains `false` if no validation errors happened.
  *
- * @var array
+ * @var array|bool
  */
 	public $validationErrors = null;
 
@@ -573,7 +581,7 @@ class Controller extends CakeObject implements CakeEventListener {
 		if ($this->uses === true) {
 			$this->uses = array($pluginDot . $this->modelClass);
 		}
-		if (isset($appVars['uses']) && $appVars['uses'] === $this->uses) {
+		if (is_array($this->uses) && isset($appVars['uses']) && $appVars['uses'] === $this->uses) {
 			array_unshift($this->uses, $pluginDot . $this->modelClass);
 		}
 		if ($pluginController) {
@@ -598,10 +606,7 @@ class Controller extends CakeObject implements CakeEventListener {
  * @return void
  */
 	protected function _mergeUses($merge) {
-		if (!isset($merge['uses'])) {
-			return;
-		}
-		if ($merge['uses'] === true) {
+		if (!isset($merge['uses']) || $merge['uses'] === true || !is_array($this->uses)) {
 			return;
 		}
 		$this->uses = array_merge(
@@ -838,7 +843,7 @@ class Controller extends CakeObject implements CakeEventListener {
  * Saves a variable for use inside a view template.
  *
  * @param string|array $one A string or an array of data.
- * @param string|array $two Value in case $one is a string (which then works as the key).
+ * @param mixed $two Value in case $one is a string (which then works as the key).
  *   Unused if $one is an associative array, otherwise serves as the values to $one's keys.
  * @return void
  * @link https://book.cakephp.org/2.0/en/controllers.html#interacting-with-views
@@ -925,7 +930,7 @@ class Controller extends CakeObject implements CakeEventListener {
 /**
  * Instantiates the correct view class, hands it its data, and uses it to render the view output.
  *
- * @param string $view View to use for rendering
+ * @param bool|string $view View to use for rendering
  * @param string $layout Layout to use
  * @return CakeResponse A response object containing the rendered view.
  * @triggers Controller.beforeRender $this
@@ -1018,7 +1023,7 @@ class Controller extends CakeObject implements CakeEventListener {
 	}
 
 /**
- * Converts POST'ed form data to a model conditions array. 
+ * Converts POST'ed form data to a model conditions array.
  *
  * If combined with SecurityComponent these conditions could be suitable
  * for use in a Model::find() call. Without SecurityComponent this method

lib/Cake/Network/CakeRequest.php

@@ -25,6 +25,11 @@ App::uses('Hash', 'Utility');
  *
  * `$request['controller']` or `$request->controller`.
  *
+ * @property string $plugin     The plugin handling the request. Will be `null` when there is no plugin.
+ * @property string $controller The controller handling the current request.
+ * @property string $action     The action handling the current request.
+ * @property array $named       Array of named parameters parsed from the URL.
+ * @property array $pass        Array of passed arguments parsed from the URL.
  * @package       Cake.Network
  */
 class CakeRequest implements ArrayAccess {

lib/Cake/View/View.php

@@ -455,7 +455,7 @@ class View extends CakeObject {
  * a plugin view/layout can be used instead of the app ones. If the chosen plugin is not found
  * the view will be located along the regular view path cascade.
  *
- * @param string $view Name of view file to use
+ * @param false|string $view Name of view file to use.
  * @param string $layout Layout to use.
  * @return string|null Rendered content or null if content already rendered and returned earlier.
  * @triggers View.beforeRender $this, array($viewFileName)

lib/Cake/basics.php

@@ -135,7 +135,7 @@ if (!function_exists('stackTrace')) {
  * - `start` - The stack frame to start generating a trace from. Defaults to 1
  *
  * @param array $options Format for outputting stack trace
- * @return mixed Formatted stack trace
+ * @return void Outputs formatted stack trace.
  * @see Debugger::trace()
  */
 	function stackTrace(array $options = array()) {
@@ -167,17 +167,16 @@ if (!function_exists('sortByKey')) {
 		if (!is_array($array)) {
 			return null;
 		}
-
+		$sa = array();
 		foreach ($array as $key => $val) {
 			$sa[$key] = $val[$sortBy];
 		}
-
 		if ($order === 'asc') {
 			asort($sa, $type);
 		} else {
 			arsort($sa, $type);
 		}
-
+		$out = array();
 		foreach ($sa as $key => $val) {
 			$out[] = $array[$key];
 		}
@@ -194,9 +193,9 @@ if (!function_exists('h')) {
  * @param string|array|object $text Text to wrap through htmlspecialchars. Also works with arrays, and objects.
  *    Arrays will be mapped and have all their elements escaped. Objects will be string cast if they
  *    implement a `__toString` method. Otherwise the class name will be used.
- * @param bool $double Encode existing html entities
+ * @param bool|string $double Boolean - encode existing html entities. String - character set to use when escaping.
  * @param string $charset Character set to use when escaping. Defaults to config value in 'App.encoding' or 'UTF-8'
- * @return string|array|object Wrapped text, Wrapped Array or Wrapped Object
+ * @return string|array|bool|object Wrapped text, Wrapped Array or Wrapped Object.
  * @link https://book.cakephp.org/2.0/en/core-libraries/global-constants-and-functions.html#h
  */
 	function h($text, $double = true, $charset = null) {
@@ -227,6 +226,7 @@ if (!function_exists('h')) {
 		}
 		if (is_string($double)) {
 			$charset = $double;
+			$double = true;
 		}
 		return htmlspecialchars($text, ENT_QUOTES, ($charset) ? $charset : $defaultCharset, $double);
 	}
@@ -431,7 +431,7 @@ if (!function_exists('cache')) {
 		if (!is_numeric($expires)) {
 			$expires = strtotime($expires, $now);
 		}
-
+		$filename = '';
 		switch (strtolower($target)) {
 			case 'cache':
 				$filename = CACHE . $path;
@@ -484,7 +484,7 @@ if (!function_exists('clearCache')) {
  *   all files in app/tmp/cache/views will be deleted
  * @param string $type Directory in tmp/cache defaults to view directory
  * @param string $ext The file extension you are deleting
- * @return true if files found and deleted false otherwise
+ * @return bool `true` if files found and deleted, `false` otherwise.
  */
 	function clearCache($params = null, $type = 'views', $ext = '.php') {
 		if (is_string($params) || $params === null) {
@@ -551,8 +551,8 @@ if (!function_exists('stripslashes_deep')) {
 /**
  * Recursively strips slashes from all values in an array
  *
- * @param array $values Array of values to strip slashes
- * @return mixed What is returned from calling stripslashes
+ * @param array|string $values Array of values or a string to strip slashes.
+ * @return array|string What is returned from calling stripslashes.
  * @link https://book.cakephp.org/2.0/en/core-libraries/global-constants-and-functions.html#stripslashes_deep
  */
 	function stripslashes_deep($values) {
@@ -1025,14 +1025,13 @@ if (!function_exists('fileExistsInPath')) {
  * Searches include path for files.
  *
  * @param string $file File to look for
- * @return string Full path to file if exists, otherwise false
+ * @return bool|string Full path to file if exists, otherwise `false`.
  * @link https://book.cakephp.org/2.0/en/core-libraries/global-constants-and-functions.html#fileExistsInPath
  */
 	function fileExistsInPath($file) {
 		$paths = explode(PATH_SEPARATOR, ini_get('include_path'));
 		foreach ($paths as $path) {
 			$fullPath = $path . DS . $file;
-
 			if (file_exists($fullPath)) {
 				return $fullPath;
 			} elseif (file_exists($file)) {