iro-only: defer loading of property value

features/hal/collection_uri_template.feature

@@ -0,0 +1,52 @@
+@php8
+@v3
+Feature: Exposing a property being a collection of resources
+  can return an IRI instead of an array
+  when the uriTemplate is set on the ApiProperty attribute
+
+  Scenario: Retrieve Resource with uriTemplate collection Property
+    Given there are propertyCollectionIriOnly with relations
+    When I add "Accept" header equal to "application/hal+json"
+    And I send a "GET" request to "/property_collection_iri_onlies/1"
+    Then the response status code should be 200
+    And the response should be in JSON
+    And the JSON should be valid according to the JSON HAL schema
+    And the header "Content-Type" should be equal to "application/hal+json; charset=utf-8"
+    And the JSON should be equal to:
+      """
+      {
+        "_links": {
+            "self": {
+                "href": "/property_collection_iri_onlies/1"
+            },
+            "propertyCollectionIriOnlyRelation": {
+                "href": "/property-collection-relations"
+            },
+            "iterableIri": {
+                "href": "/parent/1/another-collection-operations"
+            }
+        },
+        "_embedded": {
+            "propertyCollectionIriOnlyRelation": [
+                {
+                    "_links": {
+                        "self": {
+                            "href": "/property_collection_iri_only_relations/1"
+                        }
+                    },
+                    "name": "relation"
+                }
+            ],
+            "iterableIri": [
+                {
+                    "_links": {
+                        "self": {
+                            "href": "/property_collection_iri_only_relations/9999"
+                        }
+                    },
+                    "name": "Michel"
+                }
+            ]
+        }
+      }
+      """

features/jsonld/iri_only.feature

