Uploader Laravel Package

Getting Started

The 1.1.0 release adds Intervention Image support plus a set of "quick" convenience operations. Start here:

1. Install the image backend first. The package declares the integration, but it does not ship the imaging library. Add intervention/image (and, if you want the Laravel-facing facade/config, intervention/image-laravel) alongside the package update:

   composer require intervention/image intervention/image-laravel
   php artisan vendor:publish --provider="Intervention\Image\Laravel\ServiceProvider"
   

2. Confirm a driver is actually available. Check php -m | grep -E 'gd|imagick' and then config/image.php (driver => 'gd' by default in the Laravel bridge). The package cannot fail over silently — a missing driver surfaces as a runtime exception on the first conversion, not at boot.
3. Read the package's image config block before anything else. New config keys usually land under config/<package>.php in this kind of release (driver, quality, allowed mime types, storage disk, cache TTL). php artisan vendor:publish --tag=<package>-config and diff against your existing published config — a stale published config is the single most common cause of "the new feature does nothing."
4. First use case: take one existing upload path (avatar, thumbnail, product image) and route it through the new support end-to-end — store original, generate one derived size, persist the path. That single vertical slice exercises driver resolution, filesystem disk wiring, and the package's quick operations in one go.

Where to look first in the source: the service provider's bindings (does it bind ImageManager or resolve it lazily?), then the class that wraps the quick functionalities. That wrapper is where the package's opinions live and where you will extend.

Implementation Patterns

Treat the image layer as a pipeline stage, not a controller concern. The healthiest integration in Laravel is a queued job or a dedicated action class that receives a stored file path and emits derived paths. Keeps request latency flat and makes retries possible when Imagick segfaults on a malformed JPEG.

final class GenerateDerivatives implements ShouldQueue
{
    public function __construct(private string $path, private string $disk = 'public') {}

    public function handle(ImageManager $images): void
    {
        $source = Storage::disk($this->disk)->path($this->path);
        $image  = $images->read($source);

        foreach (config('media.derivatives') as $name => $width) {
            $derived = $images->read($source)->scaleDown(width: $width);
            Storage::disk($this->disk)->put(
                $this->derivedPath($this->path, $name),
                (string) $derived->toJpeg(quality: 82)
            );
        }
    }
}

Wrap the package's quick functionalities behind your own facade or service. The release note is explicit that these are "quick functionalities" — convenience methods with opinionated defaults. Calling them directly from controllers, jobs, and Blade partials scatters those defaults across the codebase, and the next minor version will move them. One thin adapter class means a one-file change when they do.

Use the manager, never the static facade, in tests. Inject ImageManager (or the package's wrapper) so you can bind a fake or point at a fixture directory. Image::make()-style statics make image tests order-dependent and slow.

Chunk and constrain uploads at the validation layer, not the image layer. mimes:jpg,jpeg,png,webp plus max:5120 in a FormRequest is cheaper than decoding a 90MP PNG to discover it is unacceptable. Intervention will happily attempt it and exhaust memory.

Handle storage disks explicitly. Every quick functionality that persists output should take a disk name. Local-vs-S3 differences (streams vs. paths, path() unavailability on remote disks) are where these integrations break. If your default disk is S3, write Storage::readStream() into a temp file before handing a path to the image library.

Pair with Laravel's image validation rule and a HasMedia-style trait so models own their derivative manifest, and deletion events clean up derived files. Orphaned thumbnails are the usual long-term cost of a half-integrated image pipeline.

Gotchas and Tips

• Intervention Image v2 vs v3 is a hard break. Image::make(), ->resize(), ->save() semantics changed to ImageManager::read(), ->scale(), ->toJpeg(). If your app still has v2 in the lock file, the new package release will either fail autoload or silently resolve the wrong API. Pin intervention/image:^3.0 and grep for v2-era calls before deploying.
• Driver parity is not guaranteed. GD and Imagick differ on EXIF orientation, animated GIF/WebP handling, colour profiles, and scaleDown results for edge-case aspect ratios. Standardise on one driver per environment and assert it in a health check; do not let dev (GD) and prod (Imagick) diverge.
• Memory limit is the classic production failure. Imagick and GD both blow past PHP's default memory_limit on large inputs. Either cap input dimensions pre-decode or raise the limit specifically in the worker (--memory on the queue, memory_limit in the pool config), not globally.
• "Quick functionalities" may not be covered by the semver promise you assume. Read the changelog signature: if these are untyped convenience wrappers, expect signature churn in 1.x. Keep them behind your adapter and pin the version (~1.1.0) on projects where image output is contractual.
• Config cache traps. After adding new config keys, php artisan config:clear in local and redeploy with config:cache in production. A cached config from before the upgrade omits the new image block, and the package falls back to defaults you never chose.
• EXIF is preserved by default and that is a privacy leak. Strip metadata on user uploads (->strip() in v3) unless you specifically need orientation data downstream.
• Debugging recipe: when an image operation fails opaquely, reproduce outside the package first — a five-line script calling ImageManager::read() on the same file isolates package bugs from driver and memory problems. Then check storage/logs/laravel.log for the underlying Intervention\Image\Exceptions\* class; the package frequently rethrows a generic message and loses that detail.
• Extension point: if the package registers a driver or decorator in its service provider, $this->app->extend(...) after the package's binding lets you swap in your own encoding defaults (quality, progressive JPEG, WebP conversion) without forking. That is the cleanest place to enforce house style across every image the app emits.