Merge pull request #2106 from danschmidt5189/2103-rename-accessdeniedhttpexception

#2103 improves http exception consistency and adds new subclasses

docs/guide/authorization.md

@@ -248,7 +248,7 @@ public function editArticle($id)
     throw new NotFoundHttpException;
   }
   if (!\Yii::$app->user->checkAccess('edit_article', ['article' => $article])) {
-    throw new AccessDeniedHttpException;
+    throw new ForbiddenHttpException;
   }
   // ...
 }

extensions/debug/Module.php

@@ -10,7 +10,7 @@ namespace yii\debug;
 use Yii;
 use yii\base\Application;
 use yii\web\View;
-use yii\web\AccessDeniedHttpException;
+use yii\web\ForbiddenHttpException;
 
 /**
  * The Yii Debug Module provides the debug toolbar and debugger
@@ -80,7 +80,7 @@ class Module extends \yii\base\Module
 		} elseif ($action->id === 'toolbar') {
 			return false;
 		} else {
-			throw new AccessDeniedHttpException('You are not allowed to access this page.');
+			throw new ForbiddenHttpException('You are not allowed to access this page.');
 		}
 	}
 

extensions/gii/Module.php

@@ -8,7 +8,7 @@
 namespace yii\gii;
 
 use Yii;
-use yii\web\AccessDeniedHttpException;
+use yii\web\ForbiddenHttpException;
 
 /**
  * This is the main module class for the Gii module.
@@ -110,7 +110,7 @@ class Module extends \yii\base\Module
 		if ($this->checkAccess()) {
 			return parent::beforeAction($action);
 		} else {
-			throw new AccessDeniedHttpException('You are not allowed to access this page.');
+			throw new ForbiddenHttpException('You are not allowed to access this page.');
 		}
 	}
 

framework/CHANGELOG.md

@@ -4,6 +4,8 @@ Yii Framework 2 Change Log
 2.0.0 beta under development
 ----------------------------
 
+- Enh #2103: Adds docblock descriptions and links to HTTP specs for new HTTP exception classes (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/classes.php

@@ -196,7 +196,7 @@ return [
 	'yii\validators\ValidationAsset' => YII_PATH . '/validators/ValidationAsset.php',
 	'yii\validators\Validator' => YII_PATH . '/validators/Validator.php',
 	'yii\web\AccessControl' => YII_PATH . '/web/AccessControl.php',
-	'yii\web\AccessDeniedHttpException' => YII_PATH . '/web/AccessDeniedHttpException.php',
+	'yii\web\ForbiddenHttpException' => YII_PATH . '/web/ForbiddenHttpException.php',
 	'yii\web\AccessRule' => YII_PATH . '/web/AccessRule.php',
 	'yii\web\Application' => YII_PATH . '/web/Application.php',
 	'yii\web\AssetBundle' => YII_PATH . '/web/AssetBundle.php',

framework/web/AccessControl.php

@@ -130,14 +130,14 @@ class AccessControl extends ActionFilter
 	 * The default implementation will redirect the user to the login page if he is a guest;
 	 * if the user is already logged, a 403 HTTP exception will be thrown.
 	 * @param User $user the current user
-	 * @throws AccessDeniedHttpException if the user is already logged in.
+	 * @throws ForbiddenHttpException if the user is already logged in.
 	 */
 	protected function denyAccess($user)
 	{
 		if ($user->getIsGuest()) {
 			$user->loginRequired();
 		} else {
-			throw new AccessDeniedHttpException(Yii::t('yii', 'You are not allowed to perform this action.'));
+			throw new ForbiddenHttpException(Yii::t('yii', 'You are not allowed to perform this action.'));
 		}
 	}
 }

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,12 +8,13 @@
 namespace yii\web;
 
 /**
- * AccessDeniedHttpException represents an "Access Denied" HTTP exception with status code 403.
+ * ConflictHttpException represents a "Conflict" HTTP exception with status code 409
  *
- * @author Qiang Xue <qiang.xue@gmail.com>
+ * @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10
+ * @author Dan Schmidt <danschmidt5189@gmail.com>
  * @since 2.0
  */
