Support empty collections in _embedded section

docs/book/v2/links-and-resources.md

@@ -198,4 +198,42 @@ $resource = $resource->withLink($link);
 $resource = $resource->withoutLink($link);
 ```
 
+To maintain consistency in the structure of the response, you may choose to embed both non-empty and empty collections within the `_embedded` section. This can be achieved by enabling the `embed-empty-collections` configuration option.
+
+To enable this feature, modify the configuration file as follows:
+
+```php
+return [
+    'mezzio-hal' => [
+        'embed-empty-collections' => false, // (default: false for compatibility reasons)
+        'metadata-factories' => [...],
+        'resource-generator' => [...],
+    ],
+];
+```
+
+The default setting of `false` ensures compatibility with existing API endpoints and prevents potential test failures.
+
+When `embed-empty-collections` is set to `false`, the representation will be as follows:
+
+**`empty-contacts-collection-not-embedded.json`**
+
+```json
+{
+  "contacts": []
+}
+```
+
+However, when `embed-empty-collections` is set to `true`, the representation will be as follows:
+
+**`empty-contacts-collection-embedded.json`**
+
+``` json
+{
+  "_embedded": {
+    "contacts": []
+  }
+}
+```
+
 With these tools, you can describe any resource you want to represent.

src/ConfigProvider.php

@@ -69,15 +69,16 @@ public function getDependencies(): array
     public function getHalConfig(): array
     {
         return [
-            'resource-generator' => [
+            'embed-empty-collections' => false,
+            'resource-generator'      => [
                 'strategies' => [ // The registered strategies and their metadata types
                     RouteBasedCollectionMetadata::class => RouteBasedCollectionStrategy::class,
                     RouteBasedResourceMetadata::class   => RouteBasedResourceStrategy::class,
                     UrlBasedCollectionMetadata::class   => UrlBasedCollectionStrategy::class,
                     UrlBasedResourceMetadata::class     => UrlBasedResourceStrategy::class,
                 ],
             ],
-            'metadata-factories' => [ // The factories for the metadata types
+            'metadata-factories'      => [ // The factories for the metadata types
                 RouteBasedCollectionMetadata::class => RouteBasedCollectionMetadataFactory::class,
                 RouteBasedResourceMetadata::class   => RouteBasedResourceMetadataFactory::class,
                 UrlBasedCollectionMetadata::class   => UrlBasedCollectionMetadataFactory::class,

src/HalResource.php

@@ -42,20 +42,25 @@ class HalResource implements EvolvableLinkProviderInterface, JsonSerializable
     /** @var array<array-key, self|array<array-key, self>> */
     private $embedded = [];
 
+    private bool $embedEmptyCollections;
+
     /**
      * @param array $data
      * @param LinkInterface[] $links
      * @param HalResource[][] $embedded
      */
-    public function __construct(array $data = [], array $links = [], array $embedded = [])
-    {
+    public function __construct(
+        array $data = [],
+        array $links = [],
+        array $embedded = [],
+        bool $embedEmptyCollections = false
+    ) {
+        $this->embedEmptyCollections = $embedEmptyCollections;
+
         $context = self::class;
         array_walk($data, function ($value, $name) use ($context) {
             $this->validateElementName($name, $context);
-            if (
-                ! empty($value)
-                && ($value instanceof self || $this->isResourceCollection($value))
-            ) {
+            if ($value instanceof self || $this->isResourceCollection($value)) {
                 $this->embedded[$name] = $value;
                 return;
             }
@@ -142,8 +147,7 @@ public function withElement(string $name, $value): HalResource
         $this->validateElementName($name, __METHOD__);
 
         if (
-            ! empty($value)
-            && ($value instanceof self || $this->isResourceCollection($value))
+            $value instanceof self || $this->isResourceCollection($value)
         ) {
             return $this->embed($name, $value);
         }
@@ -395,6 +399,10 @@ private function isResourceCollection($value): bool
             return false;
         }
 
+        if ($this->embedEmptyCollections && $value === []) {
+            return true;
+        }
+
         return array_reduce($value, static function ($isResource, $item) {
             return $isResource && $item instanceof self;
         }, true);

src/ResourceGenerator.php

@@ -94,7 +94,13 @@ public function getStrategies(): array
 
     public function fromArray(array $data, ?string $uri = null): HalResource
     {
-        $resource = new HalResource($data);
+        /** @psalm-suppress MixedArrayAccess */
+        $embedEmptyCollections =
+            $this->hydrators->has('config') &&
+            $this->hydrators->get('config')['mezzio-hal']['embed-empty-collections'] ??
+            false;
+
+        $resource = new HalResource($data, [], [], $embedEmptyCollections);
 
         if (null !== $uri) {
             return $resource->withLink(new Link('self', $uri));

test/Fixture/empty-contacts-collection.json

@@ -0,0 +1,10 @@
+{
+  "_links": {
+    "self": {
+      "href": "/api/contacts"
+    }
+  },
+  "_embedded": {
+    "contacts": []
+  }
+}

test/Fixture/non-empty-contacts-collection.json

@@ -0,0 +1,21 @@
+{
+  "_links": {
+    "self": {
+      "href": "/api/contacts"
+    }
+  },
+  "_embedded": {
+    "contacts": [
+      {
+        "id": 1,
+        "name": "John",
+        "email": "john@example.com"
+      },
+      {
+        "id": 2,
+        "name": "Jane",
+        "email": "jane@example.com"
+      }
+    ]
+  }
+}

test/Fixture/null-contacts-collection.json

@@ -0,0 +1,8 @@
+{
+  "contacts": null,
+  "_links": {
+    "self": {
+      "href": "/api/contacts"
+    }
+  }
+}

test/HalResourceTest.php

@@ -4,13 +4,17 @@
 
 namespace MezzioTest\Hal;
 
+use Generator;
 use InvalidArgumentException;
 use Mezzio\Hal\HalResource;
 use Mezzio\Hal\Link;
 use PHPUnit\Framework\TestCase;
 use RuntimeException;
 
 use function array_values;
+use function file_get_contents;
+use function is_array;
+use function json_decode;
 
 class HalResourceTest extends TestCase
 {
@@ -235,13 +239,22 @@ public function testWithElementProxiesToEmbedIfResourceCollectionValueProvided()
         $this->assertEquals(['foo' => $collection], $new->getElements());
     }
 
-    public function testWithElementDoesNotProxyToEmbedIfAnEmptyArrayValueIsProvided(): void
+    public function testWithElementWillEmbedAnEmptyArrayIfAnEmptyArrayValueIsProvided(): void
     {
-        $resource = new HalResource(['foo' => 'bar']);
+        $resource = new HalResource(['foo' => 'bar'], [], [], true);
         $new      = $resource->withElement('bar', []);
 
         $representation = $new->toArray();
-        $this->assertEquals(['foo' => 'bar', 'bar' => []], $representation);
+        self::assertSame(['foo' => 'bar', '_embedded' => ['bar' => []]], $representation);
+    }
+
+    public function testWithElementDoesNotProxyToEmbedIfNullValueIsProvided(): void
+    {
+        $resource = new HalResource(['foo' => 'bar'], [], [], true);
+        $new      = $resource->withElement('bar', null);
+
+        $representation = $new->toArray();
+        self::assertSame(['foo' => 'bar', 'bar' => null], $representation);
     }
 
     /**
@@ -636,4 +649,108 @@ public function testAllowsForcingLinkToAggregateAsACollection(): void
 
         $this->assertEquals($expected, $resource->toArray());
     }
+
+    private function fixture(string $file): array
+    {
+        $contents = file_get_contents(__DIR__ . '/Fixture/' . $file);
+
+        if ($contents === false) {
+            throw new RuntimeException('Failed to read fixture file: ' . $file);
+        }
+
+        $json = json_decode($contents, true);
+        if (! is_array($json)) {
+            throw new RuntimeException('Failed to json_decode fixture file: ' . $file);
+        }
+
+        return $json;
+    }
+
+    /**
+     * @return Generator<string,array<array-key,array<array-key,HalResource>>>
+     */
+    public static function nonEmptyCollectionDataProvider(): Generator
+    {
+        yield from [
+            'collection' => [
+                [
+                    (new HalResource())->withElements([
+                        'id'    => 1,
+                        'name'  => 'John',
+                        'email' => 'john@example.com',
+                    ]),
+                    (new HalResource())->withElements([
+                        'id'    => 2,
+                        'name'  => 'Jane',
+                        'email' => 'jane@example.com',
+                    ]),
+                ],
+            ],
+        ];
+    }
+
+    /**
+     * @return Generator<'array',list{array<never,never>},mixed,void>
+     */
+    public static function emptyCollectionDataProvider(): Generator
+    {
+        yield from [
+            'array' => [[]],
+        ];
+    }
+
+    /**
+     * @dataProvider emptyCollectionDataProvider
+     */
+    public function testEmptyCollection(mixed $collection): void
+    {
+        $resource = (new HalResource([], [], [], true))
+            ->withLink(new Link('self', '/api/contacts'))
+            ->withElements(['contacts' => $collection]);
+
+        self::assertSame(
+            $this->fixture('empty-contacts-collection.json'),
+            $resource->toArray()
+        );
+    }
+
+    /**
+     * @dataProvider nonEmptyCollectionDataProvider
+     */
+    public function testNonEmptyCollection(mixed $collection): void
+    {
+        $resource = (new HalResource())
+            ->withLink(new Link('self', '/api/contacts'))
+            ->withElements(['contacts' => $collection]);
+
+        self::assertSame(
+            $this->fixture('non-empty-contacts-collection.json'),
+            $resource->toArray()
+        );
+    }
+
+    /**
+     * @return Generator<'null',list{null},mixed,void>
+     */
+    public static function nullCollectionDataProvider(): Generator
+    {
+        yield from [
+            'null' => [null],
+        ];
+    }
+
+    /**
+     * @dataProvider nullCollectionDataProvider
+     */
+    public function testNullCollection(mixed $collection): void
+    {
+        $resource = (new HalResource([], [], [], true))
+            ->withLink(new Link('self', '/api/contacts'))
+            ->withElements(['contacts' => $collection]);
+
+        self::assertSame(
+            $this->fixture('null-contacts-collection.json'),
+            $resource->toArray()
+        );
+    }
 }

test/ResourceGeneratorTest.php

@@ -110,6 +110,9 @@ public function testCanGenerateResourceWithSelfLinkFromArrayData(): void
             'foo' => 'bar',
             'bar' => 'baz',
         ];
+
+        $this->hydrators->has('config')->willReturn(false);
+
         $this->linkGenerator->fromRoute()->shouldNotBeCalled();
         $this->metadataMap->has()->shouldNotBeCalled();