Laravel Imgproxy Laravel Package

Getting Started

Upgrade to v3 with the underlying imgproxy PHP client:

composer require hosmelq/laravel-imgproxy:^3.0 hosmelq/imgproxy:^2.0

Then publish and review config/imgproxy.php. Set the imgproxy base URL, key/salt (or trusted signature settings), source URL behaviour, and any presets you rely on. Clear config cache after changes:

php artisan config:clear

First place to look is the Imgproxy facade and the Storage disk macros. The quickest day-to-day use case is generating a signed, transformed image URL for a file on a Laravel disk:

use Illuminate\Support\Facades\Storage;

$url = Storage::disk('images')
    ->imgproxy('products/chair.jpg')
    ->width(800)
    ->height(600)
    ->build(extension: 'webp');

Use this in Blade components, API resources, or srcset generation. For imgproxy Pro metadata, use the new info URL support:

use hosmelq\LaravelImgproxy\Facades\Imgproxy;

$infoUrl = Imgproxy::infoBuilder()
    ->url(Storage::disk('images')->url('products/chair.jpg'))
    ->build();

// Or via the disk macro added in v3:
$infoUrl = Storage::disk('images')->imgproxyInfo('products/chair.jpg');

Implementation Patterns

Centralize transformations in presets. Define common sizes and options once, then reference them from application code. If you enable presets-only mode, production can only generate URLs from approved presets, which prevents arbitrary transformation parameters from leaking through user input.

Use build(extension: ...) for URL suffixes. In v3, format() no longer adds a file extension. Treat format and extension as separate concerns:

$url = Storage::disk('images')
    ->imgproxy('hero.jpg')
    ->width(1200)
    ->format('webp')          // imgproxy output format option
    ->build(extension: 'webp'); // URL suffix

Generate URLs at render time. Signed URLs depend on the current key/salt, source configuration, and encryption settings. Avoid storing them permanently in the database; store the source path and transformation preset instead.

Build responsive images in one place. A small helper or Blade component keeps srcset consistent:

$srcset = collect([400, 800, 1200])
    ->map(fn (int $width) => Storage::disk('images')
        ->imgproxy('hero.jpg')
        ->width($width)
        ->build(extension: 'webp')." {$width}w")
    ->implode(', ');

<img
    src="{{ Storage::disk('images')->imgproxy('hero.jpg')->width(800)->build(extension: 'webp') }}"
    srcset="{{ $srcset }}"
    alt=""
>

Use aliases to keep application code readable. The new option-alias config lets you map domain-specific names to imgproxy options. Keep aliases in config rather than scattering raw imgproxy option names across controllers and models.

Use info URLs for metadata, not full downloads. When running imgproxy Pro, Imgproxy::infoBuilder() and imgproxyInfo() can return metadata URLs. Cache the resulting metadata where appropriate and avoid calling the info endpoint on every request for the same source.

Configure for your deployment. Review arguments separator, source chunk size and filename, trusted signature, presets-only mode, and option aliases together. These settings affect URL shape and signature validation, so keep local, staging, and production config aligned.

Gotchas and Tips

• v3 is breaking. The upgrade to hosmelq/imgproxy ^2.0 can change URLs even when your builder calls look identical. Add URL snapshot or signature assertions to your test suite before deploying.
• format() no longer appends an extension. Replace code and tests that expected format('webp') to produce a .webp suffix. Pass build(extension: 'webp') explicitly.
• Encrypted source URLs must be rebuilt. v3 pads encrypted sources once; URLs generated by earlier versions may not behave correctly. Rebuild and republish any cached encrypted URLs.
• Invalid encryption/encoding config now throws. Unknown source_encoding values, invalid custom IVs, and invalid encryption keys fail loudly. Validate these during deployment or application boot rather than discovering them on the first image request.
• Presets-only mode can block ad-hoc transformations. If you enable it, audit every width(), height(), resize(), or other builder call in the application and make sure each is covered by a preset.
• Arguments separator mismatch breaks URLs. Ensure the package config matches the imgproxy server configuration. This is especially important when moving between imgproxy versions or environments.
• Changing source chunk size/filename can invalidate caches. These settings affect source URL construction. Coordinate CDN cache purges and URL regeneration when changing them.
• Key/salt rotation invalidates signed URLs. Rotating credentials or changing trusted signature settings means existing signed URLs stop validating. Purge CDN caches and regenerate URLs at render time.
• Info URLs require imgproxy Pro and the info endpoint. Do not depend on infoBuilder() or imgproxyInfo() in environments running imgproxy OSS or with the info endpoint disabled.
• Check the underlying client changelog. The hosmelq/imgproxy 2.0 changelog contains details about builder behaviour changes that are not repeated in the Laravel package release notes. Review it before upgrading production workloads.