Build imgproxy URLs in PHP with optional encryption and signing.
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.
use HosmelQ\Imgproxy\Imgproxy; use HosmelQ\Imgproxy\ResizingType; $url = Imgproxy::create(baseUrl: 'https://imgproxy.example.com') ->format(extension: 'png') ->resize(type: ResizingType::Fit, width: 1200, height: 630) ->build(sourceUrl: 'https://example.com/image.jpg');
- PHP 8.3+
- OpenSSL extension (for source encryption)
Install via Composer:
composer require hosmelq/imgproxy
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: 'png') ->gravity(gravity: Gravity::smart()) ->quality(quality: 80) ->resize(type: ResizingType::Fit, width: 1200, height: 630) ->build(sourceUrl: 'https://example.com/product.jpg');
Switch to short option names if you want more compact URLs:
$shortUrl = $builder ->useShortOptions() ->build(sourceUrl: 'https://example.com/product.jpg');
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: 'png') ->usePlainSource() ->build(sourceUrl: 'https://example.com/product.jpg'); // Encrypted source (pro) $encryptedUrl = Imgproxy::create(baseUrl: 'https://imgproxy.example.com') ->format(extension: 'png') ->useEncryptedSource() ->withEncryptionKey(key: '1eb5b0e971ad7f45324c1bb15c947cb207c43152fa5c6c7f35c4f36e0c18e0f1') ->build(sourceUrl: 'https://example.com/private.jpg', encoding: SourceEncoding::Encrypted);
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/product.jpg');
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: 'png') ->useEncryptedSource() ->withEncryptionKey( key: '1eb5b0e971ad7f45324c1bb15c947cb207c43152fa5c6c7f35c4f36e0f199a', ivGenerator: fn (): string => random_bytes(16) ) ->build(sourceUrl: 'https://example.com/private.jpg');
composer testWant a ready-to-run imgproxy instance? Use the Railway template:
Please see CHANGELOG.md for recent changes.
The MIT License (MIT). Please see LICENSE.md for more information.