Add methods to manipulate shared slices

.gitattributes

@@ -1,3 +1,11 @@
+#
+# *.http files in /test/ are response fixtures and should have CRLF line endings
+#
+/test/Integration/responses/*.http	text eol=crlf
+
+#
+# Ignores
+#
 /.cache/ export-ignore
 /.github/ export-ignore
 /.laminas-ci/ export-ignore

src/BaseClient.php

@@ -188,4 +188,105 @@ private function send(RequestInterface $request): ResponseInterface
 
         return $response;
     }
+
+    /** @inheritDoc */
+    public function fetchAllSharedSlices(): iterable
+    {
+        $response = $this->send(
+            $this->request('GET', '/slices'),
+        );
+
+        $body = Json::decodeToArray((string) $response->getBody());
+        $list = [];
+        foreach ($body as $item) {
+            Assert::isArray($item);
+            $definition = SharedSlice::fromArray($item);
+            $list[$definition->id] = $definition;
+        }
+
+        return $list;
+    }
+
+    public function createSharedSlice(SharedSlice $definition): void
+    {
+        $request = $this->request('POST', '/slices/insert')
+            ->withHeader('Content-Type', 'application/json')
+            ->withBody($this->streamFactory->createStream($definition->json));
+
+        $response = $this->send($request);
+
+        if ($response->getStatusCode() === 400) {
+            throw InvalidDefinition::invalidSlice($request, $response);
+        }
+
+        if ($response->getStatusCode() === 409) {
+            throw InsertFailed::forSlice($definition, $request, $response);
+        }
+
+        if ($response->getStatusCode() !== 201) {
+            throw UnexpectedStatusCode::withExpectedCode(201, $request, $response);
+        }
+    }
+
+    public function updateSharedSlice(SharedSlice $definition): void
+    {
+        $request = $this->request('POST', '/slices/update')
+            ->withHeader('Content-Type', 'application/json')
+            ->withBody($this->streamFactory->createStream($definition->json));
+
+        $response = $this->send($request);
+
+        if ($response->getStatusCode() === 400) {
+            throw InvalidDefinition::invalidSlice($request, $response);
+        }
+
+        if ($response->getStatusCode() === 422) {
+            throw UpdateFailed::forSlice($definition, $request, $response);
+        }
+
+        if ($response->getStatusCode() !== 204) {
+            throw UnexpectedStatusCode::withExpectedCode(204, $request, $response);
+        }
+    }
+
+    public function saveSharedSlice(SharedSlice $slice): void
+    {
+        try {
+            $current = $this->getSharedSlice($slice->id);
+        } catch (DefinitionNotFound) {
+            $this->createSharedSlice($slice);
+
+            return;
+        }
+
+        if ($slice->equals($current)) {
+            return;
+        }
+
+        $this->updateSharedSlice($slice);
+    }
+
+    public function getSharedSlice(string $id): SharedSlice
+    {
+        $request = $this->request('GET', sprintf('/slices/%s', $id));
+        $response = $this->send($request);
+
+        if ($response->getStatusCode() === 404) {
+            throw DefinitionNotFound::forSharedSlice($id, $request, $response);
+        }
+
+        return SharedSlice::fromArray(
+            Json::decodeToArray((string) $response->getBody()),
+        );
+    }
+
+    public function deleteSharedSlice(string $id): void
+    {
+        $request = $this->request('DELETE', sprintf('/slices/%s', $id));
+        $response = $this->send($request);
+
+        if ($response->getStatusCode() !== 204) {
+            throw UnexpectedStatusCode::withExpectedCode(204, $request, $response);
+        }
+    }
 }

src/Client.php

@@ -13,6 +13,8 @@ interface Client
     /**
      * Retrieve a document type definition by its identifier
      *
+     * @param non-empty-string $id
+     *
      * @throws DefinitionNotFound if there is no such type with the given id.
      * @throws Exception if any errors occur communicating with the remote API.
      */
@@ -37,7 +39,42 @@ public function fetchAllDefinitions(): iterable;
     /**
      * Deletes the definition with the given identifier
      *
+     * @param non-empty-string $id
+     *
      * @throws Exception if any errors occur communicating with the remote API.
      */
     public function deleteDefinition(string $id): void;
+
+    /**
+     * Return a list of the Shared Slices found in the remote repo
+     *
+     * @return iterable<string, SharedSlice>&Countable
+     */
+    public function fetchAllSharedSlices(): iterable;
+
+    /**
+     * Insert or update a shared slice
+     *
+     * @throws Exception
+     */
+    public function saveSharedSlice(SharedSlice $slice): void;
+
+    /**
+     * Fetch a shared slice
+     *
+     * @param non-empty-string $id
+     *
+     * @throws DefinitionNotFound if there is no such type with the given id.
+     * @throws Exception if any errors occur communicating with the remote API.
+     */
+    public function getSharedSlice(string $id): SharedSlice;
+
+    /**
+     * Deletes the shared slice with the given identifier
+     *
+     * @param non-empty-string $id
+     *
+     * @throws Exception if any errors occur communicating with the remote API.
+     */
+    public function deleteSharedSlice(string $id): void;
 }

