docs: metadata mutators

Author: NathanPesneau

core/metadata-mutators.md

@@ -0,0 +1,60 @@
+# Metadata Mutators
+
+Metadata mutators allow a dynamic control over ressources and operations, by programmatically altering metadata before 
+they are exposed as endpoint. Providing a way to modify, add or remove operations, adjust serialization groups or pagination settings... 
+
+It also make it possible to customize built-in endpoints from a third party API, such as Sylius.
+
+
+## Resource Mutator
+
+Use the resource mutator to modify the entire resource metadata by adding the attribute and target ressource class as argument:
+
+```php
+<?php
+
+namespace App\Mutator;
+
+use ApiPlatform\Metadata\ResourceMutatorInterface;
+use App\Entity\Book;
+
+#[AsResourceMutator(resourceClass: Book::class)]
+final class BookResourceMutator implements ResourceMutatorInterface
+{
+    public function __invoke(ApiResource $resource): ApiResource
+    {
+        $operations = $resource->getOperations();
+        // remove delete operation on Book
+        $operations->remove('api_Book_delete');
+
+        return $resource->withOperations($operations);
+    }
+}
+```
+
+## Operation Mutator
+
+The operation mutator will modify a specific operation's metadata, by using the attribute and passing operation name:
+```php
+<?php
+
+namespace App\Mutator;
+
+use ApiPlatform\Metadata\AsOperationMutator;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Metadata\OperationMutatorInterface;
+
+#[AsOperationMutator(operationName: '_api_Book_get_collection')]
+final class BookOperationMutator implements OperationMutatorInterface
+{
+    public function __invoke(Operation $operation): Operation
+    {
+        $context = $operation->getNormalizationContext() ?? [];
+        // add another group to normalization group
+        $context['groups'][] = 'review:list:read';
+        
+        return $operation->withNormalizationContext($context);
+    }
+}
+```
+