From 7fef8cf0cfd69e9ad8a0bbbe2382bf0e4ebdbae7 Mon Sep 17 00:00:00 2001
From: Daniel Schmidt <danschmidt5189@gmail.com>
Date: Wed, 22 Jan 2014 19:23:39 -0800
Subject: [PATCH] Adds docblock comments and HTTP spec links for the new HTTP Exception classes (#2103)
---
framework/CHANGELOG.md | 9 +++++++++
framework/collections/Map.php | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
framework/web/BadRequestHttpException.php | 6 ++++++
framework/web/ConflictHttpException.php | 3 ++-
framework/web/ForbiddenHttpException.php | 7 +++++++
framework/web/GoneHttpException.php | 8 +++++++-
framework/web/NotAcceptableHttpException.php | 7 ++++++-
framework/web/TooManyRequestsHttpException.php | 7 ++++++-
framework/web/UnauthorizedHttpException.php | 8 +++++++-
framework/web/UnsupportedMediaTypeHttpException.php | 8 +++++++-
10 files changed, 110 insertions(+), 6 deletions(-)
create mode 100644 framework/collections/Map.php
diff --git a/framework/CHANGELOG.md b/framework/CHANGELOG.md
index 69362ca..e11f557 100644
--- a/framework/CHANGELOG.md
+++ b/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)
diff --git a/framework/collections/Map.php b/framework/collections/Map.php
new file mode 100644
index 0000000..d5ad270
--- /dev/null
+++ b/framework/collections/Map.php
@@ -0,0 +1,53 @@
+<?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;
+ }
+}
diff --git a/framework/web/BadRequestHttpException.php b/framework/web/BadRequestHttpException.php
index 3a6cfbb..6e596da 100644
--- a/framework/web/BadRequestHttpException.php
+++ b/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
*/
diff --git a/framework/web/ConflictHttpException.php b/framework/web/ConflictHttpException.php
index 49e5519..6fa3f57 100644
--- a/framework/web/ConflictHttpException.php
+++ b/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
*/
diff --git a/framework/web/ForbiddenHttpException.php b/framework/web/ForbiddenHttpException.php
index c05511e..e96c225 100644
--- a/framework/web/ForbiddenHttpException.php
+++ b/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
*/
diff --git a/framework/web/GoneHttpException.php b/framework/web/GoneHttpException.php
index 559374a..b78aa01 100644
--- a/framework/web/GoneHttpException.php
+++ b/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
*/
diff --git a/framework/web/NotAcceptableHttpException.php b/framework/web/NotAcceptableHttpException.php
index 4da942b..5a749c9 100644
--- a/framework/web/NotAcceptableHttpException.php
+++ b/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
*/
diff --git a/framework/web/TooManyRequestsHttpException.php b/framework/web/TooManyRequestsHttpException.php
index cdf9c09..b5eb889 100644
--- a/framework/web/TooManyRequestsHttpException.php
+++ b/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
*/
diff --git a/framework/web/UnauthorizedHttpException.php b/framework/web/UnauthorizedHttpException.php
index 50d86dc..0bea209 100644
--- a/framework/web/UnauthorizedHttpException.php
+++ b/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
*/
diff --git a/framework/web/UnsupportedMediaTypeHttpException.php b/framework/web/UnsupportedMediaTypeHttpException.php
index 5038be2..715117e 100644
--- a/framework/web/UnsupportedMediaTypeHttpException.php
+++ b/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
*/
--
libgit2 0.27.1