feat(metadata) Customize Resource & operations

src/Metadata/AsOperationMutator.php

@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Metadata;
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final class AsOperationMutator
+{
+    public function __construct(
+        public readonly string $operationName,
+    ) {
+    }
+}

src/Metadata/AsResourceMutator.php

@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Metadata;
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final class AsResourceMutator
+{
+    /**
+     * @param class-string $resourceClass
+     */
+    public function __construct(
+        public readonly string $resourceClass,
+    ) {
+    }
+}

src/Metadata/Mutator/ResourceMutatorCollection.php

@@ -0,0 +1,36 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Metadata\Mutator;
+
+use Psr\Container\ContainerInterface;
+
+final class ResourceMutatorCollection implements ContainerInterface
+{
+    private array $mutators;
+
+    public function addMutator(string $resourceClass, object $mutator): void
+    {
+        $this->mutators[$resourceClass][] = $mutator;
+    }
+
+    public function get(string $id): array
+    {
+        return $this->mutators[$id] ?? [];
+    }
+
+    public function has(string $id): bool
+    {
+        return isset($this->mutators[$id]);
+    }
+}

src/Metadata/OperationMutatorInterface.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace ApiPlatform\Metadata;
+
+interface OperationMutatorInterface
+{
+    public function __invoke(Operation $operation): Operation;
+}

src/Metadata/Resource/Factory/MutatorResourceMetadataCollectionFactory.php

@@ -0,0 +1,51 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Metadata\Resource\Factory;
+
+use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+use ApiPlatform\Metadata\ResourceMutatorInterface;
+use Psr\Container\ContainerInterface;
+
+final class MutatorResourceMetadataCollectionFactory implements ResourceMetadataCollectionFactoryInterface
+{
+    /**
+     * @param ContainerInterface<ResourceMutatorInterface[]> $resourceMutators
+     * @param ResourceMetadataCollectionFactoryInterface|null $decorated
+     */
+    public function __construct(
+        private readonly ContainerInterface $resourceMutators,
+        private readonly ?ResourceMetadataCollectionFactoryInterface $decorated = null,
+    ) {
+    }
+
+    public function create(string $resourceClass): ResourceMetadataCollection
+    {
+        $resourceMetadataCollection = new ResourceMetadataCollection($resourceClass);
+        if ($this->decorated) {
+            $resourceMetadataCollection = $this->decorated->create($resourceClass);
+        }
+
+        $newMetadataCollection = new ResourceMetadataCollection($resourceClass);
+
+        foreach ($resourceMetadataCollection as $resource) {
+            foreach ($this->resourceMutators->get($resourceClass) as $mutator) {
+                $resource = $mutator($resource);
+            }
+
+            $newMetadataCollection[] = $resource;
+        }
+
+        return $newMetadataCollection;
+    }
+}

src/Metadata/ResourceMutatorInterface.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace ApiPlatform\Metadata;
+
+interface ResourceMutatorInterface
+{
+    public function __invoke(ApiResource $resource): ApiResource;
+}

src/Symfony/Bundle/ApiPlatformBundle.php

@@ -24,6 +24,7 @@
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\GraphQlResolverPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\GraphQlTypePass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\MetadataAwareNameConverterPass;
+use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\MutatorPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\SerializerMappingLoaderPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\TestClientPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\TestMercureHubPass;
@@ -62,5 +63,6 @@ public function build(ContainerBuilder $container): void
         $container->addCompilerPass(new TestMercureHubPass());
         $container->addCompilerPass(new AuthenticatorManagerPass());
         $container->addCompilerPass(new SerializerMappingLoaderPass());
+        $container->addCompilerPass(new MutatorPass());
     }
 }

src/Symfony/Bundle/DependencyInjection/ApiPlatformExtension.php

@@ -31,7 +31,11 @@
 use ApiPlatform\GraphQl\Resolver\QueryItemResolverInterface;
 use ApiPlatform\GraphQl\Type\Definition\TypeInterface as GraphQlTypeInterface;
 use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\AsOperationMutator;
+use ApiPlatform\Metadata\AsResourceMutator;
 use ApiPlatform\Metadata\FilterInterface;
+use ApiPlatform\Metadata\OperationMutatorInterface;
+use ApiPlatform\Metadata\ResourceMutatorInterface;
 use ApiPlatform\Metadata\UriVariableTransformerInterface;
 use ApiPlatform\Metadata\UrlGeneratorInterface;
 use ApiPlatform\OpenApi\Model\Tag;
@@ -184,6 +188,29 @@
                 ->addTag('api_platform.resource')
                 ->addTag('container.excluded', ['source' => 'by #[ApiResource] attribute']);
         });
