Download the PHP package marilenarm/turbo-toast-bundle without Composer

TurboToastBundle

Flash messages that keep your pages HTTP-cacheable.

Live overview → · Runnable demo app →, where you can click through every session-free flow.

A page that touches the session cannot be stored by a shared HTTP cache: Symfony marks it private, so Varnish or your CDN will never serve it. The classic $this->addFlash() does exactly that. It drags the session (and its lock) into otherwise stateless pages just to display "Item saved", and your anonymous page stops being cacheable because of a one-line notification.

This bundle takes the flash out of the session entirely, with two transports:

• Turbo Stream (AJAX/Turbo flows): the toast is generated and rendered in the same response, appended to the DOM, then auto-dismissed by a small Stimulus controller. There is no redirect and nothing gets stored.
• Short-lived cookie (classic full-page redirects): deferred toasts are serialized into a cookie at kernel.response time, and the container's Stimulus controller reads them client-side on the next page load. The page you redirect to keeps generic HTML, so it stays cacheable.

On pages that no longer open a session, three things change:

• Full-page caching behind Varnish or a CDN keeps working with flash messages, because the message travels in a cookie next to the page instead of inside it.
• Concurrent requests (several lazy Turbo Frames, for instance) stop queuing behind the PHP session lock.
• No session cookie is ever created just to show a notification.

When (not) to use it

Be honest with your profiler before adopting this. The session lock is paid once per request, whatever opens the session:

• Authenticated pages (firewall loads the token from the session), classic session-based CSRF, locale or cart in session: the session opens anyway, so removing flashes from it gains you nothing. Keep addFlash() there if you like it.
• Anonymous, cacheable pages (catalogs, content sites behind a CDN, stateless forms with stateless CSRF, lazy-frame-heavy pages): this is where the bundle pays off, as long as flashes were the last thing forcing a session open.

Profile first (Blackfire: look for session_start and serialized concurrent requests), then decide.

Requirements

• PHP >= 8.3, Symfony 6.4 (LTS), 7.x or 8.x
• symfony/ux-turbo and symfony/stimulus-bundle, UX 2.13+ or UX 3.x

Symfony 8 itself requires PHP >= 8.4.1, so that pairing rules out PHP 8.3. The same goes for UX 3, which requires PHP >= 8.4: on PHP 8.3, Composer keeps you on UX 2.

The pairings CI actually runs are listed in MATRIX (see Contributing): a sparse grid hitting both ends of the PHP range each Symfony branch supports, plus a --prefer-lowest run resolving the oldest dependency set the constraints allow.

Symfony 7.0–7.3 are accepted by the version constraint, since nothing in the bundle needs a newer API, but they are not tested: those branches are end-of-life and carry unpatched security advisories, so Composer refuses to install them by default.

Installation

Register the bundle (Flex does it automatically):

Add the toast container to your base layout:

The function renders the container div from the bundle configuration. DOM id, cookie name and Stimulus identifiers are injected from PHP, so a YAML change can never drift apart from the JS side. The rendered markup is data-turbo-permanent (existing toasts survive Turbo Drive navigations) and aria-live="polite" (inserted toasts are announced by screen readers).

[!NOTE] Controllers auto-registered from UX packages get namespaced Stimulus identifiers: marilenarm--turbo-toast--toast and marilenarm--turbo-toast--toast-container. If you need full control over the container markup, write the div manually and keep its Stimulus values in sync with the bundle configuration yourself.

Import the styles if you want them (they are meant to be overridden):

Usage

Use the trait in any controller:

Emit several at once:

To append a row and notify in the same response, include the toast partial in your own *.stream.html.twig:

Not in a controller? Inject MarilenaRM\TurboToastBundle\Toast\ToastRenderer and call ->render(new Toast(...)).

Classic redirects (non-Turbo flows)

When a flow performs a full-page RedirectResponse (post-login redirect, OAuth or payment callbacks, data-turbo="false" links, locale switch...), there is no Turbo Stream to render. Use deferToast() instead: a short-lived cookie carries the toast to the next page load, still without touching the session.

The verb follows what your controller returns, nothing is guessed:

toast() throws a LogicException when the current request does not accept Turbo Streams (no text/vnd.turbo-stream.html in the Accept header), because a stream rendered there would reach the browser as raw markup. Turbo forms send that header automatically; for anything else, use deferToast().

How the cookie transport behaves:

• serialized at kernel.response by ToastCookieSubscriber (SameSite=Lax, Secure on HTTPS, not HttpOnly since the JS must read it); the response is forced private so the Set-Cookie never enters a shared HTTP cache;
• consumed and cleared before rendering by the toast-container controller (initial load, every turbo:load, and non-Turbo navigations), so Turbo cache restores never replay a toast;
• rendered with textContent only: the client can modify the cookie, so treat its content as untrusted display text and never put sensitive data in it;
• capped at ~3.8 KB url-encoded; trailing toasts beyond the budget are dropped;
• never set on 5xx responses: a request that ended in a server error discards its queued toasts instead of promising success on the next page.

Each rule answers a concrete failure scenario. The security & hardening design notes walk through the threat model and explain why every protection is there.

Customizing cookie-rendered toasts

Two hooks, both keeping the message XSS-safe (textContent only):

Template — write the container manually (instead of turbo_toast_container()) and put a <template> target inside it. Its root element is cloned per toast, receives the toast--{type} class and the delay value; the message lands in the [data-toast-message] element (or the root when none is declared):

Event — take over rendering entirely by cancelling the marilenarm--turbo-toast--toast-container:append event:

Profiler

In debug mode, a Turbo Toast panel appears in the Symfony profiler: every toast emitted during the request, per transport (Turbo Stream / cookie), with the queued / transported / discarded counts for the cookie path. The traceable decorators are only wired under kernel.debug, so production pays nothing.

Configuration

Contributing

The test pipeline runs in Dagger, so the matrix you run on your laptop is the one CI runs. That closes the "works on my machine" gap, and the Symfony version list is not duplicated in a workflow file. With the Dagger CLI and a container runtime installed:

The tested combinations live in MATRIX, in .dagger/src/turbo_toast/main.py. Each cell pins Symfony through symfony/flex and the UX major through composer update --with, then asserts that both really landed on the versions under test, so a cell cannot go green while quietly resolving a newer Symfony or the other UX major.

Widening the supported range means editing composer.json, adding a row to MATRIX, and updating the Requirements section above plus the version strings in docs/index.html (grep -n 'Symfony 6.4' docs/index.html finds them).

If this bundle saved your pages from the session lock, you can buy me a coffee ☕