Laravel Imgproxy Laravel Package

Getting Started

Start with the README and the package guide, then skim advanced-usage, the API reference, CONTEXT.md, and docs/adr/0002 for the intent-vs-wire-level API policy. Configure the imgproxy base URL and signing key/salt as usual, then make the first call against a known Storage image:

use YourVendor\Imgproxy\Imgproxy;

$builder = Imgproxy::fromStorage('products/hero.jpg', 'public')
    ->cover(1200, 630, 'ce')
    ->toWebp()
    ->optimize(q: 75);

Use cover() for “fill this box and crop as needed” and fit() for “fit inside this box without enlarging.” That covers most day-to-day image needs. Prefer fromStorage() when the source is a Laravel disk path; use fromPath() / fromUrl() when the source kind is already explicit. image() remains the generic entry point.

Implementation Patterns

• Use intent methods for common transformations. cover(), fit(), orient(), flipVertically(), flipHorizontally(), toWebp(), toJpg(), toPng(), toAvif(), and optimize() read better in application code and compile down to the existing processing-option segments.
• Keep withOption() for edge cases. The typed processing-option layer remains the precise wire-level escape hatch. Use intent methods for the 80% path and drop to withOption() when you need an imgproxy option that has no intent method.
• Build conditional variants with when() / unless(). The builder now uses Laravel’s Conditionable trait, so responsive or feature-flagged variants can stay in one chain. Because the builder is immutable, return the modified builder from the callback.
• Model Storage workflows explicitly. fromStorage(path, disk, ?instance) resolves public disks via url() and private disks via pre-signed temporaryUrl(). For uploads, storePublicly(disk, path, options) is the intent shortcut for toStorage() with public visibility.
• Compose contain deliberately. It is not an intent method: use fit() plus extendAspectRatio plus background, as documented in advanced-usage.
• Migrate from resize() gradually. resize() is docblock-deprecated only; runtime behaviour is unchanged. Replace common cases with cover() or fit() as you touch those code paths.

Gotchas and Tips

• Intent methods are a naming layer, not new imgproxy capability. cover() compiles to rs:fill:w:h, fit() to rs:fit:w:h, orient() to ar:1, flips to fl:*, and format methods to f:*. Do not expect contain(), scale(), coordinate crop(), or grayscale() to appear.
• fit() never enlarges. If you need upscaling, handle that expectation explicitly; do not assume fit() will scale small images up.
• crop is gravity-anchored only. The package deliberately does not add coordinate cropping. Use the documented composition or raw processing options only where imgproxy actually supports the behaviour.
• optimize() defaults to WebP at quality 70. That is convenient but may surprise format-sensitive pipelines. Pass an explicit format or use toWebp() / toJpg() / etc. when the output format is part of the contract.
• Avoid stacking conflicting format/quality intents. toWebp() and optimize() both set format-related segments; pick one clear intent rather than layering several.
• storePubliclyAs does not exist. toStorage() already takes the full path; use storePublicly(disk, path, options) when you only need public visibility.
• Private-disk fromStorage() URLs expire. It uses temporaryUrl(), so disk visibility, signing configuration, and URL lifetime matter. Public disks use url().
• Conditionable plus immutability is easy to misuse. In when() / unless() callbacks, return the new builder instance; otherwise the conditional transformation is discarded.
• resize() is not removed. The deprecation is docblock-only in 2.2.0, so there is no runtime break, but new code should prefer cover() / fit().