feat: replace null return with NullImageBossBuilder null object pattern for safer chaining

Author: jorisnoo

src/Facades/ImageBoss.php

@@ -8,7 +8,7 @@
 use Statamic\Fields\Value;
 
 /**
- * @method static ?ImageBossBuilder from(Asset|Value|null $asset)
+ * @method static ImageBossBuilder from(Asset|Value|null $asset)
  *
  * @see \Noo\StatamicImageboss\ImageBoss
  * @see ImageBossBuilder::url() For fixed-dimension URLs

src/ImageBoss.php

@@ -7,14 +7,14 @@
 
 class ImageBoss
 {
-    public function from(mixed $asset): ?ImageBossBuilder
+    public function from(mixed $asset): ImageBossBuilder
     {
         if ($asset instanceof Value) {
             $asset = $asset->value();
         }
 
         if ($asset === null) {
-            return null;
+            return new NullImageBossBuilder;
         }
 
         if (! $asset instanceof Asset) {

src/NullImageBossBuilder.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace Noo\StatamicImageboss;
+
+use Noo\StatamicImageboss\Contracts\ImagePreset;
+
+class NullImageBossBuilder extends ImageBossBuilder
+{
+    public function __construct()
+    {
+    }
+
+    public function width(?int $width): self
+    {
+        return $this;
+    }
+
+    public function height(?int $height): self
+    {
+        return $this;
+    }
+
+    public function ratio(?float $ratio): self
+    {
+        return $this;
+    }
+
+    public function min(?int $min): self
+    {
+        return $this;
+    }
+
+    public function max(?int $max): self
+    {
+        return $this;
+    }
+
+    public function interval(?int $interval): self
+    {
+        return $this;
+    }
+
+    public function preset(ImagePreset|\BackedEnum|string $preset): self
+    {
+        return $this;
+    }
+
+    public function url(): string
+    {
+        return '';
+    }
+
+    /**
+     * @return array<int, array{url: string, width: int}>
+     */
+    public function srcset(): array
+    {
+        return [];
+    }
+
+    public function srcsetString(): string
+    {
+        return '';
+    }
+
+    public function rias(): string
+    {
+        return '';
+    }
+
+    public function aspectRatio(): ?float
+    {
+        return null;
+    }
+}

tests/Feature/ImageBossBuilderTest.php

@@ -2,6 +2,7 @@
 
 use Noo\StatamicImageboss\ImageBoss;
 use Noo\StatamicImageboss\ImageBossBuilder;
+use Noo\StatamicImageboss\NullImageBossBuilder;
 use Noo\StatamicImageboss\Tests\Fixtures\InterfacePreset;
 use Noo\StatamicImageboss\Tests\Fixtures\TestPreset;
 
@@ -301,17 +302,41 @@
     expect($builder->aspectRatio())->toBe(16 / 9);
 });
 
-it('returns null from factory when asset is null', function () {
+it('returns NullImageBossBuilder from factory when asset is null', function () {
     $imageBoss = new ImageBoss;
 
-    expect($imageBoss->from(null))->toBeNull();
+    $result = $imageBoss->from(null);
+
+    expect($result)->toBeInstanceOf(NullImageBossBuilder::class)
+        ->and($result->url())->toBe('');
 });
 
-it('returns null from factory when Value unwraps to null', function () {
+it('returns NullImageBossBuilder from factory when Value unwraps to null', function () {
     $value = Mockery::mock(\Statamic\Fields\Value::class);
     $value->shouldReceive('value')->andReturn(null);
 
     $imageBoss = new ImageBoss;
 
-    expect($imageBoss->from($value))->toBeNull();
+    $result = $imageBoss->from($value);
+
+    expect($result)->toBeInstanceOf(NullImageBossBuilder::class)
+        ->and($result->url())->toBe('');
+});
+
+it('returns empty values from null builder', function () {
+    $builder = new NullImageBossBuilder;
+
+    expect($builder->url())->toBe('')
+        ->and($builder->srcset())->toBe([])
+        ->and($builder->srcsetString())->toBe('')
+        ->and($builder->rias())->toBe('')
+        ->and($builder->aspectRatio())->toBeNull();
+});
+
+it('allows chaining on null builder', function () {
+    $builder = new NullImageBossBuilder;
+
+    $result = $builder->width(800)->height(600)->ratio(16 / 9)->min(320)->max(2560)->interval(320)->url();
+
+    expect($result)->toBe('');
 });