README

Signed imgproxy URL builder for Laravel with full IDE autocomplete via typed options, backed enums, and PHP 8.4 property hooks.

Installation

composer require rikodev/laravel-imgproxy

Publish the config file (optional — the package merges its own defaults automatically):

php artisan vendor:publish --tag=imgproxy-config

Configuration

Add the following keys to your .env:

Debug URL rewrite — imgproxy is a remote service and cannot reach localhost. In debug mode the package automatically rewrites the local origin to the production origin so imgproxy can fetch the source image.

Usage

Global helper (recommended)

use RikoDEV\LaravelImgproxy\Options;
use RikoDEV\LaravelImgproxy\Enums\ResizeType;
use RikoDEV\LaravelImgproxy\Enums\Gravity;
use RikoDEV\LaravelImgproxy\Enums\Format;

imgproxy($url, new Options(...))

Facade

use RikoDEV\LaravelImgproxy\Facades\Imgproxy;

Imgproxy::url($url, new Options(...))

Direct injection

use RikoDEV\LaravelImgproxy\ImgproxyManager;

class MyService
{
    public function __construct(private readonly ImgproxyManager $imgproxy) {}

    public function thumbnail(string $url): string
    {
        return $this->imgproxy->url($url, new Options(width: 400, height: 300));
    }
}

Options reference

All parameters are named, so your IDE shows every option with its type as you type new Options(.

new Options(
    width:      ?int,        // Output width in pixels
    height:     ?int,        // Output height in pixels
    resize:     ResizeType,  // Resize algorithm (default: ResizeType::Fit)
    gravity:    ?Gravity,    // Crop gravity / focus point
    quality:    ?int,        // Output quality 1–100 (JPEG / WebP)
    enlarge:    bool,        // Allow enlarging beyond original size (default: false)
    format:     ?Format,     // Convert to this format (also sets the file extension)
    blur:       ?float,      // Gaussian blur sigma 0.3–1000
    brightness: ?int,        // Brightness adjustment -255–255
    contrast:   ?float,      // Contrast multiplier
    saturation: ?float,      // Saturation multiplier
)

ResizeType enum

Gravity enum

Format enum

Examples

Resize to fixed width, keep aspect ratio:

imgproxy($url, new Options(width: 1200))

Thumbnail with smart crop:

imgproxy($url, new Options(
    width:   600,
    height:  400,
    resize:  ResizeType::Fill,
    gravity: Gravity::Smart,
))

Square avatar, converted to WebP:

imgproxy($url, new Options(
    width:  128,
    height: 128,
    resize: ResizeType::Fill,
    format: Format::WebP,
))

High-quality hero image:

imgproxy($url, new Options(
    width:   1920,
    height:  1080,
    resize:  ResizeType::Fill,
    gravity: Gravity::Smart,
    quality: 90,
    format:  Format::Avif,
))

Width only with explicit quality:

imgproxy($url, new Options(width: 800, quality: 75))

Blurred placeholder:

imgproxy($url, new Options(width: 40, height: 40, blur: 10.0))

Reading the computed options string directly (PHP 8.4 property hook):

$opts = new Options(width: 600, height: 400, resize: ResizeType::Fill);

echo $opts->value;   // "rs:fill:600:400:0"
echo (string) $opts; // "rs:fill:600:400:0"

Legacy string API

Raw imgproxy option strings are still accepted by both the helper and the facade — no breaking changes:

imgproxy($url, 'w:1200')
imgproxy($url, 's:32:32', 'webp')
imgproxy($url, 'w:600/h:176/rt:fill')
imgproxy($url, 'q:80', Format::WebP)  // Format enum also accepted for $ext