feat(metadata): resource and operation level itemUriTemplate

src/Laravel/Routing/IriConverter.php

@@ -135,6 +135,13 @@ public function getIriFromResource(object|string $resource, int $referenceType =
         }
 
         $identifiersExtractorOperation = $operation;
+
+        // The IRI of an item operation with a custom URI template points to the canonical operation declared with "itemUriTemplate"
+        if (!isset($context['item_uri_template']) && $operation instanceof HttpOperation && !$operation instanceof CollectionOperationInterface && null !== ($itemUriTemplate = $operation->getItemUriTemplate())) {
+            $operation = $this->operationMetadataFactory->create($itemUriTemplate);
+            $identifiersExtractorOperation = $operation;
+        }
+
         // In symfony the operation name is the route name, try to find one if none provided
         if (
             !$operation->getName()

src/Metadata/ApiResource.php

@@ -982,6 +982,7 @@ public function __construct(
         protected array $extraProperties = [],
         ?bool $map = null,
         protected ?array $mcp = null,
+        protected ?string $itemUriTemplate = null,
     ) {
         parent::__construct(
             shortName: $shortName,
@@ -1093,6 +1094,19 @@ public function withUriTemplate(string $uriTemplate): static
         return $self;
     }
 
+    public function getItemUriTemplate(): ?string
+    {
+        return $this->itemUriTemplate;
+    }
+
+    public function withItemUriTemplate(?string $itemUriTemplate = null): static
+    {
+        $self = clone $this;
+        $self->itemUriTemplate = $itemUriTemplate;
+
+        return $self;
+    }
+
     public function getTypes(): ?array
     {
         return $this->types;

src/Metadata/Extractor/XmlResourceExtractor.php

@@ -17,9 +17,12 @@
 use ApiPlatform\Doctrine\Orm\State\Options as OrmOptions;
 use ApiPlatform\Elasticsearch\State\Options as ElasticsearchOptions;
 use ApiPlatform\Metadata\Exception\InvalidArgumentException;
+use ApiPlatform\Metadata\Get;
 use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\HeaderParameter;
+use ApiPlatform\Metadata\Patch;
 use ApiPlatform\Metadata\Post;
+use ApiPlatform\Metadata\Put;
 use ApiPlatform\Metadata\QueryParameter;
 use ApiPlatform\OpenApi\Model\ExternalDocumentation;
 use ApiPlatform\OpenApi\Model\Operation as OpenApiOperation;
@@ -64,6 +67,7 @@ protected function extractPath(string $path): void
         foreach ($xml->resource as $resource) {
             $base = $this->buildExtendedBase($resource);
             $this->resources[$this->resolve((string) $resource['class'])][] = array_merge($base, [
+                'itemUriTemplate' => $this->phpize($resource, 'itemUriTemplate', 'string'),
                 'operations' => $this->buildOperations($resource, $base),
                 'graphQlOperations' => $this->buildGraphQlOperations($resource, $base),
             ]);
@@ -411,7 +415,7 @@ private function buildOperations(\SimpleXMLElement $resource, array $root): ?arr
                 }
             }
 
-            if (\in_array((string) $operation['class'], [GetCollection::class, Post::class], true)) {
+            if (\in_array((string) $operation['class'], [GetCollection::class, Post::class, Get::class, Patch::class, Put::class], true)) {
                 $datum['itemUriTemplate'] = $this->phpize($operation, 'itemUriTemplate', 'string');
             } elseif (isset($operation['itemUriTemplate'])) {
                 throw new InvalidArgumentException(\sprintf('"itemUriTemplate" option is not allowed on a %s operation.', $operation['class']));

src/Metadata/Extractor/YamlResourceExtractor.php

@@ -17,9 +17,12 @@
 use ApiPlatform\Doctrine\Orm\State\Options as OrmOptions;
 use ApiPlatform\Elasticsearch\State\Options as ElasticsearchOptions;
 use ApiPlatform\Metadata\Exception\InvalidArgumentException;
+use ApiPlatform\Metadata\Get;
 use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\HeaderParameter;
+use ApiPlatform\Metadata\Patch;
 use ApiPlatform\Metadata\Post;
+use ApiPlatform\Metadata\Put;
 use ApiPlatform\Metadata\QueryParameter;
 use ApiPlatform\OpenApi\Model\ExternalDocumentation;
 use ApiPlatform\OpenApi\Model\Operation as OpenApiOperation;
@@ -89,6 +92,7 @@ private function buildResources(array $resourcesYaml, string $path): void
                 try {
                     $base = $this->buildExtendedBase($resourceYamlDatum);
                     $this->resources[$resourceName][$resourcesCount + $key] = array_merge($base, [
+                        'itemUriTemplate' => $this->phpize($resourceYamlDatum, 'itemUriTemplate', 'string'),
                         'operations' => $this->buildOperations($resourceYamlDatum, $base),
                         'graphQlOperations' => $this->buildGraphQlOperations($resourceYamlDatum, $base),
                     ]);
@@ -349,7 +353,7 @@ private function buildOperations(array $resource, array $root): ?array
                 }
             }
 
-            if (\in_array((string) $class, [GetCollection::class, Post::class], true)) {
+            if (\in_array((string) $class, [GetCollection::class, Post::class, Get::class, Patch::class, Put::class], true)) {
                 $datum['itemUriTemplate'] = $this->phpize($operation, 'itemUriTemplate', 'string');
             } elseif (isset($operation['itemUriTemplate'])) {
                 throw new InvalidArgumentException(\sprintf('"itemUriTemplate" option is not allowed on a %s operation.', $class));

src/Metadata/Extractor/schema/resources.xsd

@@ -22,6 +22,7 @@
         </xsd:sequence>
         <xsd:attributeGroup ref="extendedBase"/>
         <xsd:attribute type="xsd:string" name="uriTemplate"/>
+        <xsd:attribute type="xsd:string" name="itemUriTemplate"/>
         <xsd:attribute type="xsd:string" name="class" use="required"/>
     </xsd:complexType>
 

src/Metadata/Get.php

@@ -105,6 +105,7 @@ public function __construct(
         ?bool $throwOnNotFound = null,
         array $extraProperties = [],
         ?bool $map = null,
+        ?string $itemUriTemplate = null,
     ) {
         parent::__construct(
             uriTemplate: $uriTemplate,
@@ -189,7 +190,8 @@ class: $class,
             jsonStream: $jsonStream,
             throwOnNotFound: $throwOnNotFound,
             extraProperties: $extraProperties,
-            map: $map
+            map: $map,
+            itemUriTemplate: $itemUriTemplate
         );
     }
 }

src/Metadata/GetCollection.php

@@ -104,7 +104,7 @@ public function __construct(
         ?bool $jsonStream = null,
         array $extraProperties = [],
         ?bool $throwOnNotFound = null,
-        private ?string $itemUriTemplate = null,
+        ?string $itemUriTemplate = null,
         ?bool $map = null,
     ) {
         parent::__construct(
@@ -190,20 +190,8 @@ class: $class,
             strictQueryParameterValidation: $strictQueryParameterValidation,
             hideHydraOperation: $hideHydraOperation,
             stateOptions: $stateOptions,
-            map: $map
+            map: $map,
+            itemUriTemplate: $itemUriTemplate
         );
     }
-
-    public function getItemUriTemplate(): ?string
-    {
-        return $this->itemUriTemplate;
-    }
-
-    public function withItemUriTemplate(string $itemUriTemplate): self
-    {
-        $self = clone $this;
-        $self->itemUriTemplate = $itemUriTemplate;
-
-        return $self;
-    }
 }

src/Metadata/HttpOperation.php

@@ -225,6 +225,7 @@ public function __construct(
         ?bool $throwOnNotFound = null,
         array $extraProperties = [],
         ?bool $map = null,
+        protected ?string $itemUriTemplate = null,
     ) {
         $this->formats = (null === $formats || \is_array($formats)) ? $formats : [$formats];
         $this->inputFormats = (null === $inputFormats || \is_array($inputFormats)) ? $inputFormats : [$inputFormats];
@@ -316,6 +317,19 @@ public function withUriTemplate(?string $uriTemplate = null): static
         return $self;
     }
 
+    public function getItemUriTemplate(): ?string
+    {
+        return $this->itemUriTemplate;
+    }
+
+    public function withItemUriTemplate(?string $itemUriTemplate = null): static
+    {
+        $self = clone $this;
+        $self->itemUriTemplate = $itemUriTemplate;
+
+        return $self;
+    }
+
     public function getTypes(): ?array
     {
         return $this->types;

src/Metadata/Patch.php

@@ -105,6 +105,7 @@ public function __construct(
         ?bool $throwOnNotFound = null,
         array $extraProperties = [],
         ?bool $map = null,
+        ?string $itemUriTemplate = null,
     ) {
         parent::__construct(
             method: 'PATCH',
@@ -190,7 +191,8 @@ class: $class,
             jsonStream: $jsonStream,
             throwOnNotFound: $throwOnNotFound,
             extraProperties: $extraProperties,
-            map: $map
+            map: $map,
+            itemUriTemplate: $itemUriTemplate
         );
     }
 }

src/Metadata/Post.php

@@ -102,7 +102,7 @@ public function __construct(
         ?bool $jsonStream = null,
         ?bool $throwOnNotFound = null,
         array $extraProperties = [],
-        private ?string $itemUriTemplate = null,
+        ?string $itemUriTemplate = null,
         ?bool $strictQueryParameterValidation = null,
         ?bool $hideHydraOperation = null,
         ?bool $map = null,
@@ -191,20 +191,8 @@ class: $class,
             jsonStream: $jsonStream,
             throwOnNotFound: $throwOnNotFound,
             extraProperties: $extraProperties,
-            map: $map
+            map: $map,
+            itemUriTemplate: $itemUriTemplate
         );
     }
-
-    public function getItemUriTemplate(): ?string
-    {
-        return $this->itemUriTemplate;
-    }
-
-    public function withItemUriTemplate(string $itemUriTemplate): self
-    {
-        $self = clone $this;
-        $self->itemUriTemplate = $itemUriTemplate;
-
-        return $self;
-    }
 }

src/Metadata/Put.php

@@ -106,6 +106,7 @@ public function __construct(
         ?bool $hideHydraOperation = null,
         private ?bool $allowCreate = null,
         ?bool $map = null,
+        ?string $itemUriTemplate = null,
     ) {
         parent::__construct(
             method: 'PUT',
@@ -191,7 +192,8 @@ class: $class,
             jsonStream: $jsonStream,
             throwOnNotFound: $throwOnNotFound,
             extraProperties: $extraProperties,
-            map: $map
+            map: $map,
+            itemUriTemplate: $itemUriTemplate
         );
     }
 

src/Metadata/Tests/Extractor/Adapter/XmlResourceAdapter.php

@@ -24,6 +24,7 @@ final class XmlResourceAdapter implements ResourceAdapterInterface
 {
     private const ATTRIBUTES = [
         'uriTemplate',
+        'itemUriTemplate',
         'shortName',
         'description',
         'routePrefix',