feat: add S3 source directory support

Author: ace-of-aces

config/image-transform-url.php

@@ -13,6 +13,9 @@
     | Important: The public storage directory should be addressed directly via
     | storage('app/public') instead of the public_path('storage') link.
     |
+    | You can also use any Laravel Filesystem disk (e.g. S3) by providing an
+    | array configuration with 'disk' and an optional 'prefix'.
+    |
     */
 
     'source_directories' => [

src/Http/Controllers/ImageTransformerController.php

@@ -8,13 +8,16 @@
 use AceOfAces\LaravelImageTransformUrl\Enums\AllowedOptions;
 use AceOfAces\LaravelImageTransformUrl\Traits\ManagesImageCache;
 use AceOfAces\LaravelImageTransformUrl\Traits\ResolvesOptions;
+use AceOfAces\LaravelImageTransformUrl\ValueObjects\ImageSource;
+use Illuminate\Filesystem\FilesystemAdapter;
 use Illuminate\Http\Request;
 use Illuminate\Http\Response;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\App;
 use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Facades\File;
 use Illuminate\Support\Facades\RateLimiter;
+use Illuminate\Support\Facades\Storage;
 use Illuminate\Support\Str;
 use Intervention\Image\Drivers\Gd\Encoders\WebpEncoder;
 use Intervention\Image\Encoders\AutoEncoder;
@@ -48,7 +51,7 @@ public function transformDefault(Request $request, string $options, string $path
      */
     protected function handleTransform(Request $request, ?string $pathPrefix, string $options, ?string $path = null): Response
     {
-        $realPath = $this->handlePath($pathPrefix, $path);
+        $source = $this->handlePath($pathPrefix, $path);
 
         $options = $this->parseOptions($options);
 
@@ -75,7 +78,10 @@ protected function handleTransform(Request $request, ?string $pathPrefix, string
             $this->rateLimit($request, $path);
         }
 
-        $image = Image::read($realPath);
+        $image = match ($source->type) {
+            'disk' => Image::read(Storage::disk($source->disk)->get($source->path)),
+            default => Image::read($source->path),
+        };
 
         if (Arr::hasAny($options, ['width', 'height'])) {
             $image->scale(
@@ -116,7 +122,7 @@ protected function handleTransform(Request $request, ?string $pathPrefix, string
 
         }
 
-        $originalMimetype = File::mimeType($realPath);
+        $originalMimetype = $source->mime;
 
         $format = $this->getStringOptionValue($options, 'format', $originalMimetype);
         $quality = $this->getPositiveIntOptionValue($options, 'quality', 100, 100);
@@ -150,7 +156,7 @@ protected function handleTransform(Request $request, ?string $pathPrefix, string
      *
      * @param-out string $pathPrefix
      */
-    protected function handlePath(?string &$pathPrefix, ?string &$path): string
+    protected function handlePath(?string &$pathPrefix, ?string &$path): ImageSource
     {
         if ($path === null) {
             $path = $pathPrefix;
@@ -164,8 +170,38 @@ protected function handlePath(?string &$pathPrefix, ?string &$path): string
 
         abort_unless(array_key_exists($pathPrefix, $allowedSourceDirectories), 404);
 
-        $basePath = $allowedSourceDirectories[$pathPrefix];
-        $requestedPath = $basePath.'/'.$path;
+        $base = $allowedSourceDirectories[$pathPrefix];
+
+        // Handle disk-based source directories
+        if (is_array($base) && array_key_exists('disk', $base)) {
+
+            $disk = (string) $base['disk'];
+            $prefix = isset($base['prefix']) ? trim((string) $base['prefix'], '/') : '';
+
+            $normalized = $this->normalizeRelativePath($path);
+            abort_unless(! is_null($normalized), 404);
+
+            $diskPath = trim($prefix !== '' ? $prefix.'/'.$normalized : $normalized, '/');
+
+            abort_unless(Storage::disk($disk)->exists($diskPath), 404);
+
+            /** @var FilesystemAdapter $diskAdapter */
+            $diskAdapter = Storage::disk($disk);
+            $mime = $diskAdapter->mimeType($diskPath);
+
+            abort_unless(in_array($mime, AllowedMimeTypes::all(), true), 404);
+
+            return new ImageSource(
+                type: 'disk',
+                path: $diskPath,
+                mime: $mime,
+                disk: $disk,
+            );
+        }
+
+        // Handle local filesystem paths
+        $basePath = (string) $base;
+        $requestedPath = rtrim($basePath, '/').'/'.$path;
         $realPath = realpath($requestedPath);
 
         abort_unless($realPath, 404);
@@ -177,7 +213,39 @@ protected function handlePath(?string &$pathPrefix, ?string &$path): string
 
         abort_unless(in_array(File::mimeType($realPath), AllowedMimeTypes::all(), true), 404);
 
-        return $realPath;
+        return new ImageSource(
+            type: 'local',
+            path: $realPath,
+            mime: (string) File::mimeType($realPath),
+        );
+    }
+
+    /**
+     * Normalize a relative path by resolving `.` and `..` segments.
+     * Returns null if the path escapes above the root.
+     */
+    protected function normalizeRelativePath(string $path): ?string
+    {
+        $path = str_replace('\\', '/', $path);
+        $segments = array_filter(explode('/', $path), fn ($s) => $s !== '');
+        $stack = [];
+
+        foreach ($segments as $segment) {
+            if ($segment === '.') {
+                continue;
+            }
+            if ($segment === '..') {
+                if (empty($stack)) {
+                    return null;
+                }
+                array_pop($stack);
+
+                continue;
+            }
+            $stack[] = $segment;
+        }
+
+        return implode('/', $stack);
     }
 
     /**

src/ValueObjects/ImageSource.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AceOfAces\LaravelImageTransformUrl\ValueObjects;
+
+/**
+ * @internal
+ */
+readonly class ImageSource
+{
+    public function __construct(
+        public readonly string $type,
+        public readonly string $path,
+        public readonly string $mime,
+        public readonly ?string $disk = null,
+    ) {
+        if (! in_array($this->type, ['local', 'disk'], true)) {
+            throw new \InvalidArgumentException('Invalid image source type provided.');
+        }
+    }
+}

tests/Feature/S3SourceTest.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+use AceOfAces\LaravelImageTransformUrl\Tests\TestCase;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Storage;
+
+beforeEach(function () {
+    Cache::flush();
+    Storage::fake(config()->string('image-transform-url.cache.disk'));
+    Storage::fake('s3');
+
+    // Configure S3 as a source directory using the disk driver
+    config()->set('image-transform-url.source_directories.s3', [
+        'disk' => 's3',
+        'prefix' => '',
+    ]);
+});
+
+it('can serve from an s3 disk source directory', function () {
+    /** @var TestCase $this */
+    $imagePath = 'images/test.jpg';
+    Storage::disk('s3')->put($imagePath, file_get_contents(__DIR__.'/../../workbench/test-data/cat.jpg'));
+
+    $response = $this->get(route('image.transform', [
+        'options' => 'width=100',
+        'pathPrefix' => 's3',
+        'path' => $imagePath,
+    ]));
+
+    expect($response)->toBeImage([
+        'width' => 100,
+        'mime' => 'image/jpeg',
+    ]);
+});
+
+it('can use s3 as the default source directory', function () {
+    /** @var TestCase $this */
+    config()->set('image-transform-url.default_source_directory', 's3');
+
+    $imagePath = 'images/test.jpg';
+    Storage::disk('s3')->put($imagePath, file_get_contents(__DIR__.'/../../workbench/test-data/cat.jpg'));
+
+    $response = $this->get(route('image.transform.default', [
+        'options' => 'width=100',
+        'path' => $imagePath,
+    ]));
+
+    expect($response)->toBeImage([
+        'width' => 100,
+        'mime' => 'image/jpeg',
+    ]);
+});