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,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KTXF\Preview;
+
+use Closure;
+use InvalidArgumentException;
+use KTXF\Resource\BinaryResource;
+
+final readonly class PreviewSource
+{
+    public string $mimeType;
+
+    /**
+     * @param Closure(): BinaryResource $resourceFactory
+     */
+    public function __construct(
+        public string $sourceType,
+        public string $identity,
+        public string $signature,
+        string $mimeType,
+        public ?int $size,
+        public Closure $resourceFactory,
+        public ?string $selector = null,
+    ) {
+        if ($this->sourceType === '' || $this->identity === '' || $this->signature === '') {
+            throw new InvalidArgumentException('Preview sources require a type, identity, and content signature');
+        }
+        if ($this->size !== null && $this->size < 0) {
+            throw new InvalidArgumentException('Preview source size cannot be negative');
+        }
+        if ($this->selector === '') {
+            throw new InvalidArgumentException('Preview source selectors must be null or non-empty');
+        }
+        $this->mimeType = MimeType::normalize($mimeType);
+    }
+
+    public function open(): BinaryResource
+    {
+        $resource = ($this->resourceFactory)();
+        if (!$resource instanceof BinaryResource) {
+            throw new PreviewException('Preview source factory did not return a BinaryResource');
+        }
+        return $resource;
+    }
+}