Download the PHP package survos/imgproxy-bundle without Composer

survos/imgproxy-bundle

Symfony bundle for generating signed imgproxy URLs. Provides preset-based resizing with no external PHP library dependency — signing is implemented natively.

Installation

Set your imgproxy credentials in .env:

Configuration

Presets are optional — the defaults above are used if presets is omitted.

If host is not configured the builder returns the original URL unchanged, so the bundle is safe to install before imgproxy is running.

Usage

Twig filter

The imgproxy filter is registered automatically — no extra config needed.

Image info & metadata (v4 PRO)

imgproxy v4 PRO exposes an /info endpoint that returns image metadata — dimensions, format, file size, blurhash, average/dominant color, palette, EXIF/IPTC/XMP, object detection, and image classification — without imgproxy (or you) downloading and decoding the whole image yourself.

info() returns the raw decoded imgproxy payload. Prefer infoDto() when application code needs a stable typed view:

The /imgproxy/info HTTP endpoint returns this DTO using Symfony 8.1 #[Serialize], skipping null values and serializing common fields with imgproxy/IIIF-friendly names such as mime_type, dominant_colors, aspect_ratio, and iiif_format.

info() / classify() / detectObjects() require an HTTP client (the bundle autowires symfony/http-client). infoUrl() only builds the signed URL and has no HTTP dependency. Note classify/detect_objects need the imgproxy PRO ML build (e.g. docker.imgproxy.pro/imgproxy:vX-ml).

Option formats accepted by info() / infoUrl():

Two non-obvious imgproxy requirements the builder handles for you: the /info endpoint takes the base64url-encoded source (the plain/ form returns 404 Invalid URL), and every option must use the name:value form — a bare dimensions is silently folded into the source URL. The builder base64-encodes the source and appends :1 to valueless tokens automatically.

Friendly names are mapped to imgproxy's short names automatically (blurhash→bh, average→avg, dominant_colors→dc, detect_objects→do, classify_objects→classify, video_meta→vm, …). Full option reference: https://docs.imgproxy.net/usage/getting_info.

The server must allow these options via IMGPROXY_ALLOWED_INFO_OPTIONS (or leave it blank to allow all).

Command

With no --opt, defaults to size, format, dimensions.

HTTP endpoint

Returns the decoded metadata JSON. Use this server-side route (not the public Stimulus path) for signed/private sources, since signing needs the secret key.

Stimulus controller

For public source URLs, the bundle includes a Stimulus controller that can rewrite rendered image tags in the browser. This is useful for Meilisearch and DataTables renderers where storing or precomputing thumbnail URLs would add noise.

When an image target is connected, the controller sets src to an unsigned imgproxy URL such as /insecure/rs:fit:512:512:0/plain/...@jpg and marks the element with data-imgproxy-done="1". You may also put the full public URL in src, data-src, or data-url; data-imgproxy-url is preferred because it avoids the browser starting a full-size image request before Stimulus connects.

Per-image attributes:

Signed/private URLs should use a server endpoint instead of this public controller path, because signing requires the secret key and salt.

AiThumbnailProviderInterface

Implement this interface on entities that can provide their own low-resolution URL for AI vision tasks. When present, the AI workflow uses getAiSmallUrl() instead of the full-resolution source — avoiding unnecessary costs on large images.

If the entity does not implement this interface, the workflow falls back to the full-resolution URL.

Presets

Each preset is expanded inline into the imgproxy processing string (rs:fit:W:H:0:0/q:Q/f:webp), so no server-side imgproxy preset config is required. Because every caller of a given preset emits a byte-identical URL, the imgproxy/S3 cache stays hot.

These names mirror the presets defined on the imgproxy server. We may later switch the builder to reference them by name (preset:NAME) once the server-side set is finalized — keep the two in sync until then.

Unsecured mode

If no key/salt is set, URLs are generated with the insecure token. This is fine for a local imgproxy instance running without signature verification, but never use it in production.

S3 / object-storage sources

imgproxy can fetch source images straight from object storage. Pass an s3://bucket/key (or gs://, abs://, swift://) URL anywhere this bundle accepts a source — the scheme passes through plain/ untouched:

Enable it on the imgproxy server with IMGPROXY_USE_S3=true (plus IMGPROXY_S3_REGION / credentials). See the imgproxy docs for GCS/ABS/Swift.

The encrypted-source (enc/) variant is not yet supported by this bundle (it needs a shared AES key). TODO.

Persistent cache & S3 output (v4 PRO)

v4 PRO can persist processed images in object storage as an internal cache, so you no longer need a caching reverse proxy in front of imgproxy. These are configured on the imgproxy server itself (env vars read by the imgproxy container — not by Symfony); this bundle scaffolds them in the recipe's env.txt and documents them here.

Key facts about the v4 cache: the URL signature is not part of the cache key (so you can rotate keys without invalidating the cache), /info responses are not cached, and there is no active invalidation beyond the cachebuster processing option / IMGPROXY_ETAG_BUSTER. Adapters: fs, s3, gcs, abs, swift. See https://imgproxy.net/blog/v4-caching/.

Related

• survos/media-bundle — uses this bundle for all imgproxy URL generation
• survos/ai-workflow-bundle — checks AiThumbnailProviderInterface to select the image URL for low-res AI passes