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:

Key	Default	Description
`IMGP_KEY`	`''`	Imgproxy signing key (hex-encoded)
`IMGP_SALT`	`''`	Imgproxy signing salt (hex-encoded)
`IMGP_HOST`	`https://imgproxy.example.com`	Imgproxy instance base URL
`IMGP_DEBUG_URL_FROM`	`http://example.test`	Local origin replaced in debug mode
`IMGP_DEBUG_URL_TO`	`https://example.pro`	Production origin used instead

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

Case	Value	Description
`ResizeType::Fit`	`fit`	Keeps aspect ratio, fits the whole image within the box. Default.
`ResizeType::Fill`	`fill`	Keeps aspect ratio, fills the box and crops the excess.
`ResizeType::Auto`	`auto`	Uses `Fill` when source has an alpha channel, `Fit` otherwise.
`ResizeType::ForceFit`	`force_fit`	Same as `Fit` but never enlarges a smaller source.
`ResizeType::ForceFill`	`force_fill`	Same as `Fill` but never enlarges a smaller source.

Gravity enum

Case	Value	Description
`Gravity::Smart`	`sm`	Content-aware smart crop (imgproxy detects the focus point).
`Gravity::Center`	`ce`	Center of the image.
`Gravity::North`	`no`	Top edge.
`Gravity::South`	`so`	Bottom edge.
`Gravity::East`	`ea`	Right edge.
`Gravity::West`	`we`	Left edge.
`Gravity::NorthEast`	`noea`	Top-right corner.
`Gravity::NorthWest`	`nowe`	Top-left corner.
`Gravity::SouthEast`	`soea`	Bottom-right corner.
`Gravity::SouthWest`	`sowe`	Bottom-left corner.

Format enum

Case	Value
`Format::WebP`	`webp`
`Format::Avif`	`avif`
`Format::Jpeg`	`jpg`
`Format::Png`	`png`
`Format::Gif`	`gif`

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

rikodev / laravel-imgproxy

Maintainers

Package info

Statistics

Security