feat: add built in state provider decoration doc

Author: hemel160238

core/state-providers.md

@@ -17,7 +17,7 @@ In the following examples we will create custom state providers for an entity cl
 Note, that if your entity is not Doctrine-related, you need to flag the identifier property by using
 `#[ApiProperty(identifier: true)` for things to work properly (see also [Entity Identifier Case](serialization.md#entity-identifier-case)).
 
-## State Provider
+## Creating a Custom State Provider
 
 If the [Symfony MakerBundle](https://symfony.com/doc/current/bundles/SymfonyMakerBundle) is installed in your project,
 you can use the following command to generate a custom state provider easily:
@@ -124,3 +124,65 @@ use App\State\BlogPostProvider;
 #[ApiResource(provider: BlogPostProvider::class)]
 class BlogPost {}
 ```
+
+## Hooking into the Built-In State Provider
+
+If you want to execute custom business logic before or after retrieving data, this can be achieved by [decorating](https://symfony.com/doc/current/service_container/service_decoration.html) the built-in state providers or using [composition](https://en.wikipedia.org/wiki/Object_composition).
+
+The next example uses a [DTO](https://api-platform.com/docs/core/dto/#using-data-transfer-objects-dtos) to change the presentation for data originally retrieved by the default state provider.
+
+```php
+<?php
+
+namespace App\State;
+
+use App\Dto\AnotherRepresentation;
+use App\Model\Book;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\State\ProviderInterface;
+
+final class BookRepresentationProvider implements ProviderInterface
+{
+    public function __construct(private ProviderInterface $itemProvider)
+    {
+    }
+    
+    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
+    {
+        $book = $this->itemProvider->provide($operation, $uriVariables, $context);
+        
+        return new AnotherRepresentation(
+            // Add DTO constructor params here.
+            // $book->getTitle(),
+        );
+    }
+}
+```
+
+Even with service autowiring and autoconfiguration enabled, you must still configure the decoration:
+
+```yaml
+# api/config/services.yaml
+services:
+    # ...
+    App\State\BookRepresentationProvider:
+        bind:
+            $itemProvider: '@api_platform.doctrine.orm.state.item_provider'
+        # Uncomment only if autoconfiguration is disabled
+        #tags: [ 'api_platform.state_provider' ]
+```
+
+And configure that you want to use this provider on the Book resource:
+
+```php
+<?php
+
+namespace App\Entity;
+
+use ApiPlatform\Metadata\Get;
+use App\Dto\AnotherRepresentation;
+use App\State\BookRepresentationProvider;
+
+#[Get(output: AnotherRepresentation::class, provider: BookRepresentationProvider::class)]
+class Book {}
+```