feat: allow to output null links for haljson

Issue: #4372

Author: BacLuc

src/Hal/Serializer/ItemNormalizer.php

@@ -305,14 +305,16 @@ private function populateRelation(array $data, object $object, ?string $format,
 
             $attributeValue = $this->getAttributeValue($object, $relation['name'], $format, $childContext);
 
-            if (empty($attributeValue)) {
+            if (empty($attributeValue) && ($context[self::SKIP_NULL_TO_ONE_RELATIONS] ?? $this->defaultContext[self::SKIP_NULL_TO_ONE_RELATIONS] ?? true)) {
                 continue;
             }
 
             if ('one' === $relation['cardinality']) {
                 if ('links' === $type) {
-                    $data[$key][$relationName]['href'] = $this->getRelationIri($attributeValue);
-                    continue;
+                    if (null !== $attributeValue) {
+                        $data[$key][$relationName]['href'] = $this->getRelationIri($attributeValue);
+                        continue;
+                    }
                 }
 
                 $data[$key][$relationName] = $attributeValue;

src/Serializer/AbstractItemNormalizer.php

@@ -65,6 +65,11 @@ abstract class AbstractItemNormalizer extends AbstractObjectNormalizer
     use ContextTrait;
     use InputOutputMetadataTrait;
     use OperationContextTrait;
+    /**
+     * Flag to control whether to one relation with the value `null` should be output
+     * when normalizing or omitted.
+     */
+    public const SKIP_NULL_TO_ONE_RELATIONS = 'skip_null_to_one_relations';
 
     protected PropertyAccessorInterface $propertyAccessor;
     protected array $localCache = [];

src/Serializer/SerializerContextBuilder.php

@@ -60,6 +60,7 @@ public function createFromRequest(Request $request, bool $normalization, ?array
         $context['operation'] = $operation;
         $context['resource_class'] = $attributes['resource_class'];
         $context['skip_null_values'] ??= true;
+        $context[AbstractItemNormalizer::SKIP_NULL_TO_ONE_RELATIONS] ??= true;
         $context['iri_only'] ??= false;
         $context['request_uri'] = $request->getRequestUri();
         $context['uri'] = $request->getUri();

tests/Fixtures/TestBundle/ApiResource/Issue4372/ToOneRelationPropertyMayBeNull.php

@@ -18,6 +18,7 @@
 use ApiPlatform\Metadata\Get;
 use ApiPlatform\Metadata\GetCollection;
 use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Serializer\AbstractItemNormalizer;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
 
@@ -28,6 +29,13 @@
         ),
         new Get(
             uriTemplate: self::ITEM_ROUTE.'{._format}',
+            normalizationContext: [
+                AbstractItemNormalizer::SKIP_NULL_TO_ONE_RELATIONS => false,
+            ],
+            provider: [self::class, 'provide']
+        ),
+        new Get(
+            uriTemplate: self::ITEM_SKIP_NULL_TO_ONE_RELATION_ROUTE.'{._format}',
             provider: [self::class, 'provide']
         ),
     ],
@@ -36,6 +44,8 @@ class ToOneRelationPropertyMayBeNull
 {
     public const ROUTE = '/my-route';
     public const ITEM_ROUTE = self::ROUTE.'/{id}';
+    public const SKIP_NULL_TO_ONE_RELATION_ROUTE = '/skip-null-relation-route';
+    public const ITEM_SKIP_NULL_TO_ONE_RELATION_ROUTE = self::SKIP_NULL_TO_ONE_RELATION_ROUTE.'/{id}';
     public const ENTITY_ID = 1;
 
     /** @noinspection PhpPropertyOnlyWrittenInspection */

tests/Functional/NotSkipNullToOneRelationTest.php

@@ -66,6 +66,68 @@ public function testNullRelationsAreNotSkippedWhenConfigured(): void
 
         $this->assertResponseStatusCodeSame(200);
 
+        $this->assertJsonEquals(
+            [
+                '_links' => [
+                    'self' => [
+                        'href' => $itemIri,
+                    ],
+                    'relatedEntity' => null,
+                    'relatedEntity2' => [
+                        'href' => '/related_entities/1',
+                    ],
+                ],
+                'collection' => [
+                    [
+                        '_links' => [
+                            'self' => [
+                                'href' => '/related_entities/1',
+                            ],
+                        ],
+                        'id' => 1,
+                    ],
+                    [
+                        '_links' => [
+                            'self' => [
+                                'href' => '/related_entities/2',
+                            ],
+                        ],
+                        'id' => 2,
+                    ],
+                ],
+            ]
+        );
+    }
+
+    /**
+     * @throws TransportExceptionInterface
+     * @throws ServerExceptionInterface
+     * @throws RedirectionExceptionInterface
+     * @throws DecodingExceptionInterface
+     * @throws ClientExceptionInterface
+     * @throws \JsonException
+     */
+    public function testNullRelationsAreSkippedByDefault(): void
+    {
+        $itemIri = str_replace(
+            '{id}',
+            ToOneRelationPropertyMayBeNull::ENTITY_ID.'',
+            ToOneRelationPropertyMayBeNull::ITEM_SKIP_NULL_TO_ONE_RELATION_ROUTE
+        );
+        $this->checkRoutesAreCorrectlySetUp();
+
+        self::createClient()->request(
+            'GET',
+            $itemIri,
+            [
+                'headers' => [
+                    'accept' => 'application/hal+json',
+                ],
+            ]
+        );
+
+        $this->assertResponseStatusCodeSame(200);
+
         $this->assertJsonEquals(
             [
                 '_links' => [