From 574cfdd9f67f8243e1b83a2a419512a356dfdb51 Mon Sep 17 00:00:00 2001 From: Tim MacDonald Date: Thu, 14 Jul 2022 10:20:22 +1000 Subject: [PATCH 1/6] Document customising gate status codes --- authorization.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/authorization.md b/authorization.md index 9e432a2895..92c8a3f08a 100644 --- a/authorization.md +++ b/authorization.md @@ -195,6 +195,23 @@ When using the `Gate::authorize` method, which throws an `AuthorizationException // The action is authorized... + +#### Customizing The Response Status + +When an action is denied via a Gate, a `403 Forbidden` response is returned, however it can be useful to instead return an alternative HTTP status. + +You may customize the HTTP status returned for a failed authorization check by using the `denyWithStatus` static constructor on `Illuminate\Auth\Access\Response`: + + return $user->isAdmin + ? Response::allow() + : Response::denyWithStatus(404); + +Because hiding resources via a `404 Not Found` response is such a common pattern for web applications, we have also added a nice named helper: + + return $user->isAdmin + ? Response::allow() + : Response::denyAsNotFound(); + ### Intercepting Gate Checks From 6f730d0e47ba7921ab6fef50b9e7e05d2ccfd9d3 Mon Sep 17 00:00:00 2001 From: Tim MacDonald Date: Thu, 14 Jul 2022 10:26:01 +1000 Subject: [PATCH 2/6] Document customising policy status codes --- authorization.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/authorization.md b/authorization.md index 92c8a3f08a..c855969877 100644 --- a/authorization.md +++ b/authorization.md @@ -406,6 +406,23 @@ When using the `Gate::authorize` method, which throws an `AuthorizationException // The action is authorized... + +#### Customizing The Response Status + +When an action is denied via a policy method, a `403 Forbidden` response is returned, however it can be useful to instead return an alternative HTTP status. + +You may customize the HTTP status returned for a failed authorization check by using the `denyWithStatus` static constructor on `Illuminate\Auth\Access\Response`: + + return $user->id === $post->user_id + ? Response::allow() + : Response::denyWithStatus(404); + +Because hiding resources via a `404 Not Found` response is such a common pattern for web applications, we have also added a nice named helper: + + return $user->id === $post->user_id + ? Response::allow() + : Response::denyAsNotFound(); + ### Methods Without Models From 638a7fa2e06b4ad810813e9386aa5ddd3b7d8050 Mon Sep 17 00:00:00 2001 From: Tim MacDonald Date: Thu, 14 Jul 2022 10:31:56 +1000 Subject: [PATCH 3/6] Provide better context --- authorization.md | 64 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 52 insertions(+), 12 deletions(-) diff --git a/authorization.md b/authorization.md index c855969877..f0e168faf9 100644 --- a/authorization.md +++ b/authorization.md @@ -202,15 +202,27 @@ When an action is denied via a Gate, a `403 Forbidden` response is returned, how You may customize the HTTP status returned for a failed authorization check by using the `denyWithStatus` static constructor on `Illuminate\Auth\Access\Response`: - return $user->isAdmin - ? Response::allow() - : Response::denyWithStatus(404); + 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 Not Found` response is such a common pattern for web applications, we have also added a nice named helper: - return $user->isAdmin - ? Response::allow() - : Response::denyAsNotFound(); + 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(); + }); ### Intercepting Gate Checks @@ -413,15 +425,43 @@ When an action is denied via a policy method, a `403 Forbidden` response is retu You may customize the HTTP status returned for a failed authorization check by using the `denyWithStatus` static constructor on `Illuminate\Auth\Access\Response`: - return $user->id === $post->user_id - ? Response::allow() - : Response::denyWithStatus(404); + 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 Not Found` response is such a common pattern for web applications, we have also added a nice named helper: - return $user->id === $post->user_id - ? Response::allow() - : Response::denyAsNotFound(); + 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(); + } ### Methods Without Models From 270a06ba972645b9368935e2a3c778119f44b9cf Mon Sep 17 00:00:00 2001 From: Tim MacDonald Date: Thu, 14 Jul 2022 10:43:44 +1000 Subject: [PATCH 4/6] clarify HTTP response --- authorization.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/authorization.md b/authorization.md index f0e168faf9..47df3e1b08 100644 --- a/authorization.md +++ b/authorization.md @@ -196,9 +196,9 @@ When using the `Gate::authorize` method, which throws an `AuthorizationException // The action is authorized... -#### Customizing The Response Status +#### Customizing The HTTP Response Status -When an action is denied via a Gate, a `403 Forbidden` response is returned, however it can be useful to instead return an alternative HTTP status. +When an action is denied via a Gate, a `403 Forbidden` HTTP response is returned, however it can be useful to instead return an alternative HTTP status. You may customize the HTTP status returned for a failed authorization check by using the `denyWithStatus` static constructor on `Illuminate\Auth\Access\Response`: @@ -419,9 +419,9 @@ When using the `Gate::authorize` method, which throws an `AuthorizationException // The action is authorized... -#### Customizing The Response Status +#### Customizing The HTTP Response Status -When an action is denied via a policy method, a `403 Forbidden` response is returned, however it can be useful to instead return an alternative HTTP status. +When an action is denied via a policy method, a `403 Forbidden` HTTP response is returned, however it can be useful to instead return an alternative HTTP status. You may customize the HTTP status returned for a failed authorization check by using the `denyWithStatus` static constructor on `Illuminate\Auth\Access\Response`: From 9725571533d784cfe3146dcb61a81f15e319f10f Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Thu, 14 Jul 2022 09:06:16 -0500 Subject: [PATCH 5/6] Update authorization.md --- authorization.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/authorization.md b/authorization.md index 47df3e1b08..ed35719984 100644 --- a/authorization.md +++ b/authorization.md @@ -198,9 +198,7 @@ When using the `Gate::authorize` method, which throws an `AuthorizationException #### Customizing The HTTP Response Status -When an action is denied via a Gate, a `403 Forbidden` HTTP response is returned, however it can be useful to instead return an alternative HTTP status. - -You may customize the HTTP status returned for a failed authorization check by using the `denyWithStatus` static constructor on `Illuminate\Auth\Access\Response`: +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; @@ -212,7 +210,7 @@ You may customize the HTTP status returned for a failed authorization check by u : Response::denyWithStatus(404); }); -Because hiding resources via a `404 Not Found` response is such a common pattern for web applications, we have also added a nice named helper: +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; From a3303d9e28ba8d563042fb1084f4e9507e2c6ccc Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Thu, 14 Jul 2022 09:07:20 -0500 Subject: [PATCH 6/6] Update authorization.md --- authorization.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/authorization.md b/authorization.md index ed35719984..2a5f2dbbd0 100644 --- a/authorization.md +++ b/authorization.md @@ -419,9 +419,7 @@ When using the `Gate::authorize` method, which throws an `AuthorizationException #### Customizing The HTTP Response Status -When an action is denied via a policy method, a `403 Forbidden` HTTP response is returned, however it can be useful to instead return an alternative HTTP status. - -You may customize the HTTP status returned for a failed authorization check by using the `denyWithStatus` static constructor on `Illuminate\Auth\Access\Response`: +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; @@ -441,7 +439,7 @@ You may customize the HTTP status returned for a failed authorization check by u : Response::denyWithStatus(404); } -Because hiding resources via a `404 Not Found` response is such a common pattern for web applications, we have also added a nice named helper: +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;