Flasher Symfony Laravel Package

Getting Started

composer require php-flasher/flasher-symfony

With Symfony Flex the recipe registers Flasher\Symfony\FlasherBundle in config/bundles.php and drops config/packages/flasher.yaml. Without Flex, add the bundle manually and create that config file yourself — bin/console debug:config flasher is the fastest way to confirm it loaded.

Where to look first, in order:

1. config/packages/flasher.yaml — the default adapter and its options block. This is where 90% of "why does it look wrong" problems live.
2. {{ flasher_render() }} — the Twig function that emits the adapter CSS/JS plus the container the JS reads on page load. Put it once, in your base layout, just before </body> (styles are inlined, so head placement is optional).
3. vendor/php-flasher/flasher-symfony/src/ — small surface area: the bundle class, the DI extension, the Twig extension, and a response listener. Read it in ten minutes.

First use case — the canonical one, and the reason you install this at all:

// Controller
public function edit(Request $request): Response
{
    // ... handle form
    $this->addFlash('success', 'Saved.'); // plain Symfony flash, not this package
    return $this->redirectToRoute('home');
}

becomes:

public function edit(Request $request, FlasherInterface $flasher): Response
{
    // ... handle form
    $flasher->addSuccess('Saved.');   // queued, survives the redirect
    return $this->redirectToRoute('home');
}

The layout renders {{ flasher_render() }}, and the message appears on the page after the redirect.

Implementation Patterns

Inject the interface, not the concrete class. Flasher\Prime\FlasherInterface is autowired. Prefer constructor injection in services and method injection in controllers.

Two distinct flows — know which you want:

• addSuccess(), addError(), addWarning(), addInfo() — render on the current response. Use after a non-redirecting action, or when you're about to return a template directly.
• flash() / flashSuccess() — pushes into the session flash bag, delivered on the next request. Use with redirectToRoute(), which is the normal POST-redirect-GET shape.

Mixing them is the most common source of "nothing shows up" — queuing with flash() and then rendering a template without a redirect is fine, but queuing and never issuing a subsequent request is not.

Per-call adapter switching when one area of the app needs a different look:

$flasher->adapter('sweetalert')->addSuccess('Account deleted.');
$flasher->adapter('toastr')->addInfo('Draft autosaved.');

Install the matching frontend package (php-flasher/flasher-toastr, -sweetalert, -notyf, -noty, -pnotify) and set default: in YAML for the app-wide choice. Keep the version constraint identical across all flasher-* packages.

Form + validation. Flash inside the isValid() branch and redirect; flash the error summary in the !isValid() branch without a redirect so the user sees it alongside the field errors. Don't notify on every individual constraint violation — the form renderer already does that.

Live/partial updates (Turbo, HTMX, fetch). The server-side listener only injects into a normal full-page response. For fragments, either include {{ flasher_render() }} in the partial or call the JS global directly (flasher.success('...')) from your Stimulus controller. Do not render the helper in both the layout and the fragment — you'll double-fire every queued message.

Event-driven notifications. Symfony's event dispatcher is a clean place to attach notifications to things like LoginSuccessEvent — inject the flasher, queue in the listener, let the redirect deliver it. Watch that the listener fires before the response is sent.

Layout strategy. One flasher_render() in base.html.twig, and have every layout extend it. Apps that maintain several independent layouts (admin vs public) usually want a different adapter in each and a separate {{ flasher_render() }} call per layout.

Gotchas and Tips

• This repo is a read-only subtree split. Do not open issues or PRs here — they go to the php-flasher/php-flasher monorepo. Bugs you file against this repo may sit untouched indefinitely; the low star count reflects the split, not necessarily adoption of the parent project.
• Config is compiled. After editing flasher.yaml, run bin/console cache:clear (or cache:warmup in CI). Stale compiled config is a frequent phantom bug in dev.
• Assets are the other 50% of the problems. flasher_render() must actually be on the page, and the adapter package must be installed. If you use Webpack Encore or AssetMapper instead of the injected CDN/script tags, set root_script (and scripts/styles as needed) explicitly and verify with the browser network tab.
• Flash bag is consumed on read. Render flasher_render() twice on one page (e.g. layout + a reusable component) and the second read gets nothing — or, worse, the JS gets an empty payload and the first batch silently vanishes. Render once.
• No session, no flash. flash() against a stateless firewall or an API route has nowhere to persist. Use immediate addSuccess() there, and accept that JSON API clients won't see anything anyway.
• Not every response gets messages. The listener injects into ordinary HTML responses. StreamedResponse, binary downloads (CSV/PDF exports), and 204/302 bodies are not touched — don't queue a "Download ready" toast on the export request and expect it on the download.
• Full-page caching (Symfony HttpCache, Varnish) will happily cache your notification container markup. Exclude those routes or move to client-side fetch for authenticated pages.
• Adapter options are serialized to JSON and handed to the frontend library. JS function callbacks (onclick, beforeOpen, etc.) cannot survive that serialization — set them in your own JS init, not in YAML.
• Translations: if translate is enabled, messages go through the Symfony translator. Set the correct domain and make sure the locale is resolved at render time, not at queue time, or you'll render the previous request's language.
• Debugging checklist: debug:container flasher for the service, debug:config flasher for merged config, {{ flasher_render() }} output in the page source for the payload, and the JS console for adapter load errors.
• Extension point: a custom adapter is a service implementing the package's adapter interface, tagged and referenced from flasher.yaml. Run bin/console debug:container --tag to find the exact tag name in your installed version rather than trusting docs from an older release.
• Pin versions consistently. All php-flasher/* packages should share a major version; drift between core and an adapter produces confusing "option ignored" behaviour rather than a hard error.
• Not a substitute for real error handling. These are transient, dismissible, and rendered client-side. Server errors, failed payments, and anything auditable belong in logs and rendered error pages, with a toast as a courtesy only.