Add ability to define JSON serialize key for closure based images

src/Exceptions/ImageSerializationException.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace Enflow\DocumentReplacer\Exceptions;
+
+use Exception;
+
+class ImageSerializationException extends Exception
+{
+    public static function noKeyDefined(): self
+    {
+        return new static('Image JSON serialization failed. A "key" is required to create a unique JSON key.');
+    }
+}

src/ValueTypes/Image.php

@@ -3,15 +3,19 @@
 namespace Enflow\DocumentReplacer\ValueTypes;
 
 use Closure;
+use Enflow\DocumentReplacer\Exceptions\ImageSerializationException;
+use JsonSerializable;
 
-class Image
+class Image implements JsonSerializable
 {
+    private ?string $key = null; // Caching key
     private ?bool $ratio = null;
     private ?int $width = null;
     private ?int $height = null;
 
     private function __construct(private Closure|string $image)
     {
+
     }
 
     public static function forPath(string $path): self
@@ -63,6 +67,13 @@ public function signature(): string
         return md5_file($this->path());
     }
 
+    public function key(string $key): self
+    {
+        $this->key = $key;
+
+        return $this;
+    }
+
     public function width(int $width): self
     {
         $this->width = $width;
@@ -94,4 +105,18 @@ public function replacements(): array
             'ratio' => $this->ratio,
         ];
     }
+
+    public function jsonSerialize(): mixed
+    {
+        if ($this->image instanceof Closure && empty($this->key)) {
+            throw ImageSerializationException::noKeyDefined();
+        }
+
+        return [
+            'key' => $this->key,
+            'width' => $this->width,
+            'height' => $this->height,
+            'ratio' => $this->ratio,
+        ];
+    }
 }

tests/ImageValueTypeTest.php

@@ -2,6 +2,7 @@
 
 namespace Enflow\DocumentReplacer\Test;
 
+use Enflow\DocumentReplacer\Exceptions\ImageSerializationException;
 use Enflow\DocumentReplacer\ValueTypes\Image;
 use PHPUnit\Framework\TestCase;
 
@@ -46,6 +47,26 @@ public function test_image_create_lazy()
         );
     }
 
+    public function test_image_lazy_throws_exception_when_no_key_is_defined()
+    {
+        $this->expectException(ImageSerializationException::class);
+
+        json_encode(
+            Image::lazy(function () {
+                return Image::forBinary(base64_decode('iVBORw0KGgoAAAANSUhEUgAAABQAAAAVCAIAAADJt1n/AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAB8SURBVDhP3YxBDoAgDAR5iEf//zPfgCutCGwp4MXEyZI0W6bh2PaYyMM8Aa/0l05UsjDvGzIoG+fWJQPHfyMDKccy4E9oOLpLeLLQ9OWJRwamz2VXNqPrm1xWMjB/M56coy0hK0PWKdHz5fRABj0f/Efm6I5o5SW+kmM8AS/fakEk7YJkAAAAAElFTkSuQmCC'));
+            })->width(100)
+        );
+    }
+
+    public function test_image_lazy_serializes_key_to_json_output()
+    {
+        $this->assertEquals('{"key":"foo","width":100,"height":null,"ratio":null}', json_encode(
+            Image::lazy(function () {
+                return Image::forBinary(base64_decode('iVBORw0KGgoAAAANSUhEUgAAABQAAAAVCAIAAADJt1n/AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAB8SURBVDhP3YxBDoAgDAR5iEf//zPfgCutCGwp4MXEyZI0W6bh2PaYyMM8Aa/0l05UsjDvGzIoG+fWJQPHfyMDKccy4E9oOLpLeLLQ9OWJRwamz2VXNqPrm1xWMjB/M56coy0hK0PWKdHz5fRABj0f/Efm6I5o5SW+kmM8AS/fakEk7YJkAAAAAElFTkSuQmCC'));
+            })->width(100)->key('foo')
+        ));
+    }
+
     public function test_image_replacement_tags()
     {
         $replacments = Image::forPath(__DIR__ . '/fixtures/test.png')->replacements();