Laravel Qcs Laravel Package

Getting Started

• Check your runtime before anything else. 5.0.0 requires PHP 8.3+ and Laravel 13. If you are still on Laravel 11/12 or PHP 8.1/8.2, stay on the 4.x line — install with an explicit constraint so Composer cannot silently pull 5.x: composer require <vendor>/<package>:"^4.0".
• Install on a supported app: composer require <vendor>/<package>:"^5.0". No manual provider registration is needed — package discovery wires up the image bindings and the validator extensions.
• Remove the legacy ImageServiceProvider entry from config/app.php (and any providers array in bootstrap/providers.php) if you carried it over from the Intervention Image 2 era. Leaving it in is the most likely cause of a container binding conflict on Laravel 13.
• Look first at: the package README's upgrade section (it documents the Intervention 2 → 4 migration), the published config file (image driver selection), and the validator rule list.
• First use case: add the ims / tms rules to a FormRequest and run one request through it. This exercises three things at once — rule registration on cold start, the image driver binding, and the PNG/JPEG encode path — which is exactly the surface that was broken in this release.

class UploadRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'avatar' => ['required', 'file', 'ims'],
            'banner' => ['required', 'file', 'tms'],
        ];
    }
}

Implementation Patterns

Prefer the package's rule strings over hand-rolled validation. The tms / ims rules are the package's public contract; hand-writing image checks in a withValidator() closure means you lose the 300px proportional scaling and the PNG/JPEG encoding behaviour that the package guarantees across both drivers.

Keep driver selection in config, not in code. The package supports GD and Imagick and resolves the driver through the container. Set it via the published config / env var rather than calling ImageManager::imagick() directly, so a server without the imagick extension can fall back to GD without a code change.

Drive image work through the package service, not raw Intervention. Since 5.0.0 the package owns an Intervention 4 instance. When you need to post-process (thumbnails, conversions), resolve the package's image service and let it hand you a configured manager — otherwise you re-implement the 300px scaling rule in a second place and drift.

// Preferred: package-managed manager (driver already chosen)
$manager = app(ImageManager::class);

$image = $manager->read($path)
    ->scale(width: 300)      // v4 proportional API
    ->encode(new PngEncoder(quality: 90));

Storage::disk('public')->put("thumbs/{$name}.png", (string) $image);

Integration tip — queue the encode, not the read. Encoding to PNG/JPEG is the expensive half. Read the upload synchronously in the request (so validation fails fast), persist the original, then do the scale/encode in a job.

Test the cold path explicitly. The bug fixed here only appeared on first use of the rules in a fresh process. A RefreshDatabase-based feature test that boots the app and immediately validates an upload is worth more than a unit test that constructs the validator by hand — the latter never exercises the registration hook.

Cover both drivers in CI. GD is almost always present; Imagick usually is not on the default runner. Matrix the extension so an Imagick-only regression can't ship, and assert PNG and JPEG output independently — they take different encoder branches.

Gotchas and Tips

• Intervention 2 → 4 is the real migration cost. Image::make(), ->resize($w, $h), ->save() and the Intervention\Image\ImageServiceProvider all disappear. In v4 you get a manager, call read(), use scale() (proportional) or resize() (explicit box), and encode() with an encoder object. ->resize() no longer preserves aspect ratio for you — if your code relied on v2's resize($w, null), switch to scale(width: ...) or you will ship squashed images that pass tests because the dimensions are right.
• Composer conflicts are likely. If anything else in the tree pins intervention/image:^2, the install fails rather than degrades. Run composer why intervention/image before upgrading and resolve it first; composer update --with-all-dependencies only after the constraint is gone.
• Stale provider registration is silent-until-runtime. A leftover ImageServiceProvider in config/app.php won't fail at boot; it fails on the first image operation with a binding/resolution error. If you see a container error naming an image class, check bootstrap/providers.php and the cached config before debugging anything else — and run php artisan config:clear after editing, since a cached config will keep the old provider list alive.
• "Rules not registered" on first use was a real bug, now fixed — but your own custom rules are still yours. If you extended the validator with package-adjacent rules, verify they're registered from a service provider's boot() and not at the top of a controller. That's the same class of cold-start failure.
• Imagick is not guaranteed in production. Base images often ship GD only. Force GD in the config or add the extension to your Dockerfile — don't let the driver be "whatever the container happens to have," or dev and prod will encode differently.
• Pin and read before you trust. 5.0.0 is a major with a native-library-level dependency swap; the release notes report 26 tests / 96 assertions across both drivers, which is decent for a bridge package but thin for full encode coverage. After upgrading, diff one PNG and one JPEG produced before and after — file size and colour handling are the usual silent changes.
• Extension point: if you need a third driver or a custom encoder chain, bind your own implementation against the package's image contract in a service provider and prefer that over forking — a fork will cost you again at the next Intervention major.