ImgproxyProvider

Generates imgproxy transformation URLs. Self-hosted, open-source image processing server.

use Timber\Chainsaw\Provider\Imgproxy\ImgproxyProvider;
use Timber\Chainsaw\Signer\Algorithm;
use Timber\Chainsaw\Signer\HmacUrlSigner;

// imgproxy ships the key and salt as hex strings; decode them once at boot.
$keyBin = hex2bin($_ENV['IMGPROXY_KEY']);
if ($keyBin === false) {
    throw new \InvalidArgumentException('IMGPROXY_KEY must be a hex-encoded string.');
}

$provider = new ImgproxyProvider(
    host: 'http://localhost:8081',
    signer: new HmacUrlSigner(key: $keyBin, algorithm: Algorithm::Sha256, stripPadding: true),
    salt: $_ENV['IMGPROXY_SALT'], // hex-encoded; the provider decodes + validates internally
);

Pass signer: null (the default) for unsafe URLs. Both signer and salt must be set together — otherwise the provider falls back to the unsafe segment.

stripPadding: true matches imgproxy’s base64.RawURLEncoding on the wire (no trailing =). Omitting it (the default) leaves padding intact, which is correct for imagor / thumbor but is rejected by imgproxy.

Output: {host}/{signature}/{segments}/plain/{source}@{ext}

Manipulation support

Legend: ✅ = implemented in Chainsaw, ⚠️ = supported with caveats, 🟦 = available on the CDN, not exposed by Chainsaw, ❌ = not available on this CDN.

Resize & crop

Filters & effects

Detection (Pro)

Decoration & orientation

Special

Encoding

Notes

• Free vs Pro – Brightness, Contrast, Gamma, Greyscale, Sepia, Pixelate, and Saturation are imgproxy Pro features. They are only registered when the provider is constructed with pro: true; on the OSS version they throw UnsupportedManipulator.
• Blur – range mapped from 0…100 to sigma (multiply by 0.5, minimum 1).
• Sharpen – range mapped from 0…100 to sigma (multiply by 0.1, minimum 1).
• Border – imgproxy has no native border primitive, so BorderType::Expand and BorderType::Shrink are simulated via pd:{width} (padding) + bg:{color} (background colour). Transparency caveat: imgproxy’s bg flattens every transparent source pixel onto the colour, not just the padded strip — so on PNG/WebP sources with alpha the “border” colour bleeds through the interior. BorderType::Overlay throws UnsupportedManipulator because the overlay contract (“don’t touch the interior”) cannot be honoured. Only Unit::Pixel is supported. If you need a true colour frame that preserves interior transparency, use a provider with a native border primitive (e.g. imgix).
• Watermark – on the free tier, set IMGPROXY_WATERMARK_URL as a server environment variable. The provider only emits wmu:{url} when the watermark URL differs from the server default (Pro feature).
• URL signing – HMAC path-based signing with hex-encoded key and salt.