fix(serializer): warn when readableLink false cannot be honored on untyped collections

src/Serializer/AbstractItemNormalizer.php

@@ -1060,6 +1060,8 @@ protected function getAttributeValue(object $object, string $attribute, ?string
             if ($type instanceof CollectionType) {
                 if (($subType = $type->getCollectionValueType()) instanceof ObjectType) {
                     $context = $this->createOperationContext($context, $subType->getClassName(), $propertyMetadata);
+                } elseif (false === $propertyMetadata->isReadableLink()) {
+                    trigger_deprecation('api-platform/core', '4.3', 'Property "%s::$%s" sets "readableLink: false" but its collection element type cannot be resolved. Declare it via PHPDoc "@return list<ClassName>" or "#[ApiProperty(nativeType: ...)]"; otherwise "readableLink: false" cannot be honored and related items will be embedded.', $object::class, $attribute);
                 }
 
                 $childContext = $this->createChildContext($context, $attribute, $format);

src/Serializer/Tests/AbstractItemNormalizerTest.php

@@ -223,6 +223,66 @@ public function testNormalizeNullableToManyRelationReturnsNull(): void
         ]));
     }
 
+    public function testNormalizeArrayBackedRelationWithReadableLinkFalseTriggersDeprecation(): void
+    {
+        if (!method_exists(PropertyInfoExtractor::class, 'getType')) {
+            $this->markTestSkipped('Requires symfony/type-info native types.');
+        }
+
+        $relatedDummy = new RelatedDummy();
+        $relatedDummy->setId(2);
+
+        $dummy = new Dummy();
+        $dummy->setName('foo');
+
+        $propertyNameCollectionFactoryProphecy = $this->prophesize(PropertyNameCollectionFactoryInterface::class);
+        $propertyNameCollectionFactoryProphecy->create(Dummy::class, Argument::type('array'))->willReturn(new PropertyNameCollection(['name', 'relatedDummies']));
+
+        $propertyMetadataFactoryProphecy = $this->prophesize(PropertyMetadataFactoryInterface::class);
+        $propertyMetadataFactoryProphecy->create(Dummy::class, 'name', Argument::type('array'))->willReturn((new ApiProperty())->withNativeType(Type::string())->withDescription('')->withReadable(true));
+        $propertyMetadataFactoryProphecy->create(Dummy::class, 'relatedDummies', Argument::type('array'))->willReturn((new ApiProperty())->withNativeType(Type::array())->withReadable(true)->withWritable(false)->withReadableLink(false));
+
+        $iriConverterProphecy = $this->prophesize(IriConverterInterface::class);
+        $iriConverterProphecy->getIriFromResource($dummy, Argument::cetera())->willReturn('/dummies/1');
+
+        $propertyAccessorProphecy = $this->prophesize(PropertyAccessorInterface::class);
+        $propertyAccessorProphecy->getValue($dummy, 'name')->willReturn('foo');
+        $propertyAccessorProphecy->getValue($dummy, 'relatedDummies')->willReturn([$relatedDummy]);
+
+        $resourceClassResolverProphecy = $this->prophesize(ResourceClassResolverInterface::class);
+        $resourceClassResolverProphecy->getResourceClass(null, Dummy::class)->willReturn(Dummy::class);
+        $resourceClassResolverProphecy->getResourceClass($dummy, null)->willReturn(Dummy::class);
+        $resourceClassResolverProphecy->isResourceClass(Dummy::class)->willReturn(true);
+
+        $serializerProphecy = $this->prophesize(SerializerInterface::class);
+        $serializerProphecy->willImplement(NormalizerInterface::class);
+        $serializerProphecy->normalize(Argument::any(), null, Argument::type('array'))->willReturn('foo');
+
+        $normalizer = new class($propertyNameCollectionFactoryProphecy->reveal(), $propertyMetadataFactoryProphecy->reveal(), $iriConverterProphecy->reveal(), $resourceClassResolverProphecy->reveal(), $propertyAccessorProphecy->reveal(), null, null, [], null, null) extends AbstractItemNormalizer {};
+        $normalizer->setSerializer($serializerProphecy->reveal());
+
+        $deprecations = [];
+        set_error_handler(static function (int $errno, string $errstr) use (&$deprecations): bool {
+            $deprecations[] = $errstr;
+
+            return true;
+        }, \E_USER_DEPRECATED);
+
+        try {
+            $normalizer->normalize($dummy, null, [
+                'resources' => [],
+            ]);
+        } finally {
+            restore_error_handler();
+        }
+
+        $matched = array_filter($deprecations, static fn (string $m): bool => str_contains($m, 'relatedDummies') && str_contains($m, Dummy::class));
+        $this->assertNotEmpty(
+            $matched,
+            \sprintf("Expected deprecation about relatedDummies. Got:\n  - %s", implode("\n  - ", $deprecations))
+        );
+    }
+
     public function testNormalizeWithSecuredProperty(): void
     {
         $dummy = new SecuredDummy();

tests/Fixtures/TestBundle/ApiResource/ReadableLinkArrayCollection/Api.php

@@ -0,0 +1,44 @@
+<?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\Tests\Fixtures\TestBundle\ApiResource\ReadableLinkArrayCollection;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\Operation;
+
+#[ApiResource(
+    shortName: 'ReadableLinkArrayCollectionApi',
+    operations: [
+        new Get(
+            uriTemplate: '/readable_link_array_collection_apis/{id}',
+            uriVariables: ['id'],
+            provider: [self::class, 'provide'],
+        ),
+    ],
+)]
+class Api
+{
+    public function __construct(
+        #[ApiProperty(identifier: true)]
+        public int $id = 1,
+        public string $label = 'default',
+    ) {
+    }
+
+    public static function provide(Operation $operation, array $uriVariables = []): self
+    {
+        return new self((int) ($uriVariables['id'] ?? 1));
+    }
+}

