feat: Introduce allByUuids() (#35)

Author: silasjoisten

README.md

@@ -324,6 +324,22 @@ $response = $storiesApi->allByContentType('custom_content_type', new StoriesRequ
 ));
 ```
 
+### Get multiple stories by multiple uuid's (`array`)
+
+```php
+use Storyblok\Api\StoriesApi;
+use Storyblok\Api\StoryblokClient;
+use Storyblok\Api\Request\StoriesRequest;
+use Storyblok\Api\Domain\Value\Uuid;
+
+$client = new StoryblokClient(/* ... */);
+
+$storiesApi = new StoriesApi($client);
+$response = $storiesApi->allByUuids([new Uuid(/** ... */), new Uuid(/** ... */)], new StoriesRequest(
+    language: 'de',
+));
+```
+
 ### Get by uuid (`Storyblok\Api\Domain\Value\Uuid`)
 
 ```php

src/StoriesApi.php

@@ -81,6 +81,35 @@ public function allByContentType(string $contentType, ?StoriesRequest $request =
         );
     }
 
+    public function allByUuids(array $uuids, bool $keepOrder = true, ?StoriesRequest $request = null): StoriesResponse
+    {
+        Assert::allIsInstanceOf($uuids, Uuid::class);
+
+        $request ??= new StoriesRequest();
+
+        $uuids = \implode(',', \array_map(static fn (Uuid $uuid) => $uuid->value, $uuids));
+
+        $query = ['by_uuids' => $uuids];
+
+        if ($keepOrder) {
+            $query = ['by_uuids_ordered' => $uuids];
+        }
+
+        $response = $this->client->request('GET', self::ENDPOINT, [
+            'query' => [
+                ...$request->toArray(),
+                ...$query,
+                'version' => null !== $request->version ? $request->version->value : $this->version->value,
+            ],
+        ]);
+
+        return new StoriesResponse(
+            Total::fromHeaders($response->getHeaders()),
+            $request->pagination,
+            $response->toArray(),
+        );
+    }
+
     public function bySlug(string $slug, ?StoryRequest $request = null): StoryResponse
     {
         Assert::stringNotEmpty($slug);

src/StoriesApiInterface.php

@@ -31,6 +31,11 @@ public function all(?StoriesRequest $request = null): StoriesResponse;
 
     public function allByContentType(string $contentType, ?StoriesRequest $request = null): StoriesResponse;
 
+    /**
+     * @param Uuid[] $uuids
+     */
+    public function allByUuids(array $uuids, bool $keepOrder = true, ?StoriesRequest $request = null): StoriesResponse;
+
     public function bySlug(string $slug, ?StoryRequest $request = null): StoryResponse;
 
     public function byUuid(Uuid $uuid, ?StoryRequest $request = null): StoryResponse;

src/StoriesResolvedApi.php

@@ -84,6 +84,32 @@ public function allByContentType(string $contentType, ?StoriesRequest $request =
         );
     }
 
+    public function allByUuids(array $uuids, bool $keepOrder = true, ?StoriesRequest $request = null): StoriesResponse
+    {
+        $response = $this->storiesApi->allByUuids($uuids, $keepOrder, $request);
+
+        if (null === $request || 0 === $request->withRelations->count()) {
+            return $response;
+        }
+
+        $stories = [];
+
+        foreach ($response->stories as $story) {
+            $stories[] = $this->resolver->resolve($story, $response->rels);
+        }
+
+        return new StoriesResponse(
+            $response->total,
+            $response->pagination,
+            [
+                'cv' => $response->cv,
+                'rels' => $response->rels,
+                'links' => $response->links,
+                'stories' => $stories,
+            ],
+        );
+    }
+
     public function bySlug(string $slug, ?StoryRequest $request = null): StoryResponse
     {
         $response = $this->storiesApi->bySlug($slug, $request);

tests/Integration/StoriesApiTest.php

@@ -61,6 +61,21 @@ public function allStoriesByContentTypeAreRetrievedSuccessfully(): void
         self::assertSame(1, $response->total->value);
     }
 
+    #[Test]
+    public function allStoriesByUuidsAreRetrievedSuccessfully(): void
+    {
+        $client = StoryblokFakeClient::willRespond(
+            self::faker()->storiesResponse(),
+            ['total' => 1],
+        );
+        $api = new StoriesApi($client);
+
+        $response = $api->allByUuids([new Uuid(self::faker()->uuid())]);
+
+        self::assertInstanceOf(StoriesResponse::class, $response);
+        self::assertSame(1, $response->total->value);
+    }
+
     #[Test]
     public function storyBySlugIsRetrievedSuccessfully(): void
     {