feat(metadata): introduce metadata mutators for resource & operations (#7213)

Co-authored-by: Antoine Bluchet <soyuka@users.noreply.github.com>

Author: loic425

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)]
+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)]
+class AsResourceMutator
+{
+    /**
+     * @param class-string $resourceClass
+     */
+    public function __construct(
+        public readonly string $resourceClass,
+    ) {
+    }
+}

src/Metadata/Mutator/OperationMutatorCollectionInterface.php

@@ -0,0 +1,28 @@
+<?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 ApiPlatform\Metadata\OperationMutatorInterface;
+use Psr\Container\ContainerInterface;
+
+/**
+ * Collection of Operation mutators to mutate Operation metadata.
+ */
+interface OperationMutatorCollectionInterface extends ContainerInterface
+{
+    /**
+     * @return list<OperationMutatorInterface>
+     */
+    public function get(string $id): mixed;
+}

src/Metadata/Mutator/OperationResourceMutatorCollection.php

@@ -0,0 +1,42 @@
+<?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 ApiPlatform\Metadata\OperationMutatorInterface;
+
+/**
+ * @internal
+ */
+final class OperationResourceMutatorCollection implements OperationMutatorCollectionInterface
+{
+    private array $mutators = [];
+
+    /**
+     * Adds a mutator to the container for a given operation name.
+     */
+    public function add(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/ResourceMutatorCollectionInterface.php

@@ -0,0 +1,28 @@
+<?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 ApiPlatform\Metadata\ResourceMutatorInterface;
+use Psr\Container\ContainerInterface;
+
+/**
+ * Collection of Resource mutators to mutate ApiResource metadata.
+ */
+interface ResourceMutatorCollectionInterface extends ContainerInterface
+{
+    /**
+     * @return list<ResourceMutatorInterface>
+     */
+    public function get(string $id): array;
+}

src/Metadata/Mutator/ResourceResourceMutatorCollection.php

@@ -0,0 +1,39 @@
+<?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 ApiPlatform\Metadata\ResourceMutatorInterface;
+
+/**
+ * @internal
+ */
+final class ResourceResourceMutatorCollection implements ResourceMutatorCollectionInterface
+{
+    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 <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;
+
+interface OperationMutatorInterface
+{
+    public function __invoke(Operation $operation): Operation;
+}

src/Metadata/Resource/Factory/MutatorResourceMetadataCollectionFactory.php

@@ -0,0 +1,76 @@
+<?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\ApiResource;
+use ApiPlatform\Metadata\Mutator\OperationMutatorCollectionInterface;
+use ApiPlatform\Metadata\Mutator\ResourceMutatorCollectionInterface;
+use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Metadata\Operations;
+use ApiPlatform\Metadata\Resource\ResourceMetadataCollection;
+
+final class MutatorResourceMetadataCollectionFactory implements ResourceMetadataCollectionFactoryInterface
+{
+    public function __construct(
+        private readonly ResourceMutatorCollectionInterface $resourceMutators,
+        private readonly OperationMutatorCollectionInterface $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 <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;
+
+interface ResourceMutatorInterface
+{
+    public function __invoke(ApiResource $resource): ApiResource;
+}