tests/Fixtures/TestBundle/ApiResource/ReadableLinkArrayCollection/Client.php

@@ -0,0 +1,87 @@
+<?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\Tests\Fixtures\TestBundle\ApiResource\ReadableLinkArrayCollection;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\Operation;
+
+#[ApiResource(
+    shortName: 'ReadableLinkArrayCollectionClient',
+    operations: [
+        new Get(
+            uriTemplate: '/readable_link_array_collection_clients/{id}',
+            uriVariables: ['id'],
+            provider: [self::class, 'provide'],
+        ),
+    ],
+)]
+class Client
+{
+    #[ApiProperty(identifier: true)]
+    public int $id = 1;
+
+    #[ApiProperty(readableLink: false)]
+    public ?Api $singleApi = null;
+
+    private array $typedExchangeApis = [];
+
+    private array $untypedExchangeApis = [];
+
+    /**
+     * @return list<Api>
+     */
+    #[ApiProperty(readableLink: false)]
+    public function getTypedExchangeApis(): array
+    {
+        return $this->typedExchangeApis;
+    }
+
+    /**
+     * @param list<Api> $typedExchangeApis
+     */
+    public function setTypedExchangeApis(array $typedExchangeApis): void
+    {
+        $this->typedExchangeApis = $typedExchangeApis;
+    }
+
+    #[ApiProperty(readableLink: false)]
+    public function getUntypedExchangeApis(): array
+    {
+        return $this->untypedExchangeApis;
+    }
+
+    public function setUntypedExchangeApis(array $untypedExchangeApis): void
+    {
+        $this->untypedExchangeApis = $untypedExchangeApis;
+    }
+
+    public static function provide(Operation $operation, array $uriVariables = []): self
+    {
+        $client = new self();
+        $client->id = (int) ($uriVariables['id'] ?? 1);
+        $client->singleApi = new Api(2, 'single');
+        $client->setTypedExchangeApis([
+            new Api(3, 'exchange-a'),
+            new Api(4, 'exchange-b'),
+        ]);
+        $client->setUntypedExchangeApis([
+            new Api(5, 'exchange-c'),
+            new Api(6, 'exchange-d'),
+        ]);
+
+        return $client;
+    }
+}

tests/Functional/Serializer/ReadableLinkArrayCollectionTest.php

@@ -0,0 +1,80 @@
+<?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\Tests\Functional\Serializer;
+
+use ApiPlatform\Symfony\Bundle\Test\ApiTestCase;
+use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\ReadableLinkArrayCollection\Api;
+use ApiPlatform\Tests\Fixtures\TestBundle\ApiResource\ReadableLinkArrayCollection\Client;
+use ApiPlatform\Tests\SetupClassResourcesTrait;
+
+final class ReadableLinkArrayCollectionTest extends ApiTestCase
+{
+    use SetupClassResourcesTrait;
+
+    protected static ?bool $alwaysBootKernel = false;
+
+    public static function getResources(): array
+    {
+        return [Client::class, Api::class];
+    }
+
+    public function testToOneRelationWithReadableLinkFalseRendersIri(): void
+    {
+        $response = self::createClient()->request('GET', '/readable_link_array_collection_clients/1', [
+            'headers' => ['Accept' => 'application/ld+json'],
+        ]);
+
+        $this->assertResponseIsSuccessful();
+        $body = $response->toArray();
+        $this->assertSame('/readable_link_array_collection_apis/2', $body['singleApi']);
+    }
+
+    public function testTypedArrayCollectionWithReadableLinkFalseRendersIris(): void
+    {
+        $response = self::createClient()->request('GET', '/readable_link_array_collection_clients/1', [
+            'headers' => ['Accept' => 'application/ld+json'],
+        ]);
+
+        $this->assertResponseIsSuccessful();
+        $body = $response->toArray();
+        $this->assertSame(
+            ['/readable_link_array_collection_apis/3', '/readable_link_array_collection_apis/4'],
+            $body['typedExchangeApis'],
+        );
+    }
+
+    public function testUntypedArrayCollectionWithReadableLinkFalseTriggersDeprecation(): void
+    {
+        $deprecations = [];
+        set_error_handler(static function (int $errno, string $errstr) use (&$deprecations): bool {
+            $deprecations[] = $errstr;
+
+            return true;
+        }, \E_USER_DEPRECATED);
+
+        try {
+            self::createClient()->request('GET', '/readable_link_array_collection_clients/1', [
+                'headers' => ['Accept' => 'application/ld+json'],
+            ]);
+        } finally {
+            restore_error_handler();
+        }
+
+        $matched = array_filter($deprecations, static fn (string $m): bool => str_contains($m, 'untypedExchangeApis'));
+        $this->assertNotEmpty(
+            $matched,
+            \sprintf("Expected deprecation about untypedExchangeApis. Got:\n  - %s", implode("\n  - ", $deprecations))
+        );
+    }
+}