feat(preview): add shared preview provider contracts

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>
2026-08-28 23:51:29 -04:00
parent 96fbdbab90
commit 30a8eddf06
10 changed files with 318 additions and 0 deletions
@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Preview;
+
+use InvalidArgumentException;
+
+final readonly class PreviewRequest
+{
+    public string $preferredMimeType;
+
+    public function __construct(
+        public string $variant,
+        public int $maxWidth,
+        public int $maxHeight,
+        string $preferredMimeType,
+        public int $quality,
+        public ?int $page = null,
+        public ?float $timestamp = null,
+    ) {
+        if (preg_match('/^[a-z][a-z0-9-]*$/', $this->variant) !== 1) {
+            throw new InvalidArgumentException('Preview variant must use lowercase letters, numbers, and hyphens');
+        }
+        if ($this->maxWidth < 1 || $this->maxHeight < 1) {
+            throw new InvalidArgumentException('Preview dimensions must be positive');
+        }
+        if ($this->quality < 1 || $this->quality > 100) {
+            throw new InvalidArgumentException('Preview quality must be between 1 and 100');
+        }
+        if ($this->page !== null && $this->page < 1) {
+            throw new InvalidArgumentException('Preview page numbers start at 1');
+        }
+        if ($this->timestamp !== null && $this->timestamp < 0) {
+            throw new InvalidArgumentException('Preview timestamps cannot be negative');
+        }
+        $this->preferredMimeType = MimeType::normalize($preferredMimeType);
+    }
+
+    /**
+     * Fixed-order scalar representation for cache-key generation.
+     *
+     * @return array{variant:string,maxWidth:int,maxHeight:int,preferredMimeType:string,quality:int,page:?int,timestamp:?float}
+     */
+    public function normalized(): array
+    {
+        return [
+            'variant' => $this->variant,
+            'maxWidth' => $this->maxWidth,
+            'maxHeight' => $this->maxHeight,
+            'preferredMimeType' => $this->preferredMimeType,
+            'quality' => $this->quality,
+            'page' => $this->page,
+            'timestamp' => $this->timestamp,
+        ];
+    }
+}