Imagine Laravel Package

Getting Started

Install and confirm resolution before writing any call sites. This is a Composer-only package — no installer, no Artisan command.

composer require orchestra/imagine
php artisan vendor:publish --provider="Orchestra\Imagine\ImagineServiceProvider"

That publishes config/imagine.php, whose only meaningful key is driver (gd, imagick, or gmagick). Because this is a Laravel 8-era release line, treat "won't resolve against our PHP/Laravel" as the expected outcome — let Composer tell you that in five minutes, not after you've wired a controller.

Verify the imaging extension exists on every environment. The wrapper does not install GD/Imagick; it only picks a driver. A configured imagick against a box with no extension surfaces as a murky container-resolution failure, not a clean "extension missing."

php -m | grep -Ei 'gd|imagick|gmagick'
php -r 'print_r(gd_info());'

Check staging and production too.

Where to look first, in order:

1. config/imagine.php — the driver selection; the only knob that matters.
2. The service provider — to see the container key and whether the manager is a singleton or a fresh instance per resolve.
3. The facade — read getFacadeAccessor() to confirm the alias you actually type.
4. Upstream imagine/imagine docs — because resize, crop, thumbnail, rotate, apply, save, get, draw are Imagine methods surfaced through the manager, not methods this package invented. Time spent reading Imagine docs transfers; time hunting wrapper-specific docs is wasted, because they largely don't exist.

First use case: avatar/thumbnail generation on upload. The honest sweet spot — internal upload path, unremarkable latency, small blast radius.

use Orchestra\Imagine\Facade as Imagine;

$image = Imagine::open($request->file('avatar')->getRealPath());
$image->thumbnail(new \Imagine\Image\Box(200, 200))
      ->save(storage_path("app/avatars/{$id}.jpg"));

Implementation Patterns

Put an interface between your code and the facade — this is the only durable thing you'll write here. The facade is thin wiring and the package is unmaintained. An hour of encapsulation converts an eventual swap (Intervention Image v3, a CDN transform tier, a queued worker) into a constructor change.

namespace App\Imaging;

interface ImageProcessor
{
    public function thumbnail(string $source, string $dest, int $w, int $h): void;
    public function crop(string $source, string $dest, int $x, int $y, int $w, int $h): void;
}

final class ImagineProcessor implements ImageProcessor
{
    public function __construct(private \Imagine\Image\ImagineInterface $imagine) {}

    public function thumbnail(string $source, string $dest, int $w, int $h): void
    {
        $this->imagine->open($source)
            ->thumbnail(new \Imagine\Image\Box($w, $h))
            ->save($dest);
    }
}

Bind it once in a service provider; let the orchestra/imagine manager be one possible implementation behind it. Imagine::getFacadeRoot() or the container key gets you the underlying instance to inject.

Keep presets in your config, not the vendor file. The vendor file is for the driver only. Sizes and modes belong in config/imaging.php:

return [
    'presets' => [
        'thumb'   => ['w' => 200, 'h' => 200, 'mode' => 'outbound'],
        'product' => ['w' => 800, 'h' => 800, 'mode' => 'inset'],
    ],
];

That is what actually buys the "marketing can change sizes without a deploy" benefit — the wrapper's own config does not deliver it alone.

Pin format and quality explicitly, by extension. Imagine infers format from the destination path in most cases, but be explicit when it matters:

$image->save($dest, ['jpeg_quality' => 85, 'png_compression_level' => 7]);

Quality defaults are the classic source of "why does the site look different after deploy" tickets. Pin them in config and pass them through your interface.

Route processing through a queued job even though the library is synchronous. Dispatch a GenerateThumbnails job from a model event or controller and let the worker own the facade call. Costs nothing today; makes the eventual move to a transform tier a matter of scaling workers out, not rewriting controllers.

Store originals, always. Never overwrite the uploaded file with a derived variant. Derived images are cheap to regenerate and expensive to un-regenerate.

Test against golden fixtures. Eyeballing output won't catch driver or quality drift. Commit a handful of source images plus a hash or pixel assertion per operation, and run them on every environment you deploy to. This is the highest-value test investment for an image pipeline and it survives the migration away from this package.

Gotchas and Tips

GD and Imagick produce visibly different output at identical settings. Scaling algorithms, anti-aliasing, and JPEG encoders diverge. If dev uses GD and prod uses Imagick, your QA pass doesn't reflect production. Make the driver explicit per environment and mirror production locally — an ops/QA problem as much as an engineering one.

This package is unmaintained and you inherit the image parser. Zero stars, zero dependents, release history stops at Laravel 8 — no upstream fix path, and silent incompatibility rather than filed issues. The transitive imagine/imagine pin is the real risk surface: image decoders are a known attack vector (decompression bombs, malformed headers, memory exhaustion on decode). If you keep it, pin the version explicitly in your own composer.json, track CVEs against imagine/imagine yourself, and consider vendoring or forking the wrapper for a reproducible tree. Run composer show imagine/imagine so the facade doesn't obscure which version is actually running.

Cap input dimensions before you decode. A 40MB upload with absurd pixel dimensions will exhaust memory_limit before your code runs. Check getimagesize() first and reject above a ceiling. Set the limit explicitly on worker processes — queue defaults are often lower than web defaults.

Never process in the request path for user-facing media. Synchronous resize is fine for admin screens and wrong for catalog pages. The facade ergonomics nudge you the wrong way; resist.

Extension points are thin, so use the container, not the package. Caching, Flysystem/S3 awareness, srcset generation, focal-point cropping — this package provides none of them. Rebinding the manager in your container to your own decorator is cleaner than extending the package, and it's the path that survives removal.

Facade alias and auto-discovery. If the provider isn't registered (older Laravel or disabled discovery), the facade resolves to nothing and you get an unhelpful class-not-found or container exception. Check bootstrap/providers.php / config/app.php before debugging your own code, and watch for alias collisions if anything else registers Imagine.

If resolution fails, don't patch constraints to force it. Widening constraints to shove a Laravel 8-era package onto Laravel 11 buys an install and an unbudgeted debugging session. Bind Imagine\Gd\Imagine or Imagine\Imagick\Imagine directly behind your ImageProcessor interface instead — same API, no wrapper, and you skip the dependency entirely.