Gating with custom message (#90)

Author: GautierDele

content/4.digging-deeper/3.gates.md

@@ -38,3 +38,44 @@ class UserResource extends Resource
     // ...
 }
 ```
+
+## Policy messages in gates
+
+To surface policy messages explaining authorization failures, first set the config `rest.gates.message.enabled` to `true`.
+Enabling this changes the `gates` payload shape returned by the `search` endpoint and may require frontend updates.
+
+In your policy, return an authorization `Response`:
+
+```php
+use App\Models\Post;
+use App\Models\User;
+use Illuminate\Auth\Access\Response;
+ 
+/**
+ * Determine if the given post can be updated by the user.
+ */
+public function update(User $user, Post $post): Response
+{
+    return $user->id === $post->user_id
+        ? Response::allow()
+        : Response::deny('You do not own this post.');
+}
+```
+
+This changes the `search` gates payload by adding a `message` and `allowed` keys:
+
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "gates": {
+        "authorized_to_update": {
+          "allowed": false,
+          "message": "You do not own this post."
+        }
+      }
+    }
+  ]
+}
+```