Download the PHP package id-sign/image-bundle without Composer

ImageBundle

Lightweight yet powerful image optimization bundle for Symfony. Provides a <twig:Image> component that generates <picture> tags with automatic resize, client-side format negotiation (AVIF/WebP), responsive srcset, blur placeholders, watermark profiles, and HMAC-signed URLs.

Built on ext-imagick with no additional dependencies — zero CLI tools, no third-party image libraries. Designed for performance: web server serves cached images directly via try_files with no PHP overhead. Extensible through interfaces for custom image sources and cache storage. Ready for FrankenPHP worker mode.

Requirements

• PHP 8.2+
• Symfony 7.4+
• ext-imagick

Installation

If Symfony Flex doesn't register the bundle automatically, add it to config/bundles.php:

Import the bundle routes:

Configuration

Usage

Basic

Output:

With blur placeholder and fit mode

With watermark

Custom quality

SVG passthrough

SVG files are served without any image processing — no resize, no format conversion, no srcset. The file is copied to cache on first request and served via try_files (public mode) or controller. No HMAC signature is needed.

Output:

Component attributes

All other attributes (alt, class, id, loading, data-*, aria-*, etc.) are passed through to the <img> tag.

src

Path to the source image relative to the configured source directory (default data/). The file must exist on the filesystem. For SVG files, no processing is applied — the image is served directly.

width

The intrinsic width of the generated image file in pixels — not the rendered CSS size. Used as the width HTML attribute (CLS prevention), as the main size in srcset, and as the upper bound for responsive breakpoints (SrcsetGenerator only emits device_sizes breakpoints ≤ width).

width is required and must be > 0 — omitting it (or passing 0) throws InvalidArgumentException at render time, applies to SVG as well. Pick a value that matches the largest pixel size the image will ever render at.

Picking the right value:

• Full-bleed image (class="w-full", sizes="100vw"): use the largest realistic render size, typically the largest relevant device_sizes entry (e.g. 1920 or 2048). The browser picks from all breakpoints ≤ width.
• Fixed-size image in a column: set width to the max CSS width the image can reach, optionally 2× for retina. Pair with a matching sizes, e.g. sizes="(min-width: 1024px) 500px, 100vw".
• width smaller than smallest device_sizes entry (default 640) produces a single-candidate srcset — on wide viewports the image gets stretched and looks blurry. Raise width, or narrow sizes to reflect the real layout.
• SVG: width only affects the <img width="…"> HTML attribute — no server-side processing happens. Pick the layout size you want reserved for CLS.

Mismatch between width and sizes wastes bandwidth or causes blurry rendering — see Picking sizes below.

Picking sizes

The sizes attribute tells the browser how wide the image will render at each viewport size. The browser multiplies that against DPR and picks the smallest srcset candidate ≥ the target. Without a correct sizes, responsive srcset is wasted bandwidth: the bundle default sizes="100vw" makes every browser download the largest candidate regardless of actual render size.

Set sizes to match the real CSS layout. Common patterns:

• Full-bleed (edge-to-edge): sizes="100vw" (bundle default — only correct if the image truly spans the viewport).
• Fixed max-width container with full-bleed mobile: sizes="(min-width: 1280px) 1280px, 100vw".
• Grid column, breakpoint-dependent: sizes="(min-width: 1024px) 33vw, (min-width: 640px) 50vw, 100vw".
• Fixed pixel size: sizes="400px".

Pass sizes as any other attribute — it propagates to every <source> and <img>:

height

The display height in pixels. When omitted and auto dimensions is enabled (globally via auto_dimensions config or per-component via autoDimensions prop), the height is automatically calculated from the source image's aspect ratio. When both width and height are provided with a fit mode, the server produces an image with exactly these dimensions.

autoDimensions

Overrides the global auto_dimensions config for this specific component instance. When true, height is auto-calculated from the source aspect ratio (if height is not provided). When false, auto-calculation is disabled even if the global config is enabled. When omitted (null), the global config value is used.

fit

Controls how the image is resized when both width and height are specified:

• cover — fills the target dimensions, cropping any overflow. Crop is always centered. For custom crop positioning, omit fit and use CSS object-fit + object-position instead — this gives full control over the visible area in the browser.
• contain — fits within the target dimensions, preserving aspect ratio (may leave empty space)
• scale-down — same as contain, but never upscales images smaller than the target

When omitted, the image is resized to the exact dimensions, which may distort the aspect ratio.

blur

Enables an inline blur placeholder. A tiny 10px-wide JPEG thumbnail is base64-encoded and rendered as a CSS background-image with filter: blur(20px). Once the full image loads, the placeholder is removed via onload. The placeholder is generated on-demand and cached on disk.

Can be set globally via blur.enabled in bundle configuration. The component attribute overrides the global setting.

quality

Output compression quality (1-100). Overrides the global default_quality setting. Lower values produce smaller files with more compression artifacts. Typical values: 60-80 for photos, 80-90 for detailed images.

watermark

Selects a named watermark profile to apply. Profiles are defined in watermarks in the bundle configuration, each with its own image, position, opacity, size, and margin.

• watermark="copyright" — applies the copyright profile
• :watermark="false" — disables watermark even if default_watermark is set globally
• Omitted — uses the default_watermark profile from config (null = no watermark)

Each watermark profile produces a separate cached file with a distinct URL, so the same image can exist with different watermarks or without one.

lossless

