[9.x] Authorization HTTP status customisation

authorization.md

@@ -195,6 +195,33 @@ When using the `Gate::authorize` method, which throws an `AuthorizationException
 
  // The action is authorized...
 
+<a name="customising-gate-response-status"></a>
+#### Customizing The HTTP Response Status
+
+When an action is denied via a Gate, a `403` HTTP response is returned; however, it can sometimes be useful to return an alternative HTTP status code. You may customize the HTTP status code returned for a failed authorization check using the `denyWithStatus` static constructor on the `Illuminate\Auth\Access\Response` class:
+
+ use App\Models\User;
+ use Illuminate\Auth\Access\Response;
+ use Illuminate\Support\Facades\Gate;
+
+ Gate::define('edit-settings', function (User $user) {
+ return $user->isAdmin
+ ? Response::allow()
+ : Response::denyWithStatus(404);
+ });
+
+Because hiding resources via a `404` response is such a common pattern for web applications, the `denyAsNotFound` method is offered for convenience:
+
+ use App\Models\User;
+ use Illuminate\Auth\Access\Response;
+ use Illuminate\Support\Facades\Gate;
+
+ Gate::define('edit-settings', function (User $user) {
+ return $user->isAdmin
+ ? Response::allow()
+ : Response::denyAsNotFound();
+ });
+
 <a name="intercepting-gate-checks"></a>
 ### Intercepting Gate Checks
 
@@ -389,6 +416,49 @@ When using the `Gate::authorize` method, which throws an `AuthorizationException
 
  // The action is authorized...
 
+<a name="customising-policy-response-status"></a>
+#### Customizing The HTTP Response Status
+
+When an action is denied via a policy method, a `403` HTTP response is returned; however, it can sometimes be useful to return an alternative HTTP status code. You may customize the HTTP status code returned for a failed authorization check using the `denyWithStatus` static constructor on the `Illuminate\Auth\Access\Response` class:
+
+ use App\Models\Post;
+ use App\Models\User;
+ use Illuminate\Auth\Access\Response;
+
+ /**
+ * Determine if the given post can be updated by the user.
+ *
+ * @param \App\Models\User $user
+ * @param \App\Models\Post $post
+ * @return \Illuminate\Auth\Access\Response
+ */
+ public function update(User $user, Post $post)
+ {
+ return $user->id === $post->user_id
+ ? Response::allow()
+ : Response::denyWithStatus(404);
+ }
+
+Because hiding resources via a `404` response is such a common pattern for web applications, the `denyAsNotFound` method is offered for convenience:
+
+ use App\Models\Post;
+ use App\Models\User;
+ use Illuminate\Auth\Access\Response;
+
+ /**
+ * Determine if the given post can be updated by the user.
+ *
+ * @param \App\Models\User $user
+ * @param \App\Models\Post $post
+ * @return \Illuminate\Auth\Access\Response
+ */
+ public function update(User $user, Post $post)
+ {
+ return $user->id === $post->user_id
+ ? Response::allow()
+ : Response::denyAsNotFound();
+ }
+
 <a name="methods-without-models"></a>
 ### Methods Without Models