Enhancement: Automatic Relation Resolution

src/Bridge/Faker/Generator.php

@@ -20,19 +20,20 @@
 /**
  * @author Silas Joisten <[email protected]>
  *
- * @method array assetResponse(array $overrides = [])
- * @method array datasourceDimensionResponse(array $overrides = [])
- * @method array datasourceEntriesResponse(array $overrides = [])
- * @method array datasourceEntryResponse(array $overrides = [])
- * @method array datasourceResponse(array $overrides = [])
- * @method array datasourcesResponse(array $overrides = [])
- * @method array linkAlternateResponse(array $overrides = [])
- * @method array linkResponse(array $overrides = [])
- * @method array linksResponse(array $overrides = [])
- * @method array spaceResponse(array $overrides = [])
- * @method array storiesResponse(array $overrides = [])
- * @method array storyResponse(array $overrides = [])
- * @method array tagsResponse(array $overrides = [])
+ * @method array  assetResponse(array $overrides = [])
+ * @method array  datasourceDimensionResponse(array $overrides = [])
+ * @method array  datasourceEntriesResponse(array $overrides = [])
+ * @method array  datasourceEntryResponse(array $overrides = [])
+ * @method array  datasourceResponse(array $overrides = [])
+ * @method array  datasourcesResponse(array $overrides = [])
+ * @method array  linkAlternateResponse(array $overrides = [])
+ * @method array  linkResponse(array $overrides = [])
+ * @method array  linksResponse(array $overrides = [])
+ * @method string relation()
+ * @method array  spaceResponse(array $overrides = [])
+ * @method array  storiesResponse(array $overrides = [])
+ * @method array  storyResponse(array $overrides = [])
+ * @method array  tagsResponse(array $overrides = [])
  */
 final class Generator extends BaseGenerator
 {

src/Bridge/Faker/Provider/StoryblokProvider.php

@@ -503,4 +503,13 @@ public function assetResponse(array $overrides = []): array
             $overrides,
         );
     }
+
+    public function relation(): string
+    {
+        return \sprintf(
+            '%s.%s',
+            $this->generator->word(),
+            $this->generator->word(),
+        );
+    }
 }

src/Domain/Value/Resolver/Relation.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of Storyblok-Api.
+ *
+ * (c) SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Domain\Value\Resolver;
+
+use OskarStark\Value\TrimmedNonEmptyString;
+use Webmozart\Assert\Assert;
+
+/**
+ * @author Silas Joisten <[email protected]>
+ */
+final readonly class Relation
+{
+    public function __construct(
+        public string $value,
+    ) {
+        TrimmedNonEmptyString::fromString($value);
+        Assert::regex($value, '/^([a-zA-Z].+)\.([a-zA-Z].+)$/');
+    }
+}

