README

Build imgproxy URLs from PHP with full processing coverage, signing, and source encryption support.

Introduction

This package generates imgproxy URLs with every documented option (free and pro) and signs requests when you provide a key/salt pair. Long option names are emitted by default, and you can switch to the short aliases that imgproxy supports.

<?php

use HosmelQ\Imgproxy\Imgproxy;
use HosmelQ\Imgproxy\ResizingType;
use HosmelQ\Imgproxy\Support\Gravity;

$builder = Imgproxy::create(
    baseUrl: 'https://imgproxy.example.com',
    keyHex: 'b397f17682dea6270ac06941ca1e3f0f',
    saltHex: '68de0f586bdb701cf2458565bf5a6aec'
)
    ->cachebuster('v2')
    ->format('webp')
    ->gravity(Gravity::smart())
    ->resize(ResizingType::Fill, width: 800, height: 600, enlarge: false);

$url = $builder->build('https://example.com/image.jpg');

Requirements

PHP 8.3+
OpenSSL extension (for source encryption)

Installation & setup

Install via Composer:

composer require hosmelq/imgproxy

Basic usage

Getting started

Create a builder with your base URL and optional signing key/salt. Configure processing options fluently, then build the URL for a source image.

use HosmelQ\Imgproxy\Imgproxy;
use HosmelQ\Imgproxy\ResizingType;
use HosmelQ\Imgproxy\Support\Gravity;

$builder = Imgproxy::create(
    baseUrl: 'https://imgproxy.example.com',
    keyHex: 'b397f17682dea6270ac06941ca1e3f0f',
    saltHex: '68de0f586bdb701cf2458565bf5a6aec'
);

$url = $builder
    ->format('jpg')
    ->gravity(Gravity::smart())
    ->quality(80)
    ->resize(ResizingType::Fit, width: 1200, height: 800, enlarge: true)
    ->build('https://example.com/assets/product.jpg');

Switch to short option names if you want more compact URLs:

$shortUrl = $builder
    ->useShortOptions()
    ->build('https://example.com/photo.jpg');

Source encoding choices

Base64 is the default. You can output plain or encrypted sources when needed:

use HosmelQ\Imgproxy\SourceEncoding;

// Plain source (no signature if key/salt are omitted)
$plainUrl = Imgproxy::create('https://imgproxy.example.com')
    ->format('webp')
    ->usePlainSource()
    ->build('https://example.com/assets/hero-banner.png');

// Encrypted source (pro)
$encryptedUrl = Imgproxy::create('https://imgproxy.example.com')
    ->format('jpg')
    ->useEncryptedSource()
    ->withEncryptionKey('1eb5b0e971ad7f45324c1bb15c947cb207c43152fa5c6c7f35c4f36e0c18e0f1')
    ->build('https://example.com/private.jpg', encoding: SourceEncoding::Encrypted);

Signing and truncation

Provide both key and salt to enable signing; optionally truncate the signature to match your imgproxy config:

$signed = Imgproxy::create(
    baseUrl: 'https://imgproxy.example.com',
    keyHex: 'b397f17682dea6270ac06941ca1e3f0f',
    saltHex: '68de0f586bdb701cf2458565bf5a6aec',
    signatureSize: 12, // bytes
)
    ->format('png')
    ->build('https://example.com/avatar.png');

Working with processing options

Every imgproxy option (including pro-only ones) is exposed as a fluent method. You can mix geometry, color, metadata, and video thumbnail controls in one chain:

use HosmelQ\Imgproxy\GravityDirection;
use HosmelQ\Imgproxy\ResizingAlgorithm;
use HosmelQ\Imgproxy\Support\Color;
use HosmelQ\Imgproxy\Support\Gravity;
use HosmelQ\Imgproxy\WatermarkPosition;

$url = Imgproxy::create('https://imgproxy.example.com')
    ->background(Color::fromHex('ffffff'))
    ->cachebuster('v3')
    ->crop(0.8, 0.6, Gravity::direction(GravityDirection::SouthEast))
    ->gravity(Gravity::direction(GravityDirection::NorthWest))
    ->quality(75)
    ->resizingAlgorithm(ResizingAlgorithm::Cubic)
    ->size(width: 1200, height: 800, enlarge: true, extend: false)
    ->useShortOptions()
    ->watermark(0.5, position: WatermarkPosition::SouthEast, xOffset: 10, yOffset: 20, scale: 0.25)
    ->build('https://example.com/assets/source.jpg', extension: 'jpg');

Advanced usage

Custom IV generator for encrypted sources

Pass your own IV generator to withEncryptionKey when you need a specific IV strategy (for example, to align with another language implementation):

$url = Imgproxy::create('https://imgproxy.example.com')
    ->format('jpg')
    ->useEncryptedSource()
    ->withEncryptionKey(
        '1eb5b0e971ad7f45324c1bb15c947cb207c43152fa5c6c7f35c4f36e0f199a',
        fn (): string => random_bytes(16)
    )
    ->build('https://example.com/private/secret.jpg');

Testing

composer test

Deployments

Want a ready-to-run imgproxy instance? Use the Railway template:

Changelog

Please see CHANGELOG.md for recent changes.

Credits

License

The MIT License (MIT). Please see LICENSE.md for more information.

hosmelq / imgproxy

Maintainers

Details