imgproxy PHP URL builder

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',
    key: 'b397f17682dea6270ac06941ca1e3f0f',
    salt: '68de0f586bdb701cf2458565bf5a6aec'
)
    ->cachebuster(value: 'v2')
    ->format(extension: 'webp')
    ->gravity(gravity: Gravity::smart())
    ->resize(type: ResizingType::Fill, width: 800, height: 600, enlarge: false);

$url = $builder->build(sourceUrl: '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',
    key: 'b397f17682dea6270ac06941ca1e3f0f',
    salt: '68de0f586bdb701cf2458565bf5a6aec'
);

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

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

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

Source encoding choices

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

use HosmelQ\Imgproxy\Imgproxy;
use HosmelQ\Imgproxy\SourceEncoding;

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

// Encrypted source (pro)
$encryptedUrl = Imgproxy::create(baseUrl: 'https://imgproxy.example.com')
    ->format(extension: 'jpg')
    ->useEncryptedSource()
    ->withEncryptionKey(key: '1eb5b0e971ad7f45324c1bb15c947cb207c43152fa5c6c7f35c4f36e0c18e0f1')
    ->build(sourceUrl: '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:

use HosmelQ\Imgproxy\Imgproxy;

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

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):

use HosmelQ\Imgproxy\Imgproxy;

$url = Imgproxy::create(baseUrl: 'https://imgproxy.example.com')
    ->format(extension: 'jpg')
    ->useEncryptedSource()
    ->withEncryptionKey(
        key: '1eb5b0e971ad7f45324c1bb15c947cb207c43152fa5c6c7f35c4f36e0f199a',
        ivGenerator: fn (): string => random_bytes(16)
    )
    ->build(sourceUrl: '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

• Hosmel Quintana
• All Contributors

License

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