-class AccessDeniedHttpException extends HttpException
+class ConflictHttpException extends HttpException
 {
 	/**
 	 * Constructor.
@@ -23,6 +24,6 @@ class AccessDeniedHttpException extends HttpException
 	 */
 	public function __construct($message = null, $code = 0, \Exception $previous = null)
 	{
-		parent::__construct(403, $message, $code, $previous);
+		parent::__construct(409, $message, $code, $previous);
 	}
 }

framework/web/ForbiddenHttpException.php

@@ -0,0 +1,35 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+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
+ */
+class ForbiddenHttpException extends HttpException
+{
+	/**
+	 * Constructor.
+	 * @param string $message error message
+	 * @param integer $code error code
+	 * @param \Exception $previous The previous exception used for the exception chaining.
+	 */
+	public function __construct($message = null, $code = 0, \Exception $previous = null)
+	{
+		parent::__construct(403, $message, $code, $previous);
+	}
+}

framework/web/GoneHttpException.php

@@ -0,0 +1,34 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\web;
+
+/**
+ * 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
+ */
+class GoneHttpException extends HttpException
+{
+	/**
+	 * Constructor.
+	 * @param string $message error message
+	 * @param integer $code error code
+	 * @param \Exception $previous The previous exception used for the exception chaining.
+	 */
+	public function __construct($message = null, $code = 0, \Exception $previous = null)
+	{
+		parent::__construct(410, $message, $code, $previous);
+	}
+}

framework/web/NotAcceptableHttpException.php

@@ -0,0 +1,33 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\web;
+
+/**
+ * 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
+ */
+class NotAcceptableHttpException extends HttpException
+{
+	/**
+	 * Constructor.
+	 * @param string $message error message
+	 * @param integer $code error code
+	 * @param \Exception $previous The previous exception used for the exception chaining.
+	 */
+	public function __construct($message = null, $code = 0, \Exception $previous = null)
+	{
+		parent::__construct(406, $message, $code, $previous);
+	}
+}

framework/web/TooManyRequestsHttpException.php

@@ -0,0 +1,33 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\web;
+
+/**
+ * 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
+ */
+class TooManyRequestsHttpException extends HttpException
+{
+	/**
+	 * Constructor.
+	 * @param string $message error message
+	 * @param integer $code error code
+	 * @param \Exception $previous The previous exception used for the exception chaining.
+	 */
+	public function __construct($message = null, $code = 0, \Exception $previous = null)
+	{
+		parent::__construct(429, $message, $code, $previous);
+	}
+}

framework/web/UnauthorizedHttpException.php

@@ -0,0 +1,34 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\web;
+
+/**
+ * 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
+ */
+class UnauthorizedHttpException extends HttpException
+{
+	/**
+	 * Constructor.
+	 * @param string $message error message
+	 * @param integer $code error code
+	 * @param \Exception $previous The previous exception used for the exception chaining.
+	 */
+	public function __construct($message = null, $code = 0, \Exception $previous = null)
+	{
+		parent::__construct(401, $message, $code, $previous);
+	}
+}

framework/web/UnsupportedMediaTypeHttpException.php

@@ -0,0 +1,34 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\web;
+
+/**
+ * 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
+ */
+class UnsupportedMediaTypeHttpException extends HttpException
+{
+	/**
+	 * Constructor.
+	 * @param string $message error message
+	 * @param integer $code error code
+	 * @param \Exception $previous The previous exception used for the exception chaining.
+	 */
+	public function __construct($message = null, $code = 0, \Exception $previous = null)
+	{
+		parent::__construct(415, $message, $code, $previous);
+	}
+}

framework/web/User.php

@@ -323,7 +323,7 @@ class User extends Component
 	 * Note that when [[loginUrl]] is set, calling this method will NOT terminate the application execution.
 	 *
 	 * @return Response the redirection response if [[loginUrl]] is set
-	 * @throws AccessDeniedHttpException the "Access Denied" HTTP exception if [[loginUrl]] is not set
+	 * @throws ForbiddenHttpException the "Access Denied" HTTP exception if [[loginUrl]] is not set
 	 */
 	public function loginRequired()
 	{
@@ -334,7 +334,7 @@ class User extends Component
 		if ($this->loginUrl !== null) {
 			return Yii::$app->getResponse()->redirect($this->loginUrl);
 		} else {
-			throw new AccessDeniedHttpException(Yii::t('yii', 'Login Required'));
+			throw new ForbiddenHttpException(Yii::t('yii', 'Login Required'));
 		}
 	}