@@ -56,3 +56,37 @@ Feature: JSON-LD using iri_only parameter
           "hydra:totalItems": 3
       }
       """
+
+  Scenario: Retrieve Resource with uriTemplate collection Property
+    Given there are propertyCollectionIriOnly with relations
+    When I send a "GET" request to "/property_collection_iri_onlies"
+    Then the response status code should be 200
+    And the response should be in JSON
+    And the header "Content-Type" should be equal to "application/ld+json; charset=utf-8"
+    And the JSON should be valid according to this schema:
+      """
+      {
+        "hydra:member": [
+          {
+            "@id": "/property_collection_iri_onlies/1",
+            "@type": "PropertyCollectionIriOnly",
+            "propertyCollectionIriOnlyRelation": "/property-collection-relations",
+            "iterableIri": "/parent/1/another-collection-operations"
+          }
+        ]
+      }
+      """
+    When I send a "GET" request to "/property_collection_iri_onlies/1"
+    Then the response status code should be 200
+    And the response should be in JSON
+    And the header "Content-Type" should be equal to "application/ld+json; charset=utf-8"
+    And the JSON should be valid according to this schema:
+      """
+      {
+        "@context": "/contexts/PropertyCollectionIriOnly",
+        "@id": "/property_collection_iri_onlies/1",
+        "@type": "PropertyCollectionIriOnly",
+        "propertyCollectionIriOnlyRelation": "/property-collection-relations",
+        "iterableIri": "/parent/1/another-collection-operations"
+      }
+      """

src/Doctrine/Orm/Extension/EagerLoadingExtension.php

@@ -155,8 +155,9 @@ private function joinRelations(QueryBuilder $queryBuilder, QueryNameGeneratorInt
             }
 
             $fetchEager = $propertyMetadata->getFetchEager();
+            $uriTemplate = $propertyMetadata->getUriTemplate();
 
-            if (false === $fetchEager) {
+            if (false === $fetchEager || null !== $uriTemplate) {
                 continue;
             }
 

src/Hal/Serializer/ItemNormalizer.php

@@ -14,6 +14,7 @@
 namespace ApiPlatform\Hal\Serializer;
 
 use ApiPlatform\Api\UrlGeneratorInterface;
+use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\Util\ClassInfoTrait;
 use ApiPlatform\Serializer\AbstractItemNormalizer;
 use ApiPlatform\Serializer\CacheKeyTrait;
@@ -166,7 +167,28 @@ private function getComponents(object $object, ?string $format, array $context):
                     continue;
                 }
 
-                $relation = ['name' => $attribute, 'cardinality' => $isOne ? 'one' : 'many'];
+                $relation = ['name' => $attribute, 'cardinality' => $isOne ? 'one' : 'many', 'uriTemplate' => null];
+
+                // if we specify the uriTemplate, generates its value for link definition
+                // @see ApiPlatform\Serializer\AbstractItemNormalizer:getAttributeValue logic for intentional duplicate content
+                if ($isMany && $itemUriTemplate = $propertyMetadata->getUriTemplate()) {
+                    $attributeValue = $this->propertyAccessor->getValue($object, $attribute);
+                    $resourceClass = $this->resourceClassResolver->getResourceClass($attributeValue, $className);
+                    $childContext = $this->createChildContext($context, $attribute, $format);
+                    unset($childContext['iri'], $childContext['uri_variables'], $childContext['resource_class'], $childContext['operation']);
+
+                    $operation = $this->resourceMetadataCollectionFactory->create($resourceClass)->getOperation(
+                        operationName: $itemUriTemplate,
+                        forceCollection: true,
+                        httpOperation: true
+                    );
+
+                    if ($operation instanceof GetCollection) {
+                        $relation['uriTemplate'] = $this->iriConverter->getIriFromResource($object, UrlGeneratorInterface::ABS_PATH, $operation, $childContext);
+                    }
+                }
+
+
                 if ($propertyMetadata->isReadableLink()) {
                     $components['embedded'][] = $relation;
                 }
@@ -215,6 +237,12 @@ private function populateRelation(array $data, object $object, ?string $format,
                 $relationName = $this->nameConverter->normalize($relationName, $class, $format, $context);
             }
 
+            // if we specify the uriTemplate, then the link takes the uriTemplate defined.
+            if ('links' === $type && $itemUriTemplate = $relation['uriTemplate']) {
+                $data[$key][$relationName]['href'] = $itemUriTemplate;
+                continue;
+            }
+
             if ('one' === $relation['cardinality']) {
                 if ('links' === $type) {
                     $data[$key][$relationName]['href'] = $this->getRelationIri($attributeValue);

src/JsonSchema/Metadata/Property/Factory/SchemaPropertyMetadataFactory.php

@@ -49,7 +49,7 @@ public function create(string $resourceClass, string $property, array $options =
 
         $propertySchema = $propertyMetadata->getSchema() ?? [];
 
-        if (!\array_key_exists('readOnly', $propertySchema) && false === $propertyMetadata->isWritable() && !$propertyMetadata->isInitializable()) {
+        if (null !== $propertyMetadata->getUriTemplate() || (!\array_key_exists('readOnly', $propertySchema) && false === $propertyMetadata->isWritable() && !$propertyMetadata->isInitializable())) {
             $propertySchema['readOnly'] = true;
         }
 
@@ -124,6 +124,11 @@ public function create(string $resourceClass, string $property, array $options =
                 $propertySchema['owl:maxCardinality'] = 1;
             }
 
+            if ($isCollection && null !== $propertyMetadata->getUriTemplate()) {
+                $keyType = null;
+                $isCollection = false;
+            }
+
             $propertyType = $this->getType(new Type($builtinType, $type->isNullable(), $className, $isCollection, $keyType, $valueType), $propertyMetadata->isReadableLink());
             if (!\in_array($propertyType, $valueSchema, true)) {
                 $valueSchema[] = $propertyType;

src/Metadata/ApiProperty.php

@@ -40,6 +40,7 @@ final class ApiProperty
      * @param string[]    $types                   the RDF types of this property
      * @param string[]    $iris
      * @param Type[]      $builtinTypes
+     * @param string|null $uriTemplate             whether to return the subRessource collection IRI instead of an iterable of IRI
      */
     public function __construct(
         private ?string $description = null,
@@ -105,15 +106,16 @@ public function __construct(
         private ?string $security = null,
         private ?string $securityPostDenormalize = null,
         private array|string|null $types = null,
-        /**
+        /*
          * The related php types.
          */
         private ?array $builtinTypes = null,
         private ?array $schema = null,
         private ?bool $initializable = null,
         private $iris = null,
         private ?bool $genId = null,
-        private array $extraProperties = []
+        private ?string $uriTemplate = null,
+        private array $extraProperties = [],
     ) {
         if (\is_string($types)) {
             $this->types = (array) $types;
@@ -464,4 +466,20 @@ public function withGenId(bool $genId): self
 
         return $metadata;
     }
+
+    /**
+     * Whether to return the subRessource collection IRI instead of an iterable of IRI.
+     */
+    public function getUriTemplate(): ?string
+    {
+        return $this->uriTemplate;
+    }
+
+    public function withUriTemplate(?string $uriTemplate): self
+    {
+        $metadata = clone $this;
+        $metadata->uriTemplate = $uriTemplate;
+
+        return $metadata;
+    }
 }

src/Metadata/Extractor/XmlPropertyExtractor.php

@@ -72,6 +72,7 @@ protected function extractPath(string $path): void
                 'extraProperties' => $this->buildExtraProperties($property, 'extraProperties'),
                 'iris' => $this->buildArrayValue($property, 'iri'),
                 'genId' => $this->phpize($property, 'genId', 'bool'),
+                'uriTemplate' => $this->phpize($property, 'uriTemplate', 'string'),
             ];
         }
     }

src/Metadata/Extractor/YamlPropertyExtractor.php

@@ -93,6 +93,7 @@ private function buildProperties(array $resourcesYaml): void
                     'builtinTypes' => $this->buildAttribute($propertyValues, 'builtinTypes'),
                     'schema' => $this->buildAttribute($propertyValues, 'schema'),
                     'genId' => $this->phpize($propertyValues, 'genId', 'bool'),
+                    'uriTemplate' => $this->phpize($propertyValues, 'uriTemplate', 'string'),
                 ];
             }
         }

src/Metadata/Extractor/schema/properties.xsd

@@ -44,6 +44,7 @@
         <xsd:attribute name="securityPostDenormalize" type="xsd:string"/>
         <xsd:attribute name="initializable" type="xsd:boolean"/>
         <xsd:attribute name="genId" type="xsd:boolean"/>
+        <xsd:attribute name="uriTemplate" type="xsd:string"/>
     </xsd:complexType>
 
     <xsd:complexType name="types">

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

@@ -43,6 +43,7 @@ final class XmlPropertyAdapter implements PropertyAdapterInterface
         'initializable',
         'iris',
         'genId',
+        'uriTemplate',
     ];
 
     /**

src/Metadata/Tests/Extractor/Adapter/properties.xml

@@ -1,3 +1,3 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <properties xmlns="https://api-platform.com/schema/metadata/properties-3.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://api-platform.com/schema/metadata/properties-3.0            https://api-platform.com/schema/metadata/properties-3.0.xsd">
-<property name="comment" resource="ApiPlatform\Metadata\Tests\Fixtures\ApiResource\Comment" description="Comment message" readable="true" writable="true" readableLink="true" writableLink="true" required="true" identifier="false" default="Plop" example="Lorem ipsum dolor sit amet" deprecationReason="Foo" fetchable="true" fetchEager="true" push="true" security="is_granted('IS_AUTHENTICATED_ANONYMOUSLY')" securityPostDenormalize="is_granted('ROLE_CUSTOM_ADMIN')" initializable="true" genId="true"><jsonldContext><values><value name="bar"><values><value name="foo"><values><value name="bar">baz</value></values></value></values></value></values></jsonldContext><openapiContext><values><value name="foo">bar</value></values></openapiContext><jsonSchemaContext><values><value name="lorem">ipsum</value></values></jsonSchemaContext><types><type>someirischema</type><type>anotheririschema</type></types><builtinTypes><builtinType>string</builtinType></builtinTypes><schema><values><value>https://schema.org/Thing</value></values></schema><iris><iri>https://schema.org/totalPrice</iri></iris><extraProperties><values><value name="custom_property">Lorem ipsum dolor sit amet</value></values></extraProperties></property></properties>
+<property name="comment" resource="ApiPlatform\Metadata\Tests\Fixtures\ApiResource\Comment" description="Comment message" readable="true" writable="true" readableLink="true" writableLink="true" required="true" identifier="false" default="Plop" example="Lorem ipsum dolor sit amet" deprecationReason="Foo" fetchable="true" fetchEager="true" push="true" security="is_granted('IS_AUTHENTICATED_ANONYMOUSLY')" securityPostDenormalize="is_granted('ROLE_CUSTOM_ADMIN')" initializable="true" genId="true" uriTemplate="/sub-resource-get-collection"><jsonldContext><values><value name="bar"><values><value name="foo"><values><value name="bar">baz</value></values></value></values></value></values></jsonldContext><openapiContext><values><value name="foo">bar</value></values></openapiContext><jsonSchemaContext><values><value name="lorem">ipsum</value></values></jsonSchemaContext><types><type>someirischema</type><type>anotheririschema</type></types><builtinTypes><builtinType>string</builtinType></builtinTypes><schema><values><value>https://schema.org/Thing</value></values></schema><iris><iri>https://schema.org/totalPrice</iri></iris><extraProperties><values><value name="custom_property">Lorem ipsum dolor sit amet</value></values></extraProperties></property></properties>

src/Metadata/Tests/Extractor/Adapter/properties.yaml

@@ -37,3 +37,4 @@ properties:
             iris:
                 - 'https://schema.org/totalPrice'
             genId: true
+            uriTemplate: /sub-resource-get-collection

src/Metadata/Tests/Extractor/PropertyMetadataCompatibilityTest.php

@@ -72,6 +72,7 @@ final class PropertyMetadataCompatibilityTest extends TestCase
         ],
         'iris' => ['https://schema.org/totalPrice'],
         'genId' => true,
+        'uriTemplate' => '/sub-resource-get-collection',
     ];
 
     /**