src/Definition.php

@@ -10,6 +10,10 @@
 /** @psalm-immutable */
 final class Definition implements JsonSerializable
 {
+    /**
+     * @param non-empty-string $id
+     * @param non-empty-string $json
+     */
     private function __construct(
         private string $id,
         private string $label,
@@ -19,6 +23,10 @@ private function __construct(
     ) {
     }
 
+    /**
+     * @param non-empty-string $id
+     * @param non-empty-string $json
+     */
     public static function new(
         string $id,
         string $label,
@@ -66,6 +74,7 @@ public function jsonSerialize(): array
         ];
     }
 
+    /** @return non-empty-string */
     public function id(): string
     {
         return $this->id;
@@ -86,11 +95,13 @@ public function isActive(): bool
         return $this->active;
     }
 
+    /** @return non-empty-string */
     public function json(): string
     {
         return $this->json;
     }
 
+    /** @param non-empty-string $json */
     public function withAlteredPayload(string $json): self
     {
         $clone = clone $this;

src/Exception/DefinitionNotFound.php

@@ -22,4 +22,16 @@ public static function withIdentifier(
             $response,
         );
     }
+
+    public static function forSharedSlice(
+        string $id,
+        RequestInterface $request,
+        ResponseInterface $response,
+    ): self {
+        return self::withHttpExchange(
+            sprintf('A shared slice with the id "%s" cannot be found', $id),
+            $request,
+            $response,
+        );
+    }
 }

src/Exception/InsertFailed.php

@@ -5,6 +5,7 @@
 namespace Prismic\DocumentType\Exception;
 
 use Prismic\DocumentType\Definition;
+use Prismic\DocumentType\SharedSlice;
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
 
@@ -26,4 +27,19 @@ public static function withDefinition(
             $response,
         );
     }
+
+    public static function forSlice(
+        SharedSlice $definition,
+        RequestInterface $request,
+        ResponseInterface $response,
+    ): self {
+        return self::withHttpExchange(
+            sprintf(
+                'Failed to insert the shared slice "%s" because one already exists with that identifier',
+                $definition->id,
+            ),
+            $request,
+            $response,
+        );
+    }
 }

src/Exception/InvalidDefinition.php

@@ -17,4 +17,13 @@ public static function new(RequestInterface $request, ResponseInterface $respons
             $response,
         );
     }
+
+    public static function invalidSlice(RequestInterface $request, ResponseInterface $response): self
+    {
+        return self::withHttpExchange(
+            'The slice definition was rejected because it (most likely) has validation errors',
+            $request,
+            $response,
+        );
+    }
 }

src/Exception/UpdateFailed.php

@@ -5,6 +5,7 @@
 namespace Prismic\DocumentType\Exception;
 
 use Prismic\DocumentType\Definition;
+use Prismic\DocumentType\SharedSlice;
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
 
@@ -26,4 +27,19 @@ public static function withDefinition(
             $response,
         );
     }
+
+    public static function forSlice(
+        SharedSlice $definition,
+        RequestInterface $request,
+        ResponseInterface $response,
+    ): self {
+        return self::withHttpExchange(
+            sprintf(
+                'Failed to update the shared slice "%s" because it has not yet been created',
+                $definition->id,
+            ),
+            $request,
+            $response,
+        );
+    }
 }

src/Json.php

@@ -34,7 +34,11 @@ public static function decodeToArray(string $json): array
         }
     }
 
-    /** @param array<array-key, mixed> $parameters */
+    /**
+     * @param array<array-key, mixed> $parameters
+     *
+     * @return non-empty-string
+     */
     public static function encodeArray(array $parameters): string
     {
         try {

src/SharedSlice.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prismic\DocumentType;
+
+use function json_encode;
+
+final class SharedSlice
+{
+    /**
+     * @param non-empty-string $id
+     * @param non-empty-string $json
+     */
+    private function __construct(
+        public readonly string $id,
+        public readonly string $json,
+    ) {
+    }
+
+    /**
+     * @param non-empty-string $id
+     * @param non-empty-string $json
+     */
+    public static function new(string $id, string $json): self
+    {
+        return new self($id, $json);
+    }
+
+    /** @param array<array-key, mixed> $payload */
+    public static function fromArray(array $payload): self
+    {
+        Assert::keyExists($payload, 'id');
+        Assert::stringNotEmpty($payload['id']);
+
+        return new self($payload['id'], json_encode($payload));
+    }
+
+    public function equals(SharedSlice $other): bool
+    {
+        return $this->id === $other->id
+            && $this->json === $other->json;
+    }
+}