+        $container->registerAttributeForAutoconfiguration(AsResourceMutator::class,
+            static function (ChildDefinition $definition, AsResourceMutator $attribute, \ReflectionClass $reflector): void {
+                if (!is_a($reflector->name, ResourceMutatorInterface::class, true)) {
+                    throw new RuntimeException(sprintf('Resource mutator "%s" should implement %s', $reflector->name, ResourceMutatorInterface::class));
+                }
+
+                $definition->addTag('api_platform.resource_mutator', [
+                    'resourceClass' => $attribute->resourceClass,
+                ]);
+            },
+        );
+
+        $container->registerAttributeForAutoconfiguration(AsOperationMutator::class,
+            static function (ChildDefinition $definition, AsOperationMutator $attribute, \ReflectionClass $reflector): void {
+                if (!is_a($reflector->name, OperationMutatorInterface::class, true)) {
+                    throw new RuntimeException(sprintf('Operation mutator "%s" should implement %s', $reflector->name, OperationMutatorInterface::class));
+                }
+
+                $definition->addTag('api_platform.operation_mutator', [
+                    'operationName' => $attribute->operationName,
+                ]);
+            },
+        );
 
         if (!$container->has('api_platform.state.item_provider')) {
             $container->setAlias('api_platform.state.item_provider', 'api_platform.state_provider.object');
@@ -341,6 +368,7 @@
         $loader->load('metadata/property.xml');
         $loader->load('metadata/resource.xml');
         $loader->load('metadata/operation.xml');
+        $loader->load('metadata/mutator.xml');
 
         $container->getDefinition('api_platform.metadata.resource_extractor.xml')->replaceArgument(0, $xmlResources);
         $container->getDefinition('api_platform.metadata.property_extractor.xml')->replaceArgument(0, $xmlResources);

src/Symfony/Bundle/DependencyInjection/Compiler/MutatorPass.php

@@ -0,0 +1,41 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <dunglas@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler;
+
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Reference;
+
+class MutatorPass implements CompilerPassInterface
+{
+    public function process(ContainerBuilder $container): void
+    {
+        if (!$container->hasDefinition('api_platform.metadata.mutator_collection.resource')) {
+            return;
+        }
+
+        $definition = $container->getDefinition('api_platform.metadata.mutator_collection.resource');
+
+        $mutators = $container->findTaggedServiceIds('api_platform.resource_mutator');
+
+        foreach ($mutators as $id => $tags) {
+            foreach ($tags as $tag) {
+                $definition->addMethodCall('addMutator', [
+                    $tag['resourceClass'],
+                    new Reference($id),
+                ]);
+            }
+        }
+    }
+}

src/Symfony/Bundle/Resources/config/metadata/mutator.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" ?>
+
+<container xmlns="http://symfony.com/schema/dic/services"
+           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+    <services>
+        <service id="api_platform.metadata.mutator_collection.resource" class="ApiPlatform\Metadata\Mutator\ResourceMutatorCollection" public="false" />
+    </services>
+</container>

src/Symfony/Bundle/Resources/config/metadata/resource.xml

@@ -30,6 +30,11 @@
             <argument type="service" id="service_container" on-invalid="null" />
         </service>
 
+        <service id="api_platform.metadata.resource.metadata_collection_factory.mutator" class="ApiPlatform\Metadata\Resource\Factory\MutatorResourceMetadataCollectionFactory" decorates="api_platform.metadata.resource.metadata_collection_factory" decoration-priority="800" public="false" >
+            <argument type="service" id="api_platform.metadata.mutator_collection.resource" />
+            <argument type="service" id="api_platform.metadata.resource.metadata_collection_factory.mutator.inner" />
+        </service>
+
         <service id="api_platform.metadata.resource.metadata_collection_factory.concerns" class="ApiPlatform\Metadata\Resource\Factory\ConcernsResourceMetadataCollectionFactory" decorates="api_platform.metadata.resource.metadata_collection_factory" decoration-priority="800" public="false">
             <argument type="service" id="api_platform.metadata.resource.metadata_collection_factory.concerns.inner" />
         </service>

tests/Symfony/Bundle/ApiPlatformBundleTest.php

@@ -25,6 +25,7 @@
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\GraphQlResolverPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\GraphQlTypePass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\MetadataAwareNameConverterPass;
+use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\MutatorPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\SerializerMappingLoaderPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\TestClientPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\TestMercureHubPass;
@@ -58,6 +59,7 @@ public function testBuild(): void
         $containerProphecy->addCompilerPass(Argument::type(TestMercureHubPass::class))->willReturn($containerProphecy->reveal())->shouldBeCalled();
         $containerProphecy->addCompilerPass(Argument::type(AuthenticatorManagerPass::class))->willReturn($containerProphecy->reveal())->shouldBeCalled();
         $containerProphecy->addCompilerPass(Argument::type(SerializerMappingLoaderPass::class))->willReturn($containerProphecy->reveal())->shouldBeCalled();
+        $containerProphecy->addCompilerPass(Argument::type(MutatorPass::class))->willReturn($containerProphecy->reveal())->shouldBeCalled();
 
         $bundle = new ApiPlatformBundle();
         $bundle->build($containerProphecy->reveal());