Picasso Bundle Laravel Package

Getting Started

This is a Symfony bundle (silarhi/picasso-bundle) rather than a Laravel package, so treat it as two things: a ready-made responsive-image pipeline if you're in Symfony, and a reference implementation of Glide + signed URL generation if you're in Laravel. Either way, the day-to-day value is the same — one template include turns an image into a srcset/src pair backed by Glide-managed transforms and cached URLs.

Minimal path:

1. composer require silarhi/picasso-bundle and register the bundle; if you're on Laravel, you'll instead pull in league/glide and borrow the URL-generating logic.
2. Go to the new documentation site (picasso-bundle.silarhi.dev) first — the README was trimmed in this release (PR #130) to point there, so don't expect the old README to carry the setup details anymore. Read the Performance page alongside the install page.
3. Configure the Glide cache directory and, if you serve originals from remote storage/CDN, a url loader.
4. Render your first image by including the bundled image.html.twig template. That template is the integration seam for everything else.

First use case: a product/blog listing page where each card needs a retina-friendly <img>. You get the transform URLs, the width/format variants and the signature handling without writing any of it.

Implementation Patterns

Keep the stock image.html.twig unless you have a strong reason not to. Since v2.5.0 it escapes src and srcset through the @internal picasso_escape_urls filter, which matches Twig's escaper output for URLs but far cheaper. Templates that override the file still work, but you silently opt out of that slice of the speedup. If you must override, override a sub-template or partial rather than the whole file, and diff against upstream on each release.

Let the router memoization be invisible. Glide now asks the router once per image + set of query keys, using placeholder values, then substitutes width, format and signature for subsequent URLs. In practice you change nothing — but do expect the router to be called fewer times per request than you might assume if you were profiling or relying on router side effects. A value the router would encode, a request-context change (worker mode), or a public-cache URL still goes through the router normally.

Signed vs public-cache URLs are the expensive branch. Signing and public-cache generation are explicitly excluded from the fast path, so if your config leans on public cache URLs you won't see the full 30% headline. Measure with your actual configuration rather than the docs' benchmark.

Worker mode is a first-class deployment target. If you run FrankenPHP worker mode, RoadRunner — or, in Laravel terms, Octane — the url loaders are now tagged kernel.reset and implement ResetInterface, so remote responses and temp files are closed between requests. In Laravel you'd replicate this with an Octane RequestReceived/RequestTerminated listener that resets your loader. If you write your own loader, tag/reset it the same way or you inherit the old leak.

Blade equivalent. The Twig include maps cleanly to a Blade component: a x-responsive-image component that takes the path, widths and formats, resolves URLs once per request (memoized in a request-scoped array/keyed cache), and emits srcset. Keep the memo keyed on image path + query-key set, mirroring how Glide does it, so context changes (locale, host) bust it.

Testing and caches. v2.5.0 moved the test kernel caches and Glide caches into the project's var/. In Laravel, point the Glide cache at storage/framework/cache/glide (or a dedicated disk) so test runs don't pollute bootstrap/cache or leave artefacts in the repo.

Gotchas and Tips

• No breaking changes in 2.5.0. The release is one perf change and one worker-mode bugfix. Upgrading from 2.4.x should be a drop-in; the only compatibility surface is a locally overridden image.html.twig.
• picasso_escape_urls is @internal. Use it inside the shipped template, never in your own templates — it's an optimisation detail, not API.
• The leak fix matters more than the speedup for some apps. Before this release, a url loader could hold an open connection to the remote host (or a temp file) for an undecodable image or a mid-flight failure, until the next miss on that loader. In long-running workers that's a slow resource bleed. If you're on 2.4 with worker mode and remote images, prioritise this upgrade; if you can't, restart workers on a schedule.
• Performance numbers are per-environment. 113 µs vs 170 µs per responsive image and 4.2 ms vs 5.5 ms for a 30-image Twig page was measured on Linux; macOS shows ~40%. Treat them as direction, not a contract — profile your own pages, and remember the gain shrinks if your pages are dominated by DB or template rendering elsewhere.
• Don't build logic on router call counts. Memoization is an internal optimisation and may change again; if you have middleware, listeners or analytics hooked to URL generation, verify they still fire the number of times you expect.
• Cache key hygiene with overrides. If you override the template and add your own query params (e.g. v=asset-version), those become part of Glide's query-key set and will reduce memoization hits — keep the parameter surface stable per request.
• Docs are now the source of truth. With the README trimmed, link the docs site in your team's onboarding notes; older blog posts referencing the long README will drift.