Download the PHP package tito10047/progressive-image-bundle without Composer

Progressive Image Bundle

High-performance, Fully Responsive Images for Symfony.

This bundle handles everything you need for modern image management. From fully responsive images with Tailwind-like selectors, to blur placeholders, to content-addressed generation of every required size, on local disk or any cloud storage Flysystem supports.

🌍 Production Ready: This bundle is successfully deployed and running in production on live websites such as mostka.sk and vsetkosada.sk.

⚠️ Version 2.0 is experimental. It's a from-scratch DDD rewrite of the Variant pipeline and hasn't been tagged as a stable release yet — expect breaking changes before a final 2.0.0 tag.

📖 Full documentation: pgi.blue

✅ Requirements

• PHP 8.3 or newer — required by intervention/image (^4.2), the image-processing library the Variant pipeline is built on.
• Symfony 6.4, 7.4, or 8.1+ — see composer.json for the exact per-package constraints.

✨ Key Features

• 🎨 Blur & Error Placeholders: Users see a beautiful Blurhash placeholder while loading. If an image is not found, the bundle automatically displays a stylish error placeholder.
• 🖼️ Responsive via <picture>: Uses the modern <picture> element with multiple <source> tags for optimal browser selection and performance.
• 📱 Tailwind-like Selectors: Define responsiveness naturally directly in your template using familiar breakpoints.
• 🖼️ Retina Support: Automatically generates 1x, 2x (and more) versions for high-density displays.
• ⚙️ Content-Addressed Variant Pipeline: Every generated size is identified by a deterministic hash of its source + spec — no coordination needed across workers, and generation runs synchronously, on kernel.terminate, or async via Messenger, your choice.
• 🎯 Zero CLS (Cumulative Layout Shift): Automatically reserves space for the image, preventing content jumping during load.
• ⚡ Smart Preload: Automatically injects <link rel="preload"> for critical images (hero images), significantly improving LCP scores.
• 🧩 Built to Be Extended: Storage backend, image engine, post-processors, path resolution and URL generation are all swappable Symfony services.

🎨 Usage

Simply use the Twig component. The bundle takes care of everything — it automatically calculates the required image dimensions for each breakpoint, resizes the original, and generates all necessary variants on the fly.

📱 Selector Examples (Breakpoint Assignment)

The bundle supports flexible size assignment based on breakpoints you know from Tailwind or Bootstrap. For each selector, it automatically calculates the final pixel dimensions based on the container width defined by your CSS framework (Bootstrap or Tailwind) and generates the corresponding image.

What is a "container"? The bundle automatically detects your CSS framework (Bootstrap or Tailwind) and extracts the exact container widths for each breakpoint from its configuration. It then uses these values to calculate the precise pixel dimensions for your images.

Full syntax reference: The Twig Component → Sizes syntax.

🚀 Advanced Features

Point of Interest (PoI) Cropping

Define a focal point as pixel coordinates in the original image (e.g., pointInterest="544x320") so the most important subject stays in frame regardless of the target aspect ratio. The bundle finds the largest region of the original that matches the target ratio, centres it on the focal point, and scales the result — never slicing at original resolution. → Cookbook: Point of Interest Cropping

Smart Upscaling Protection

The bundle never generates an image larger than the original. If you need 1200px but the original is only 1000px, the bundle uses the original and prevents blurring.

Stream-based Metadata

To retrieve dimensions and Blurhash, the bundle doesn't load the entire image into RAM (no 20MB files in memory). It uses PHP streams to read only the necessary header bytes.

Content-Addressed Variant Generation

Every generated file is identified by an HMAC hash of its source + processing spec — the same request from any request or worker produces the same file, with no coordination needed beyond a short-lived lock. Choose when generation actually runs: inline in the request (sync), deferred to kernel.terminate, or asynchronously via Symfony Messenger (async, the default). → Variant Pipeline → Overview

Custom Modifiers & Filters

Extend the selector logic with your own modifiers (e.g., lg:4|circle), or add your own crop/resize/watermark filters via filter_sets. You can implement custom logic and even prioritize modifiers to override default behavior. → Cookbook: Custom Modifier

📦 Installation

See Getting Started for routing, cache pool, and full setup steps.

⚙️ Optional Configuration

Every available option is documented in the Configuration Reference.

📄 License

MIT License. See LICENSE for more information.

📚 Documentation

📖 Full documentation site: pgi.blue

The docs source lives in VitePress — run npm install && npm run dev inside that directory to preview changes locally.

📜 Changelog

All notable changes to this project are documented in CHANGELOG.md.