src/Domain/Value/Resolver/RelationCollection.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of Storyblok-Api.
+ *
+ * (c) SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Domain\Value\Resolver;
+
+/**
+ * @author Silas Joisten <[email protected]>
+ *
+ * @implements \IteratorAggregate<int, Relation>
+ */
+final class RelationCollection implements \Countable, \IteratorAggregate
+{
+    /**
+     * @var list<Relation>
+     */
+    private array $items = [];
+
+    /**
+     * @param list<Relation> $items
+     */
+    public function __construct(
+        array $items = [],
+    ) {
+        foreach ($items as $item) {
+            $this->add($item);
+        }
+    }
+
+    /**
+     * @return \Traversable<int, Relation>
+     */
+    public function getIterator(): \Traversable
+    {
+        return new \ArrayIterator($this->items);
+    }
+
+    public function count(): int
+    {
+        return \count($this->items);
+    }
+
+    public function add(Relation $relation): void
+    {
+        if ($this->has($relation)) {
+            return;
+        }
+
+        $this->items[] = $relation;
+    }
+
+    public function has(Relation $relation): bool
+    {
+        foreach ($this->items as $item) {
+            if ($item->value === $relation->value) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    public function remove(Relation $relation): void
+    {
+        foreach ($this->items as $key => $item) {
+            if ($item->value === $relation->value) {
+                unset($this->items[$key]);
+
+                break;
+            }
+        }
+    }
+
+    public function toString(): string
+    {
+        return implode(',', array_map(static fn (Relation $relation): string => $relation->value, $this->items));
+    }
+}

src/Request/StoriesRequest.php

@@ -19,6 +19,7 @@
 use Storyblok\Api\Domain\Value\Field\FieldCollection;
 use Storyblok\Api\Domain\Value\Filter\FilterCollection;
 use Storyblok\Api\Domain\Value\IdCollection;
+use Storyblok\Api\Domain\Value\Resolver\RelationCollection;
 use Storyblok\Api\Domain\Value\Tag\TagCollection;
 use Webmozart\Assert\Assert;
 
@@ -38,6 +39,7 @@ public function __construct(
         public ?FieldCollection $excludeFields = null,
         public ?TagCollection $withTags = null,
         public ?IdCollection $excludeIds = null,
+        public ?RelationCollection $withRelations = null,
         public ?Version $version = null,
     ) {
         Assert::stringNotEmpty($language);
@@ -85,6 +87,10 @@ public function toArray(): array
             $array['excluding_ids'] = $this->excludeIds->toString();
         }
 
+        if (null !== $this->withRelations && $this->withRelations->count() > 0) {
+            $array['resolve_relations'] = $this->withRelations->toString();
+        }
+
         if (null !== $this->version) {
             $array['version'] = $this->version->value;
         }

src/Request/StoryRequest.php

@@ -14,6 +14,7 @@
 namespace Storyblok\Api\Request;
 
 use Storyblok\Api\Domain\Value\Dto\Version;
+use Storyblok\Api\Domain\Value\Resolver\RelationCollection;
 use Webmozart\Assert\Assert;
 
 /**
@@ -24,6 +25,7 @@
     public function __construct(
         public string $language = 'default',
         public ?Version $version = null,
+        public ?RelationCollection $withRelations = null,
     ) {
         Assert::stringNotEmpty($language);
     }
@@ -32,6 +34,7 @@ public function __construct(
      * @return array{
      *     language: string,
      *     version?: string,
+     *     resolve_relations?: string,
      * }
      */
     public function toArray(): array
@@ -44,6 +47,10 @@ public function toArray(): array
             $array['version'] = $this->version->value;
         }
 
+        if (null !== $this->withRelations && $this->withRelations->count() > 0) {
+            $array['resolve_relations'] = $this->withRelations->toString();
+        }
+
         return $array;
     }
 }

src/Resolver/ResolverInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of Storyblok-Api.
+ *
+ * (c) SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Resolver;
+
+/**
+ * @author Silas Joisten <[email protected]>
+ */
+interface ResolverInterface
+{
+    /**
+     * Resolves relations in the target content using the given relations collection.
+     *
+     * @param array<string, mixed>             $target    the target story content containing UUIDs to resolve
+     * @param array<int, array<string, mixed>> $relations the target story content containing UUIDs to resolve
+     *
+     * @return array<string, mixed>
+     */
+    public function resolve(array $target, array $relations): array;
+}

src/Resolver/StoryResolver.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of Storyblok-Api.
+ *
+ * (c) SensioLabs Deutschland <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Storyblok\Api\Resolver;
+
+use Webmozart\Assert\Assert;
+
+/**
+ * @author Silas Joisten <[email protected]>
+ */
+final readonly class StoryResolver implements ResolverInterface
+{
+    public function resolve(array $target, array $relations): array
+    {
+        $relationMap = [];
+
+        foreach ($relations as $key => $relation) {
+            Assert::keyExists($relation, 'uuid');
+            Assert::uuid($relation['uuid']);
+            $relationMap[$relation['uuid']] = $relation;
+
+            // There is a limit of possible resolvable relations.
+            // @see https://www.storyblok.com/docs/api/content-delivery/v2/stories/retrieve-a-single-story
+            if (50 === $key) {
+                break;
+            }
+        }
+
+        foreach ($target as &$value) {
+            if (\is_string($value) && \array_key_exists($value, $relationMap)) {
+                $value = $relationMap[$value];
+
+                continue;
+            }
+
+            if (\is_array($value)) {
+                $value = $this->resolve($value, $relations);
+            }
+        }
+
+        return $target;
+    }
+}

src/Response/StoriesResponse.php

@@ -29,7 +29,7 @@
     public int $cv;
 
     /**
-     * @var list<string>
+     * @var list<array<string, mixed>>
      */
     public array $rels;
 

src/Response/StoryResponse.php

@@ -27,7 +27,7 @@
     public int $cv;
 
     /**
-     * @var list<array<mixed>>
+     * @var list<array<string, mixed>>
      */
     public array $rels;