Adds docblock comments and HTTP spec links for the new HTTP Exception classes (#2103)

framework/CHANGELOG.md

@@ -4,6 +4,15 @@ Yii Framework 2 Change Log
 2.0.0 beta under development
 ----------------------------
 
+- Enh #2103: Added docblock description and link to HTTP spec for BadRequestHttpException (danschmidt5189)
+- Enh #2103: Added docblock description and link to HTTP spec for UnauthorizedHttpException (danschmidt5189)
+- Enh #2103: Added docblock description and link to HTTP spec for ForbiddenHttpException (danschmidt5189)
+- Enh #2103: Added docblock description and link to HTTP spec for NotAcceptableHttpException (danschmidt5189)
+- Enh #2103: Added link to HTTP spec for ConflictHttpException (danschmidt5189)
+- Enh #2103: Added docblock description and link to HTTP spec for GoneHttpException (danschmidt5189)
+- Enh #2103: Added docblock description and link to HTTP spec for UnsupportedMediaTypeHttpException (danschmidt5189)
+- Enh #2103: Added docblock description and link to HTTP spec for TooManyRequestsHttpException (danschmidt5189)
+- Enh #2103: Renames AccessDeniedHttpException to ForbiddenHttpException (danschmidt5189)
 - Bug #1265: AssetController does not override 'js' and 'css' for compressed bundles (klimov-paul)
 - Bug #1326: The `visible` setting for `DetailView` doesn't work as expected (qiangxue)
 - Bug #1446: Logging while logs are processed causes infinite loop (qiangxue)

framework/collections/Map.php

+<?php
+
+namespace yii\collections;
+
+use yii\base\Object;
+use yii\base\ArrayAccessTrait;
+
+class Map extends Object implements IteratorAggregate, ArrayAccess, Countable
+{
+	use ArrayAccessTrait;
+
+	/**
+	 * @var array internal data storage. This is used by [[ArrayAccessTrait]] to
+	 * implement the IteratorAggregate, ArrayAccess, and Countable interfaces.
+	 */
+	protected $data;
+
+	/**
+	 * @var boolean whether this list is read-only
+	 */
+	private $_readOnly = false;
+
+	/**
+	 * Constructor.
+	 * Initializes the list with an array or an iterable object.
+	 * @param array $data the initial data. Default is null, meaning no initialization.
+	 * @param boolean $readOnly whether the list is read-only
+	 * @throws CException If data is not null and neither an array nor an iterator.
+	 */
+	public function __construct($data = null, $readOnly = false)
+	{
+		if ($data !== null) {
+			$this->copyFrom($data);
+		}
+		$this->setReadOnly($readOnly);
+	}
+
+	/**
+	 * @return boolean whether this map is read-only or not. Defaults to false.
+	 */
+	public function getReadOnly()
+	{
+		return $this->_readOnly;
+	}
+
+	/**
+	 * @param boolean $value whether this list is read-only or not
+	 */
+	public function setReadOnly($value)
+	{
+		$this->_readOnly = $value;
+	}
+}

framework/web/BadRequestHttpException.php

@@ -10,6 +10,12 @@ namespace yii\web;
 /**
  * BadRequestHttpException represents a "Bad Request" HTTP exception with status code 400.
  *
+ * Use this exception to represent a generic client error. In many cases, there
+ * may be an HTTP exception that more precisely describes the error. In that
+ * case, consider using the more precise exception to provide the user with
+ * additional information.
+ *
+ * @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/web/ConflictHttpException.php

@@ -8,8 +8,9 @@
 namespace yii\web;
 
 /**
- * ConflictHttpException represents a "Conflict" HTTP exception with status code 409.
+ * ConflictHttpException represents a "Conflict" HTTP exception with status code 409
  *
+ * @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10
  * @author Dan Schmidt <danschmidt5189@gmail.com>
  * @since 2.0
  */

framework/web/ForbiddenHttpException.php

@@ -10,6 +10,13 @@ namespace yii\web;
 /**
  * ForbiddenHttpException represents a "Forbidden" HTTP exception with status code 403.
  *
+ * Use this exception when a user has been authenticated but is not allowed to
+ * perform the requested action. If the user is not authenticated, consider
+ * using a 401 [[UnauthorizedHttpException]]. If you do not want to
+ * expose authorization information to the user, it is valid to respond with a
+ * 404 [[NotFoundHttpException]].
+ *
+ * @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4
  * @author Dan Schmidt <danschmidt5189@gmail.com>
  * @since 2.0
  */

framework/web/GoneHttpException.php

@@ -8,8 +8,14 @@
 namespace yii\web;
 
 /**
- * GoneHttpException represents a "Gone" HTTP exception with status code 410.
+ * GoneHttpException represents a "Gone" HTTP exception with status code 410
  *
+ * Throw a GoneHttpException when a user requests a resource that no longer exists
+ * at the requested url. For example, after a record is deleted, future requests
+ * for that record should return a 410 GoneHttpException instead of a 404
+ * [[NotFoundHttpException]].
+ *
+ * @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.11
  * @author Dan Schmidt <danschmidt5189@gmail.com>
  * @since 2.0
  */

framework/web/NotAcceptableHttpException.php

@@ -8,8 +8,13 @@
 namespace yii\web;
 
 /**
- * NotAcceptableHttpException represents a "Not Acceptable" HTTP exception with status code 406.
+ * NotAcceptableHttpException represents a "Not Acceptable" HTTP exception with status code 406
  *
+ * Use this exception when the client requests a Content-Type that your
+ * application cannot return. Note that, according to the HTTP 1.1 specification,
+ * you are not required to respond with this status code in this situation.
+ *
+ * @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7
  * @author Dan Schmidt <danschmidt5189@gmail.com>
  * @since 2.0
  */

framework/web/TooManyRequestsHttpException.php

@@ -8,8 +8,13 @@
 namespace yii\web;
 
 /**
- * TooManyRequestsHttpException represents a "Too Many Requests" HTTP exception with status code 429.
+ * TooManyRequestsHttpException represents a "Too Many Requests" HTTP exception with status code 429
  *
+ * Use this exception to indicate that a client has made too many requests in a
+ * given period of time. For example, you would throw this exception when
+ * 'throttling' an API user.
+ *
+ * @link http://tools.ietf.org/search/rfc6585#section-4
  * @author Dan Schmidt <danschmidt5189@gmail.com>
  * @since 2.0
  */

framework/web/UnauthorizedHttpException.php

@@ -8,8 +8,14 @@
 namespace yii\web;
 
 /**
- * UnauthorizedHttpException represents an "Unauthorized" HTTP exception with status code 401.
+ * UnauthorizedHttpException represents an "Unauthorized" HTTP exception with status code 401
  *
+ * Use this exception to indicate that a client needs to authenticate or login
+ * to perform the requested action. If the client is already authenticated and
+ * is simply not allowed to perform the action, consider using a 403
+ * [[ForbiddenHttpException]] or 404 [[NotFoundHttpException]] instead.
+ *
+ * @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2
  * @author Dan Schmidt <danschmidt5189@gmail.com>
  * @since 2.0
  */

framework/web/UnsupportedMediaTypeHttpException.php

@@ -8,8 +8,14 @@
 namespace yii\web;
 
 /**
- * UnsupportedMediaTypeHttpException represents an "Unsupported Media Type" HTTP exception with status code 415.
+ * UnsupportedMediaTypeHttpException represents an "Unsupported Media Type" HTTP exception with status code 415
  *
+ * Use this exception when the client sends data in a format that your
+ * application does not understand. For example, you would throw this exception
+ * if the client POSTs XML data to an action or controller that only accepts
+ * JSON.
+ *
+ * @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.16
  * @author Dan Schmidt <danschmidt5189@gmail.com>
  * @since 2.0
  */