Docs/automatic policy (#13)

* doc: add automatic policy detection documentation

* doc: add automatic policy detection documentation

* doc: doc review

* doc: typo

* Apply suggestions from code review

Co-authored-by: Kévin Dunglas <kevin@dunglas.fr>

---------

Co-authored-by: Antoine Bluchet <soyuka@users.noreply.github.com>
Co-authored-by: Kévin Dunglas <kevin@dunglas.fr>

Author: 3 people

laravel/index.md

@@ -287,8 +287,8 @@ Let's replace our author column by a relation to a new `author` table:
     }
 ```
 
-By doing so, API Platform will automatically handle links to that relation using your prefered format (JSON:API, JSON-LD etc) 
-and when we request a Book we obtain: 
+By doing so, API Platform will automatically handle links to that relation using your prefered format (JSON:API, JSON-LD etc)
+and when we request a Book we obtain:
 
 ```json
 {
@@ -649,29 +649,7 @@ To protect an operation and ensure that only authorized users can access it, sta
 php artisan make:policy BookPolicy --model=Book
 ```
 
-If the standard Laravel conventions are followed, the Policy class is autodetected and used automatically.
-Otherwise, you can use the `policy` property on an operation attribute to explicitly enforce a policy:
-
-```patch
- // app/Models/Book.php
- namespace App\Models;
-
- use ApiPlatform\Metadata\ApiResource;
-+use ApiPlatform\Metadata\Patch;
- use Illuminate\Database\Eloquent\Model;
-
--#[ApiResource]
- #[ApiResource(
-+    operations: [
-+       new Patch(
-+            policy: 'update',
-+       ),
-+    ],
- )]
- class Book extends Model
- {
- }
-```
+Laravel will automatically detect your new policy and use it when manipulating a Book.
 
 Read the detailed documentation about using [Laravel gates and policies with API Platform](security.md).
 

laravel/security.md

@@ -1,26 +1,78 @@
 # Security
 
-API platform is compatible with Laravel [authorization](https://laravel.com/docs/authorization) mechanism. Once a gate is defined, you can specify the policy to use within an operation:
+## Policies
+
+API platform is compatible with Laravel [authorization](https://laravel.com/docs/authorization) mechanism. Once a gate is defined, API Platform will automatically detect your policy.
 
 ```php
 // app/Models/Book.php 
 
 use ApiPlatform\Metadata\Patch;
 
-#[Patch(policy: 'update')]
+#[Patch]
 class Book extends Model
 {
 }
 ```
 
+API Platform will detect the operation and map it to a specific method in your policy according to the rules defined in this table:
+
+| Operation      | Policy                                                     |
+|----------------|------------------------------------------------------------|
+| GET collection | `viewAny`                                                  |
+| GET            | `view`                                                     |
+| POST           | `create`                                                   |
+| PATCH          | `update`                                                   |
+| DELETE         | `delete`                                                   |
+| PUT            | `update` or `create` if the resource doesn't already exist |
+
+If your policy methods do not match Laravel's conventions, you can always use the `policy` property on an operation attribute to enforce this policy:
+```php
+// app/Models/Book.php
+namespace App\Models;
+
+ use ApiPlatform\Metadata\ApiResource;
++use ApiPlatform\Metadata\Patch;
+ use Illuminate\Database\Eloquent\Model;
+
+-#[ApiResource]
+ #[ApiResource(
+     paginationItemsPerPage: 10,
++    operations: [
++       new Patch(
++            policy: 'myCustomPolicy',
++       ),
++    ],
+)]
+ class Book extends Model
+ {
+ }
+```
+
+You also can link a model to a policy:
+
+```php
+use App\Models\Book;
+use App\Tests\Book\BookPolicy;
+use Illuminate\Support\Facades\Gate;
+
+Gate::guessPolicyNamesUsing(function (string $modelClass): ?string {
+    return Book::class === $modelClass ?
+        BookPolicy::class :
+        null;
+});
+```
+
+## Authentication
+
 Usually, you will use [Sanctum](https://laravel.com/docs/sanctum) and add a middleware on secured routes:
 
 ```php
 // app/Models/Book.php 
 
 use ApiPlatform\Metadata\Patch;
 
-#[Patch(middleware: 'auth:sanctum', policy: 'update')]
+#[Patch(middleware: 'auth:sanctum')]
 class Book extends Model
 {
 }