Merge remote-tracking branch 'origin/2.0.x' into 1.11.x-merge-up-into…

…-2.0.x_lo5L9oGr # Conflicts: # test/Unit/Document/Fragment/FactoryTest.php
netglue · Oct 31, 2024 · a14bc36 · a14bc36
2 parents bc52738 + 1adb8b5
commit a14bc36
Show file tree

Hide file tree

Showing 19 changed files with 450 additions and 11 deletions.
diff --git a/src/DefaultLinkResolver.php b/src/DefaultLinkResolver.php
@@ -15,7 +15,7 @@ public function resolve(Link $link): string|null
         }
 
         if ($link instanceof DocumentLink) {
-            return $this->resolveDocumentLink($link);
+            return $link->url() ?? $this->resolveDocumentLink($link);
         }
 
         return null;

diff --git a/src/Document.php b/src/Document.php
@@ -48,4 +48,9 @@ public function asLink(): DocumentLink;
      * Return the value object containing all of the document content fragments
      */
     public function data(): DocumentData;
+
+    /**
+     * If the api has been configured with a route for this type of document, the url might be a string
+     */
+    public function url(): string|null;
 }
diff --git a/src/Document/DocumentDataConsumer.php b/src/Document/DocumentDataConsumer.php
@@ -64,4 +64,9 @@ public function data(): DocumentData
     {
         return $this->data;
     }
+
+    public function url(): string|null
+    {
+        return $this->data->url();
+    }
 }
diff --git a/src/Document/Fragment/DocumentLink.php b/src/Document/Fragment/DocumentLink.php
@@ -21,6 +21,7 @@ private function __construct(
         private string $lang,
         private bool $isBroken,
         iterable $tags,
+        private string|null $url,
     ) {
         $this->tags = [];
         foreach ($tags as $tag) {
@@ -41,8 +42,9 @@ public static function new(
         string $lang,
         bool $isBroken = false,
         iterable $tags = [],
+        string|null $url = null,
     ): self {
-        return new self($id, $uid, $type, $lang, $isBroken, $tags);
+        return new self($id, $uid, $type, $lang, $isBroken, $tags, $url);
     }
 
     public static function withDocument(Document $document): self
@@ -54,6 +56,7 @@ public static function withDocument(Document $document): self
             $document->lang(),
             false,
             $document->tags(),
+            $document->url(),
         );
     }
 
@@ -97,4 +100,9 @@ public function isEmpty(): bool
     {
         return false;
     }
+
+    public function url(): string|null
+    {
+        return $this->url;
+    }
 }
diff --git a/src/Document/Fragment/Factory.php b/src/Document/Fragment/Factory.php
@@ -215,6 +215,7 @@ private static function linkFactory(object $data): Link
                 $lang,
                 $isBroken,
                 self::assertObjectPropertyAllString($data, 'tags'),
+                self::optionalStringProperty($data, 'url'),
             );
         }
 

diff --git a/src/Query.php b/src/Query.php
@@ -6,6 +6,7 @@
 
 use Prismic\Value\FormSpec;
 use Prismic\Value\Ref;
+use Prismic\Value\RouteResolverSpec;
 
 use function array_filter;
 use function array_map;
@@ -45,21 +46,21 @@ public function toUrl(): string
     /** @psalm-return QueryParams */
     private function mergeWithDefaults(): array
     {
-        $parameters = $this->defaultParameters();
+        $defaults = $this->defaultParameters();
         foreach ($this->parameters as $name => $value) {
             if (is_scalar($value)) {
-                $parameters[$name] = $value;
+                $defaults[$name] = $value;
                 continue;
             }
 
-            $merged = isset($parameters[$name]) && is_array($parameters[$name])
-                ? array_merge($parameters[$name], (array) $value)
+            $merged = isset($defaults[$name]) && is_array($defaults[$name])
+                ? array_merge($defaults[$name], (array) $value)
                 : $value;
 
-            $parameters[$name] = $merged;
+            $defaults[$name] = $merged;
         }
 
-        return $parameters;
+        return $defaults;
     }
 
     private function buildQuery(): string
@@ -236,6 +237,18 @@ public function ref(Ref $ref): self
         return $this->set('ref', (string) $ref);
     }
 
+    /**
+     * Override or set Route Resolvers used to return document and link urls in received payloads
+     *
+     * If the api was initialised with a `routes` parameter, the query will be pre-populated with that value.
+     *
+     * @param list<RouteResolverSpec> $routes
+     */
+    public function routes(array $routes): self
+    {
+        return $this->set('routes', Json::encode($routes));
+    }
+
     /**
      * Order results
      *

diff --git a/src/Value/DocumentData.php b/src/Value/DocumentData.php
@@ -37,6 +37,7 @@ private function __construct(
         private string $lang,
         private DateTimeImmutable $firstPublished,
         private DateTimeImmutable $lastPublished,
+        private string|null $url,
         iterable $tags,
         iterable $translations,
         private FragmentCollection $body,
@@ -75,6 +76,7 @@ public static function factory(object $data): self
             self::assertObjectPropertyIsString($data, 'lang'),
             self::assertObjectPropertyIsUtcDateTime($data, 'first_publication_date'),
             self::assertObjectPropertyIsUtcDateTime($data, 'last_publication_date'),
+            self::optionalStringProperty($data, 'url'),
             self::assertObjectPropertyAllString($data, 'tags'),
             $translations,
             $body,
@@ -147,4 +149,9 @@ public function data(): DocumentData
     {
         return $this;
     }
+
+    public function url(): string|null
+    {
+        return $this->url;
+    }
 }
diff --git a/src/Value/FormSpec.php b/src/Value/FormSpec.php
@@ -31,6 +31,12 @@ private function __construct(
         FormField ...$fields,
     ) {
         $this->fields = $fields;
+
+        if ($this->hasField('routes')) {
+            return;
+        }
+
+        $this->fields[] = FormField::new('routes', FormField::TYPE_STRING, false, null);
     }
 
     public static function factory(string $id, object $object): self
@@ -107,7 +113,7 @@ public function field(string $name): FormField
     }
 
     /**
-     * @return FormField[]
+     * @return Traversable<array-key, FormField>
      * @psalm-return ArrayIterator<array-key, FormField>
      */
     public function getIterator(): Traversable