Switches the encoder into its lossless mode for formats that support it. Useful for screenshots, diagrams, UI assets, pixel art, and anything where quality=100 still visibly softens edges or introduces banding.

Format matrix:

Lossless encoding is 5-50× slower and produces 2-10× larger files than lossy at quality=80. For photographic content the visual difference is imperceptible; use lossless only where bit-exact pixels actually matter.

AVIF runtime requirement: libheif on Debian/Ubuntu 24.04+ ships without an AV1 encoder by default. Install libheif-plugin-aomenc on the host where PHP runs. Without it, AVIF lossless (and even lossy) encoding fails with no encode delegate for image format AVIF.

lossless can be set globally via the lossless config key and overridden per-component via the prop. The global default is false.

Serve modes

Public mode (default)

Cached images are stored at a path matching the URL. The web server serves them directly via try_files, PHP is only called on the first request per variant.

Nginx example:

Caddy example:

Controller mode

Every image request goes through PHP. Enables TTL-based cache invalidation -- expired variants are regenerated on the next request. Use this when you need access control or TTL-based refresh.

Custom route prefix

Import the bundle routes with a custom prefix to change the URL base path:

Update the bundle config to match:

Restricting access to authenticated users

Use controller mode with Symfony security to require authentication for image access:

In public mode, the web server serves cached files directly and bypasses PHP — Symfony's security firewall is not involved. Use controller mode when access control is required.

URL security

All raster image URLs are signed with HMAC-SHA256 derived from kernel.secret. The signature is part of the URL path, so any modification of parameters (width, height, quality, etc.) results in a 403 Forbidden response. This prevents cache exhaustion attacks where an attacker generates arbitrary image variants.

SVG URLs are not signed — SVG has no parameter variations, so HMAC would add no protection against cache exhaustion. See Security model below for the implications.

Security model

The bundle's threat model treats the configured source directory (default %kernel.project_dir%/data) as a publicly accessible asset tree. Any file under it can be fetched by anyone who knows or guesses the path:

• Raster images — attacker needs a valid HMAC signature (generated by your application) to access any specific (src, width, height, …) combination. They cannot forge arbitrary sizes or qualities. But the source file itself is public as soon as you render it anywhere with <twig:Image> or image_url().
• SVG files — no signature is required. Any .svg file under the source directory is readable by anyone who knows or guesses the path.

What this means for your project

Do not store access-controlled or non-public files under the source directory. The bundle does not enforce authorization. If you need:

• Authorization per user/role: use serve_mode: controller and add a Symfony firewall / #[IsGranted] in front of the bundle route. In public mode the web server serves cached files directly and bypasses Symfony security.
• Private storage with controlled access: implement a custom ImageSourceInterface pointing at a non-public location, and use serve_mode: controller with access control.

Path traversal and symlinks

Input paths (src values) are checked for .. and empty segments and rejected with 400/403 at the controller / cache layer. Symlinks are followed transparently — the bundle assumes any symlink inside the source directory was placed there intentionally by the administrator. If you don't want symlinks followed, audit your source tree (e.g. find data/ -type l) and remove unexpected ones before relying on the boundary.

Decompression bombs

max_source_bytes (default 20 MiB) rejects oversized source files before they reach Imagick. Also configure ImageMagick's policy.xml to restrict memory/width/height limits and disable dangerous coders (MVG, MSL, PDF, EPHEMERAL, URL). The bundle cannot substitute for a properly configured ImageMagick policy.

SVG and XSS

SVG files can contain <script> and event handlers that execute in your origin when the SVG is loaded as a top-level document. The bundle serves SVGs as-is — it does not strip scripts. If your source directory can receive user-uploaded SVGs, you must either sanitize before storage, or harden the served response (see Webserver hardening for SVG below).

Webserver hardening for SVG

In public mode the web server serves cached SVG files directly via try_files — PHP is not involved, so the bundle cannot set response headers on those requests. To block script execution in served SVGs, add a Content-Security-Policy: sandbox header in the web server configuration:

Nginx

Apache

Caddy

Content-Security-Policy: sandbox (with no directive value) applies the strictest sandbox: blocks scripts, forms, popups, plugins, and same-origin access. The SVG still renders as an image. This is cheap (single header in response), effective against <script> and on* handlers, and independent of the bundle.

If you cannot configure the web server and SVG hardening is a requirement, sanitize SVGs before they land in the source directory — e.g. using enshrined/svg-sanitize on upload.

Validating uploaded images

The bundle does not validate uploaded files — that is the host project's job, best done with Symfony's built-in Assert\Image constraint, which already covers size, dimensions, aspect ratio, MIME type, and corruption detection:

The bundle's max_source_bytes and max_width are runtime safety nets, not replacements for proper upload validation.

Image source

By default, source images are loaded from %kernel.project_dir%/data. To change this, override the service:

For custom sources (S3, Flysystem, etc.), implement ImageSourceInterface and register it:

Cache management

By default, all commands run in dry-run mode (showing what would be deleted). Add --force to actually delete files.

Purge all cached images

Purge a specific source image

Purge by age

Programmatic cache invalidation

Inject CacheStorageInterface to invalidate cache from your application code:

This deletes all cached variants (all sizes, formats, watermark combinations) for the given source image.

Programmatic URL generation

Generate optimized image URLs from PHP code (e.g. for API responses, emails):

Twig function image_url()

For contexts where you need a single image URL instead of a full <picture> tag — og tags, emails, JSON-LD, etc.:

Development

Docker test matrix

Run tests across all supported PHP versions using Docker:

License

MIT