refactor(metadata): cascade resource to operation

soyuka · soyuka · commit 936e4f917556 · 2025-06-27T12:23:20.000+02:00
diff --git a/src/Metadata/ApiResource.php b/src/Metadata/ApiResource.php
@@ -31,8 +31,12 @@
 #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
 class ApiResource extends Metadata
 {
+    use CascadeToOperationsTrait;
     use WithResourceTrait;
 
+    /**
+     * @var Operations<HttpOperation>
+     */
     protected ?Operations $operations;
 
     /**
diff --git a/src/Metadata/CascadeFromResource.php b/src/Metadata/CascadeFromResource.php
@@ -0,0 +1,29 @@
+<?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;
+
+/**
+ * @internal
+ *
+ * @phpstan-require-extends Operation
+ */
+trait CascadeFromResource
+{
+    use WithResourceTrait;
+
+    public function cascadeFromResource(ApiResource $apiResource, array $ignoredOptions = []): static
+    {
+        return $this->copyFrom($apiResource, $ignoredOptions);
+    }
+}
diff --git a/src/Metadata/CascadeToOperationsTrait.php b/src/Metadata/CascadeToOperationsTrait.php
@@ -0,0 +1,70 @@
+<?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;
+
+use ApiPlatform\Metadata\Exception\RuntimeException;
+use ApiPlatform\Metadata\GraphQl\Operation as GraphQlOperation;
+
+/**
+ * @internal
+ *
+ * @phpstan-require-extends ApiResource
+ */
+trait CascadeToOperationsTrait
+{
+    public function cascadeToOperations(): static
+    {
+        if (!$this instanceof ApiResource) {
+            throw new RuntimeException('Not an API resource');
+        }
+
+        if (!($operations = $this->getOperations() ?? [])) {
+            return $this;
+        }
+
+        return (clone $this)->withOperations(
+            new Operations($this->getMutatedOperations($operations, $this)),
+        );
+    }
+
+    public function cascadeToGraphQlOperations(): static
+    {
+        if (!$this instanceof ApiResource) {
+            throw new RuntimeException('Not an API resource');
+        }
+
+        if (!($operations = $this->getGraphQlOperations() ?? [])) {
+            return $this;
+        }
+
+        return (clone $this)->withGraphQlOperations(
+            $this->getMutatedOperations($operations, $this),
+        );
+    }
+
+    /**
+     * @param Operations<HttpOperation>|list<GraphQlOperation> $operations
+     *
+     * @return array[string, HttpOperation]|list<GraphQlOperation>
+     */
+    private function getMutatedOperations(iterable $operations, ApiResource $apiResource): iterable
+    {
+        $modifiedOperations = [];
+        foreach ($operations as $key => $operation) {
+            $modifiedOperations[$key] = $operation->cascadeFromResource($apiResource);
+        }
+
+        return $modifiedOperations;
+    }
+}
diff --git a/src/Metadata/Operation.php b/src/Metadata/Operation.php
@@ -20,6 +20,7 @@
  */
 abstract class Operation extends Metadata
 {
+    use CascadeFromResource;
     use WithResourceTrait;
 
     /**
@@ -861,7 +862,7 @@ class: $class,
         );
     }
 
-    public function withOperation($operation)
+    public function withOperation(self $operation): static
     {
         return $this->copyFrom($operation);
     }
diff --git a/src/Metadata/Operations.php b/src/Metadata/Operations.php
@@ -15,9 +15,14 @@
 
 /**
  * An Operation dictionnary.
+ *
+ * @template T of Operation
  */
 final class Operations implements \IteratorAggregate, \Countable
 {
+    /**
+     * @var array{string, T}
+     */
     private array $operations = [];
 
     /**
@@ -42,6 +47,9 @@ public function __construct(array $operations = [])
         $this->sort();
     }
 
+    /**
+     * @return Traversable<string, T>
+     */
     public function getIterator(): \Traversable
     {
         return (function (): \Generator {
diff --git a/src/Metadata/Resource/Factory/NotExposedOperationResourceMetadataCollectionFactory.php b/src/Metadata/Resource/Factory/NotExposedOperationResourceMetadataCollectionFactory.php
@@ -70,8 +70,7 @@ public function create(string $resourceClass): ResourceMetadataCollection
 
         // No item operation has been found on all resources for resource class: generate one on the last resource
         // Helpful to generate an IRI for a resource without declaring the Get operation
-        /** @var HttpOperation $operation */
-        [$key, $operation] = $this->getOperationWithDefaults(resource: $resource, operation: new NotExposed(), generated: true, ignoredOptions: ['uriTemplate', 'uriVariables']); // @phpstan-ignore-line $resource is defined if count > 0
+        [$key, $operation] = $this->getOperationWithDefaults($resource, new NotExposed(), true, ['uriTemplate', 'uriVariables']); // @phpstan-ignore-line $resource is defined if count > 0
 
         if (!$this->linkFactory->createLinksFromIdentifiers($operation)) {
             $operation = $operation->withUriTemplate(self::$skolemUriTemplate);
diff --git a/src/Metadata/Resource/Factory/OperationDefaultsTrait.php b/src/Metadata/Resource/Factory/OperationDefaultsTrait.php
@@ -36,6 +36,9 @@
 use ApiPlatform\Validator\Exception\ValidationException;
 use Psr\Log\LoggerInterface;
 
+/**
+ * @internal since api-platform 4.2
+ */
 trait OperationDefaultsTrait
 {
     private CamelCaseToSnakeCaseNameConverter $camelCaseToSnakeCaseNameConverter;
@@ -96,7 +99,10 @@ private function getResourceWithDefaults(string $resourceClass, string $shortNam
         return $this->addGlobalDefaults($resource);
     }
 
-    private function getDefaultHttpOperations($resource): iterable
+    /**
+     * @return Operations<HttpOperation>|array<int,HttpOperation>
+     */
+    private function getDefaultHttpOperations(ApiResource $resource): iterable
     {
         if (enum_exists($resource->getClass())) {
             return new Operations([new GetCollection(paginationEnabled: false), new Get()]);
@@ -175,30 +181,14 @@ private function completeGraphQlOperations(ApiResource $resource): ApiResource
         return $resource->withGraphQlOperations($graphQlOperations);
     }
 
+    /**
+     * @param list<string> $ignoredOptions
+     *
+     * @return array<int,mixed>
+     */
     private function getOperationWithDefaults(ApiResource $resource, Operation $operation, bool $generated = false, array $ignoredOptions = []): array
     {
-        // Inherit from resource defaults
-        foreach (get_class_methods($resource) as $methodName) {
-            if (!str_starts_with($methodName, 'get')) {
-                continue;
-            }
-
-            if (\in_array(lcfirst(substr($methodName, 3)), $ignoredOptions, true)) {
-                continue;
-            }
-
-            if (!method_exists($operation, $methodName) || null !== $operation->{$methodName}()) {
-                continue;
-            }
-
-            if (null === ($value = $resource->{$methodName}())) {
-                continue;
-            }
-
-            $operation = $operation->{'with'.substr($methodName, 3)}($value);
-        }
-
-        $operation = $operation->withExtraProperties(array_merge(
+        $operation = $operation->cascadeFromResource($resource, $ignoredOptions)->withExtraProperties(array_merge(
             $resource->getExtraProperties(),
             $operation->getExtraProperties(),
             $generated ? ['generated_operation' => true] : []
@@ -249,6 +239,7 @@ private function getDefaultOperationName(HttpOperation $operation, string $resou
             '_api_%s_%s%s',
             $path ?: ($operation->getShortName() ?? $this->getDefaultShortname($resourceClass)),
             strtolower($operation->getMethod()),
-            $operation instanceof CollectionOperationInterface ? '_collection' : '');
+            $operation instanceof CollectionOperationInterface ? '_collection' : ''
+        );
     }
 }
diff --git a/src/Metadata/Tests/Resource/Factory/AttributesResourceMetadataCollectionFactoryTest.php b/src/Metadata/Tests/Resource/Factory/AttributesResourceMetadataCollectionFactoryTest.php
@@ -71,13 +71,25 @@ class: AttributeResource::class,
                     provider: AttributeResourceProvider::class,
                     operations: [
                         '_api_AttributeResource_get' => new Get(
-                            shortName: 'AttributeResource', class: AttributeResource::class, normalizationContext: ['skip_null_values' => true], priority: 1, provider: AttributeResourceProvider::class,
+                            shortName: 'AttributeResource',
+                            class: AttributeResource::class,
+                            normalizationContext: ['skip_null_values' => true],
+                            priority: 1,
+                            provider: AttributeResourceProvider::class,
                         ),
                         '_api_AttributeResource_put' => new Put(
-                            shortName: 'AttributeResource', class: AttributeResource::class, normalizationContext: ['skip_null_values' => true], priority: 2, provider: AttributeResourceProvider::class,
+                            shortName: 'AttributeResource',
+                            class: AttributeResource::class,
+                            normalizationContext: ['skip_null_values' => true],
+                            priority: 2,
+                            provider: AttributeResourceProvider::class,
                         ),
                         '_api_AttributeResource_delete' => new Delete(
-                            shortName: 'AttributeResource', class: AttributeResource::class, normalizationContext: ['skip_null_values' => true], priority: 3, provider: AttributeResourceProvider::class,
+                            shortName: 'AttributeResource',
+                            class: AttributeResource::class,
+                            normalizationContext: ['skip_null_values' => true],
+                            priority: 3,
+                            provider: AttributeResourceProvider::class,
                         ),
                     ],
                     graphQlOperations: $this->getDefaultGraphqlOperations('AttributeResource', AttributeResource::class, AttributeResourceProvider::class)
diff --git a/src/Metadata/WithResourceTrait.php b/src/Metadata/WithResourceTrait.php
@@ -13,15 +13,19 @@
 
 namespace ApiPlatform\Metadata;
 
+/**
+ * @internal since api-platform/metadata 4.2
+ */
 trait WithResourceTrait
 {
-    protected function copyFrom(Metadata $resource): static
+    protected function copyFrom(Metadata $resource, array $ignoredOptions = []): static
     {
         $self = clone $this;
         foreach (get_class_methods($resource) as $method) {
             if (
                 method_exists($self, $method)
                 && preg_match('/^(?:get|is|can)(.*)/', (string) $method, $matches)
+                && (!$ignoredOptions || !\in_array(lcfirst($matches[1]), $ignoredOptions, true))
                 && null === $self->{$method}()
                 && null !== $val = $resource->{$method}()
             ) {
diff --git a/tests/Fixtures/TestBundle/Entity/AttributeResource.php b/tests/Fixtures/TestBundle/Entity/AttributeResource.php
@@ -31,7 +31,7 @@
 #[Put]
 #[Delete]
 #[ApiResource(
-    '/dummy/{dummyId}/attribute_resources/{identifier}{._format}',
+    uriTemplate: '/dummy/{dummyId}/attribute_resources/{identifier}{._format}',
     inputFormats: ['json' => ['application/merge-patch+json']],
     status: 301,
     provider: AttributeResourceProvider::class,

Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,7 @@`
`20`	`20`	`*/`
`21`	`21`	`abstract class Operation extends Metadata`
`22`	`22`	`{`
	`23`	`+ use CascadeFromResource;`
`23`	`24`	`use WithResourceTrait;`
`24`	`25`
`25`	`26`	`/**`
`@@ -861,7 +862,7 @@ class: $class,`
`861`	`862`	`);`
`862`	`863`	`}`
`863`	`864`
`864`		`- public function withOperation($operation)`
	`865`	`+ public function withOperation(self $operation): static`
`865`	`866`	`{`
`866`	`867`	`return $this->copyFrom($operation);`
`867`	`868`	`}`