From 7fef8cf0cfd69e9ad8a0bbbe2382bf0e4ebdbae7 Mon Sep 17 00:00:00 2001 From: Daniel Schmidt 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 ++- .../web/TooManyRequestsHttpException.php | 7 ++- framework/web/UnauthorizedHttpException.php | 8 ++- .../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 69362caa0e..e11f5577e5 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 0000000000..d5ad27003a --- /dev/null +++ b/framework/collections/Map.php @@ -0,0 +1,53 @@ +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 3a6cfbb641..6e596dab1a 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 * @since 2.0 */ diff --git a/framework/web/ConflictHttpException.php b/framework/web/ConflictHttpException.php index 49e551910a..6fa3f57bab 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 * @since 2.0 */ diff --git a/framework/web/ForbiddenHttpException.php b/framework/web/ForbiddenHttpException.php index c05511e8b9..e96c225293 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 * @since 2.0 */ diff --git a/framework/web/GoneHttpException.php b/framework/web/GoneHttpException.php index 559374a4db..b78aa01b59 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 * @since 2.0 */ diff --git a/framework/web/NotAcceptableHttpException.php b/framework/web/NotAcceptableHttpException.php index 4da942b9d1..5a749c91e8 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 * @since 2.0 */ diff --git a/framework/web/TooManyRequestsHttpException.php b/framework/web/TooManyRequestsHttpException.php index cdf9c097fd..b5eb8898a5 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 * @since 2.0 */ diff --git a/framework/web/UnauthorizedHttpException.php b/framework/web/UnauthorizedHttpException.php index 50d86dca9b..0bea209046 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 * @since 2.0 */ diff --git a/framework/web/UnsupportedMediaTypeHttpException.php b/framework/web/UnsupportedMediaTypeHttpException.php index 5038be2a7c..715117e0ed 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 * @since 2.0 */