Flash Alert Bundle Laravel Package

Getting Started

The bundle is Symfony-first, not Laravel: treat it as a drop-in replacement for manually looping over app.flashes in your base layout. Minimal path:

1. Install it:

   composer require ras/flash-alert-bundle
   

2. Register it. With Symfony Flex this is usually automatic; otherwise add it to config/bundles.php:

   Ras\FlashAlertBundle\FlashAlertBundle::class => ['all' => true],
   

3. Look first at the bundle’s Resources/ (or assets/) directory and its DependencyInjection/Configuration.php. That tells you three things you need immediately:
   • the Twig function/helper name used to render the alert container,
   • where the pure-JS file lives (usually Resources/public/js/...) and how to publish/link it,
   • which config keys exist under flash_alert: in config/packages/.
4. Wire it once in your global layout (templates/base.html.twig): include the JS asset and render the alert mount point just before </body>.
5. First real use case: a form POST that redirects with a success flash.

   // Controller
   $this->addFlash('success', 'Saved successfully.');
   return $this->redirectToRoute('dashboard');
   

   Then confirm the alert appears on the redirected page — not on the POST response.

If nothing appears, you have almost certainly missed step 4 or the flash was consumed on the POST request itself.

Implementation Patterns

Global layout mount (the core pattern). Render the bundle’s container once in base.html.twig, after your JS bundle but before </body>. Keep it out of individual templates; flashes are session-scoped and can appear on any page.

Standard controller flow. Use Symfony’s native addFlash($type, $message) rather than bundle-specific methods unless the README documents otherwise. The bundle is a renderer, not a replacement for the flash bag. Typical types to standardize on: success, error, warning, info.

Mapping types to your CSS. Most flash-alert bundles expose a config or an option to map types to CSS classes. Decide your mapping early (e.g. success → alert-success) and keep it in config/packages/flash_alert.yaml so controllers stay presentation-agnostic.

Multiple flashes in one request. Expect a queue: several addFlash() calls in a single request should render as stacked alerts. Test this explicitly — one alert is the happy path, three is where ordering and auto-dismiss bugs show up.

Auto-dismiss vs. persistent alerts. Use the JS timing option for success/info, but disable auto-dismiss for error so validation messages and failed-payment errors aren’t lost. If the bundle only offers a single global timeout, render errors through your own template and reserve the JS path for transient notices.

Redirect-after-POST is the intended workflow. The pattern the bundle is built around is: flash on POST → 302 → render on GET. Don’t try to render alerts directly into the POST response for form validation failures; use Symfony form errors there and reserve flash alerts for post-redirect outcomes.

Integration with partial navigation. If you use Turbo/Turbolinks/hotwire-style navigation, the JS must initialize on each page swap, not just DOMContentLoaded. Check whether the bundle’s script is idempotent; if not, add a listener for your navigation event that re-runs the initializer.

Testing pattern. In functional tests, assert on $client->getRequest()->getSession()->getFlashBag()->peek('success') before following the redirect, and assert on the rendered container markup after. That separates “flash was set” from “flash was rendered.”

Gotchas and Tips

• This is not a Laravel package. ras/flash-alert-bundle targets Symfony’s Session/FlashBag and Twig. In Laravel, use session()->flash() with your own Blade component instead; do not attempt to install this via Composer into a Laravel app expecting it to work.
• Flash bag consumption is the #1 pitfall. Flashes are read-once. If you render the container in a layout that also runs during the POST request (e.g. an AJAX POST returning HTML), the message is consumed and vanishes on redirect. Ensure the mount point renders only on full GET responses, or guard it.
• Asset publishing/discovery. With Webpack Encore or AssetMapper the bundle’s Resources/public files may not be auto-exposed. Check whether you need assets:install, an Encore addEntry, or an AssetMapper path config. A 404 on the JS file means alerts silently never initialize.
• Silent failure mode. If the JS doesn’t load or the container element ID/class doesn’t match what the script queries, you get no alert and no console error. Debug order: (1) does the container HTML render? (2) is the script in the network tab? (3) does the script’s selector match your DOM?
• HTML escaping. Flash messages are strings and should be escaped by default. Do not pass raw HTML into flashes to get bold/links; if the bundle offers a raw/html option, treat it as an XSS vector and only use it with trusted, server-generated content.
• Session configuration. If your app uses stateless APIs, multiple firewalls, or session: false for some routes, flashes won’t persist. Confirm the redirect target shares the same session.
• Cache-busting. The “last release” date and low star count suggest infrequent maintenance. Pin the version in composer.json and vendor/copy the JS if you need to patch it, rather than relying on upstream fixes.
• Extension point to prefer. If the default markup doesn’t fit your design system, override the bundle’s template via templates/bundles/FlashAlertBundle/... rather than forking the JS. That keeps upgrades and security patches cheap.
• Low ecosystem signal. With ~23 stars and 0 dependents, expect thin docs and no Stack Overflow coverage. Read the bundle source (it’s small) before debugging blind; the Twig extension and JS initializer are usually the only two files that matter.