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 <[email protected]>
+ *
+ * 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 <[email protected]>
+ *
+ * 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/OperationMutatorCollection.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * 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 ApiPlatform\Metadata\OperationMutatorInterface;
+use Psr\Container\ContainerInterface;
+
+final class OperationMutatorCollection implements ContainerInterface
+{
+    private array $mutators;
+
+    public function addMutator(string $operationName, OperationMutatorInterface $mutator): void
+    {
+        $this->mutators[$operationName][] = $mutator;
+    }
+
+    public function get(string $id): array
+    {
+        return $this->mutators[$id] ?? [];
+    }
+
+    public function has(string $id): bool
+    {
+        return isset($this->mutators[$id]);
+    }
+}

src/Metadata/Mutator/ResourceMutatorCollection.php

@@ -0,0 +1,37 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * 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 ApiPlatform\Metadata\ResourceMutatorInterface;
+use Psr\Container\ContainerInterface;
+
+final class ResourceMutatorCollection implements ContainerInterface
+{
+    private array $mutators;
+
+    public function addMutator(string $resourceClass, ResourceMutatorInterface $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,19 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * 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;
+
+interface OperationMutatorInterface
+{
+    public function __invoke(Operation $operation): Operation;
+}

src/Metadata/Resource/Factory/MutatorResourceMetadataCollectionFactory.php

@@ -0,0 +1,81 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * 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\ApiResource;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Metadata\OperationMutatorInterface;
+use ApiPlatform\Metadata\Operations;
+use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+use ApiPlatform\Metadata\ResourceMutatorInterface;
+use Psr\Container\ContainerInterface;
+
+final class MutatorResourceMetadataCollectionFactory implements ResourceMetadataCollectionFactoryInterface
+{
+    /**
+     * @param ContainerInterface<ResourceMutatorInterface[]>  $resourceMutators
+     * @param ContainerInterface<OperationMutatorInterface[]> $operationMutators
+     */
+    public function __construct(
+        private readonly ContainerInterface $resourceMutators,
+        private readonly ContainerInterface $operationMutators,
+        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) {
+            $resource = $this->mutateResource($resource, $resourceClass);
+            $operations = $this->mutateOperations($resource->getOperations() ?? new Operations());
+            $resource = $resource->withOperations($operations);
+
+            $newMetadataCollection[] = $resource;
+        }
+
+        return $newMetadataCollection;
+    }
+
+    private function mutateResource(ApiResource $resource, string $resourceClass): ApiResource
+    {
+        foreach ($this->resourceMutators->get($resourceClass) as $mutator) {
+            $resource = $mutator($resource);
+        }
+
+        return $resource;
+    }
+
+    private function mutateOperations(Operations $operations): Operations
+    {
+        $newOperations = new Operations();
+
+        /** @var Operation $operation */
+        foreach ($operations as $key => $operation) {
+            foreach ($this->operationMutators->get($key) as $mutator) {
+                $operation = $mutator($operation);
+            }
+
+            $newOperations->add($key, $operation);
+        }
+
+        return $newOperations;
+    }
+}

src/Metadata/ResourceMutatorInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * 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;
+
+interface ResourceMutatorInterface
+{
+    public function __invoke(ApiResource $resource): ApiResource;
+}

src/Metadata/Tests/Resource/Factory/MutatorResourceMetadataCollectionFactoryTest.php

@@ -0,0 +1,96 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * 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\Tests\Resource\Factory;
+
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\HttpOperation;
+use ApiPlatform\Metadata\Mutator\OperationMutatorCollection;
+use ApiPlatform\Metadata\Mutator\ResourceMutatorCollection;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Metadata\OperationMutatorInterface;
+use ApiPlatform\Metadata\Operations;
+use ApiPlatform\Metadata\Resource\Factory\MutatorResourceMetadataCollectionFactory;
+use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
+use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+use ApiPlatform\Metadata\ResourceMutatorInterface;
+use PHPUnit\Framework\TestCase;
+
+final class MutatorResourceMetadataCollectionFactoryTest extends TestCase
+{
+    public function testMutateResource(): void
+    {
+        $decorated = $this->createMock(ResourceMetadataCollectionFactoryInterface::class);
+        $resourceClass = \stdClass::class;
+        $resourceMetadataCollection = new ResourceMetadataCollection($resourceClass);
+        $resourceMetadataCollection[] = (new ApiResource())->withClass($resourceClass);
+
+        $resourceMutatorCollection = new ResourceMutatorCollection();
+        $resourceMutatorCollection->addMutator($resourceClass, new DummyResourceMutator());
+
+        $customResourceMetadataCollectionFactory = new MutatorResourceMetadataCollectionFactory($resourceMutatorCollection, new OperationMutatorCollection(), $decorated);
+
+        $decorated->expects($this->once())->method('create')->with($resourceClass)->willReturn(
+            $resourceMetadataCollection,
+        );
+
+        $resourceMetadataCollection = $customResourceMetadataCollectionFactory->create($resourceClass);
+
+        $resource = $resourceMetadataCollection->getIterator()->current();
+        $this->assertInstanceOf(ApiResource::class, $resource);
+        $this->assertSame('dummy', $resource->getShortName());
+    }
+
+    public function testMutateOperation(): void
+    {
+        $decorated = $this->createMock(ResourceMetadataCollectionFactoryInterface::class);
+        $resourceClass = \stdClass::class;
+
+        $operations = new Operations();
+        $operations->add('_api_Dummy_get', new HttpOperation());
+
+        $resourceMetadataCollection = new ResourceMetadataCollection($resourceClass);
+        $resourceMetadataCollection[] = (new ApiResource())->withClass($resourceClass)->withOperations($operations);
+
+        $operationMutatorCollection = new OperationMutatorCollection();
+        $operationMutatorCollection->addMutator('_api_Dummy_get', new DummyOperationMutator());
+
+        $customResourceMetadataCollectionFactory = new MutatorResourceMetadataCollectionFactory(new ResourceMutatorCollection(), $operationMutatorCollection, $decorated);
+
+        $decorated->expects($this->once())->method('create')->with($resourceClass)->willReturn(
+            $resourceMetadataCollection,
+        );
+
+        $resourceMetadataCollection = $customResourceMetadataCollectionFactory->create($resourceClass);
+
+        $resource = $resourceMetadataCollection->getIterator()->current();
+        $this->assertInstanceOf(ApiResource::class, $resource);
+        $this->assertEquals('custom_dummy', $resourceMetadataCollection->getOperation('_api_Dummy_get')->getShortName());
+    }
+}
+
+final class DummyResourceMutator implements ResourceMutatorInterface
+{
+    public function __invoke(ApiResource $resource): ApiResource
+    {
+        return $resource->withShortName('dummy');
+    }
+}
+
+final class DummyOperationMutator implements OperationMutatorInterface
+{
+    public function __invoke(Operation $operation): Operation
+    {
+        return $operation->withShortName('custom_dummy');
+    }
+}

src/Symfony/Bundle/ApiPlatformBundle.php

@@ -24,6 +24,8 @@
 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\OperationMutatorPass;
+use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\ResourceMutatorPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\SerializerMappingLoaderPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\TestClientPass;
 use ApiPlatform\Symfony\Bundle\DependencyInjection\Compiler\TestMercureHubPass;
@@ -62,5 +64,7 @@ public function build(ContainerBuilder $container): void
         $container->addCompilerPass(new TestMercureHubPass());
         $container->addCompilerPass(new AuthenticatorManagerPass());
         $container->addCompilerPass(new SerializerMappingLoaderPass());
+        $container->addCompilerPass(new ResourceMutatorPass());
+        $container->addCompilerPass(new OperationMutatorPass());
     }
 }