diff --git a/src/Value/RouteResolverSpec.php b/src/Value/RouteResolverSpec.php
@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prismic\Value;
+
+use JsonSerializable;
+use Prismic\Json;
+use Stringable;
+
+use const JSON_FORCE_OBJECT;
+
+final class RouteResolverSpec implements JsonSerializable, Stringable
+{
+    /** @param array<string, string> $resolvers */
+    public function __construct(
+        private string $type,
+        private string $path,
+        private array $resolvers,
+    ) {
+    }
+
+    public function __toString(): string
+    {
+        return Json::encode($this, JSON_FORCE_OBJECT);
+    }
+
+    /** @return array{type: string, path: string, resolvers: array<string, string>} */
+    public function jsonSerialize(): array
+    {
+        return [
+            'type' => $this->type,
+            'path' => $this->path,
+            'resolvers' => $this->resolvers,
+        ];
+    }
+
+    /** @param array{type: string, path: string, resolvers: array<string, string>} $data */
+    public static function __set_state(array $data): self
+    {
+        return new self(
+            $data['type'],
+            $data['path'],
+            $data['resolvers'],
+        );
+    }
+}
diff --git a/test/Unit/DefaultLinkResolverTest.php b/test/Unit/DefaultLinkResolverTest.php
@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PrismicTest;
+
+use PHPUnit\Framework\TestCase;
+use Prismic\DefaultLinkResolver;
+use Prismic\Document\Fragment\DocumentLink;
+use Prismic\Document\Fragment\MediaLink;
+use Prismic\Link;
+
+class DefaultLinkResolverTest extends TestCase
+{
+    private DefaultLinkResolver $linkResolver;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->linkResolver = new class extends DefaultLinkResolver {
+            protected function resolveDocumentLink(DocumentLink $link): string|null
+            {
+                return '/some/url';
+            }
+        };
+    }
+
+    public function testMediaUrlsReturnTheExpectedUrl(): void
+    {
+        $media = MediaLink::new('/foo', 'whatever.jpg', 1234);
+
+        self::assertSame('/foo', $this->linkResolver->resolve($media));
+    }
+
+    public function testDocLinksWillYieldStoredUrlWhenPresent(): void
+    {
+        $docLink = DocumentLink::new('id', 'uid', 'foo', 'en-gb', false, [], '/special');
+
+        self::assertSame('/special', $this->linkResolver->resolve($docLink));
+    }
+
+    public function testDocLinksWillUseCustomResolveWhenNull(): void
+    {
+        $docLink = DocumentLink::new('id', 'uid', 'foo', 'en-gb', false, [], null);
+
+        self::assertSame('/some/url', $this->linkResolver->resolve($docLink));
+    }
+
+    public function testUnknownLinkTypesWillYieldNull(): void
+    {
+        $link = $this->createMock(Link::class);
+
+        self::assertNull($this->linkResolver->resolve($link));
+    }
+}
diff --git a/test/Unit/Document/DocumentDataConsumerTest.php b/test/Unit/Document/DocumentDataConsumerTest.php
@@ -44,6 +44,7 @@ public function testProxyMethods(): void
         $this->assertSame($this->document->type(), $this->subject->type());
         $this->assertSame($this->document->tags(), $this->subject->tags());
         $this->assertSame($this->document->lang(), $this->subject->lang());
+        $this->assertSame($this->document->url(), $this->subject->url());
         $this->assertSame($this->document->firstPublished(), $this->subject->firstPublished());
         $this->assertSame($this->document->lastPublished(), $this->subject->lastPublished());
         $this->assertSame($this->document->translations(), $this->subject->translations());

diff --git a/test/Unit/Document/Fragment/DocumentLinkTest.php b/test/Unit/Document/Fragment/DocumentLinkTest.php
@@ -34,7 +34,29 @@ public function testConstructor(): DocumentLink
             false,
             ['a', 'b'],
         );
-        $this->expectNotToPerformAssertions();
+        self::assertTrue(true);
+
+        return $link;
+    }
+
+    /** @depends testConstructor */
+    public function testThatCastingALinkToAStringWillYieldItsId(DocumentLink $link): void
+    {
+        self::assertSame('id', (string) $link);
+    }
+
+    public function testConstructorWithUrl(): DocumentLink
+    {
+        $link = DocumentLink::new(
+            'id',
+            'uid',
+            'type',
+            'en-gb',
+            false,
+            ['a', 'b'],
+            '/some/url',
+        );
+        self::assertTrue(true);
 
         return $link;
     }
@@ -81,4 +103,16 @@ public function testThatTagsHaveExpectedMembers(DocumentLink $link): void
         $this->assertContainsEquals('a', $link->tags());
         $this->assertContainsEquals('b', $link->tags());
     }
+
+    /** @depends testConstructor */
+    public function testTheLinkMayHaveAUrlAndItIsNullByDefault(DocumentLink $link): void
+    {
+        self::assertNull($link->url());
+    }
+
+    /** @depends testConstructorWithUrl */
+    public function testThatUrlReturnsTheExpectedValue(DocumentLink $link): void
+    {
+        self::assertSame('/some/url', $link->url());
+    }
 }