Ajax Flash Message Bundle Laravel Package

Getting Started

Caveat up front: the 2.0 release notes contain only a diff link, no changelog entries. Everything below is based on the package's documented purpose (session-backed flash messages delivered to AJAX clients) and holds for the 1.x line. Before adopting 2.0, read the actual diff — see Gotchas.

Minimal steps:

1. composer require kaistaerk/ajax-flash-message-bundle
2. Register the bundle in your kernel (bundles.php in Symfony Flex, AppKernel::registerBundles() otherwise) — this is a Symfony bundle, not a Laravel package, so there is no service provider and no package auto-discovery.
3. Import the bundle's routing/config if the README calls for it, then confirm the messages endpoint responds (usually a controller action returning JSON).
4. Drop the provided JS/Twig snippet into your layout so the front end knows where to fetch from.

Where to look first:

• The bundle's DependencyInjection/Configuration.php — it is the authoritative list of config keys. READMEs for bundles of this vintage drift from the code.
• The controller action that serves messages — that is the contract your JS depends on (URL, response shape, status codes).
• The Resources/public JS — tells you whether it polls, fetches once on load, or hooks into your own XHR.

First use case: after an AJAX form submit succeeds, set a flash in the controller, return your JSON payload, and let the client fetch and render the queued message on the next tick — replacing the "flash then full page redirect" flow that breaks in SPA-ish UIs.

Implementation Patterns

Set-then-fetch. The dominant pattern is: controller sets the flash as normal, your XHR completes, the client immediately GETs the messages endpoint and renders whatever came back. This keeps the server as the single source of truth and avoids duplicating message strings in JS.

Fetch-on-load only. Cheaper alternative — one request per page load, no polling. Fine for redirect-after-action flows, wrong for long-lived pages where several actions queue messages.

Front-end helper. Wrap the bundle's endpoint in a small JS module: pull() returns messages, render() appends DOM nodes, dismiss() clears them. Do not scatter fetch() calls across views; you will lose the "consume once" semantics.

The Laravel port. If you are assessing this package for a Laravel codebase rather than Symfony, the realistic move is to port the idea, not the code:

• A FlashToJson middleware that, on JSON requests, pulls session()->get('flash'), appends it to the response payload under a known key, and forgets it.
• session()->flash() in controllers stays idiomatic.
• A Blade partial + a few lines of JS on the client to render the flash key from any JSON response.

This gives you the bundle's behaviour with no cross-framework dependency and works with laravel/framework's session driver, including the database/redis drivers the bundle assumes nothing about.

Testing. Assert on the session store after the action (assertSessionHas), and separately assert the endpoint returns and then clears the queue. The "clears" half is the one people forget, and it is where double-render bugs hide.

Gotchas and Tips

2.0 is undocumented here. The release notes are a bare /compare/1.0...2.0 link. Treat this as a major-version bump with unknown contents and read the diff for: minimum PHP version, minimum Symfony version, namespace/class renames, config key renames, and any change to the messages endpoint's response shape. A 2.0 on a bundle this small is most often a Symfony-version floor bump plus a namespace move — but verify rather than assume.

It is a Symfony bundle. Composer will install it into a Laravel app without complaint, and nothing will work: no auto-discovery, no facade, no config publishing. Budget for the middleware port above.

Consume-on-read is the sharp edge. Flash messages are typically read-and-cleared. Two concurrent fetches (say, an interval timer plus an action handler) can result in one of them getting an empty array, or in a message being displayed twice if the clear happens after rendering fails. Serialise your fetch calls or debounce them.

Set-then-redirect loses messages in AJAX flows. If an action sets a flash and then triggers a client-side route change that never reloads the page, the message sits in the session until something else pulls it — appearing later, attached to the wrong action. Always pair a flash with an explicit pull.

Config quirks. Bundle registration order matters for anything that touches the templating or session layer. Config keys are nested under a single root (typically the bundle's short name); a typo'd key is silently ignored rather than erroring in many Symfony versions — dump the resolved container config to confirm.

Extension points. Look for a renderer/transport service you can override via a compiler pass or a service alias: that is the clean way to change the payload shape (e.g. add severity levels or i18n keys) without forking. Template/JS overrides are usually done by placing files at the documented path in your app, not by editing vendor code.

Debugging. If messages never arrive, check in this order: is the flash actually in the session (inspect the session store directly), does the endpoint return it, and does the client call the endpoint at all. The bundle sits on the boundary between all three, so the failure is rarely where it looks.