Flashy Bundle Laravel Package

Getting Started

First, confirm what you are installing. mercuryseries/flashy-bundle is packaged as a Symfony bundle, not a Laravel package. It will not give you a Laravel service provider, publishable Blade views, or a config/flashy.php file. As a Laravel developer, the day-to-day answer is usually: do not install this in a Laravel app. Use the Laravel sibling mercuryseries/flashy, or Laravel’s native session flash plus a Blade component.

If you are working in a Symfony app and want the bundle’s rendering layer:

1. Install it, pinning a version compatible with your Symfony major:

   # Symfony 6.x projects
   composer require mercuryseries/flashy-bundle:^5.1
   

2. Register the bundle in config/bundles.php if Symfony Flex does not do it:

   Mercuryseries\FlashyBundle\FlashyBundle::class => ['all' => true],
   

3. Add any bundle configuration under config/packages/flashy.yaml after checking the bundle’s README for supported keys, usually theme/position/timeout style options.
4. Add the bundle’s render include or Twig helper once in your base layout, for example templates/base.html.twig.
5. In a controller, write to Symfony’s flash bag and redirect:

   $this->addFlash('success', 'Your changes were saved.');
   return $this->redirectToRoute('dashboard');
   

Where to look first:

• README.md for the exact Twig include/function and config keys.
• composer.json for Symfony/PHP version constraints and package type. As of v5.1.0 the constraint floor moves off Symfony 3 and Symfony 6.0 is supported — read it before assuming Symfony 7 works.
• src/FlashyBundle.php and src/DependencyInjection/ for configuration shape.
• src/Resources/views/ for the actual rendering template.
• src/Resources/public/ or asset references for CSS/JS dependencies.

The first real use case is a CRUD form: flash success after create/update, flash error after validation failure, render once in the layout, and let the redirect consume the message.

For Laravel specifically, use one of these instead:

// Native Laravel session flash
session()->flash('success', 'Your changes were saved.');
return redirect()->route('dashboard');

@if (session('success'))
    <div class="alert alert-success">{{ session('success') }}</div>
@endif

Or, if using the Laravel sibling package, the common pattern is a flashy()->success(...) helper in the controller and a single @include('flashy::message') in the layout. Verify the exact API in the sibling package’s README before adopting it.

Implementation Patterns

Keep message creation in controllers/services, rendering in layouts. Do not echo notification markup from deep inside business logic. Put the flash call at the HTTP boundary and include the render partial once in the base template. This avoids duplicate messages and keeps the UI layer swappable.

Use Symfony’s native flash bag as the contract. In Symfony, the standard pattern is:

$this->addFlash('success', 'Saved.');
$this->addFlash('error', 'Something went wrong.');

The bundle should render those types. If the bundle expects its own session key or service call, follow its README rather than mixing both approaches.

Render once, in the base layout. A typical Symfony base template include looks like:

<body>
    {% include '@Flashy/messages.html.twig' %}
    {% block body %}{% endblock %}
</body>

Adjust the Twig namespace/partial name to what the bundle documents. The important pattern is a single include near the top of the layout, not one include per page.

Map message types to your CSS framework. If the bundle supports themes, configure the theme once instead of overriding individual classes. If it does not, override the bundle template in templates/bundles/FlashyBundle/... and map success, error, warning, and info to your design system’s alert classes.

Use a service for non-controller code. If a domain service needs to queue a notification, inject Symfony’s FlashBagInterface or the bundle’s service rather than calling controller methods. Keep the message text short and user-facing.

Handle AJAX/Turbo/Inertia separately. Session flash messages are consumed on the next HTML render. For JSON APIs, return a flash payload explicitly and render it client-side. Do not assume the server-rendered partial will appear after a JSON response.

Example Laravel/Inertia pattern:

// HandleInertiaRequests::share()
'flash' => [
    'success' => fn () => $request->session()->get('success'),
    'error' => fn () => $request->session()->get('error'),
],

Then render the notification in your frontend layout from the shared prop.

Test the behavior, not the markup. In Symfony, assert the flash bag after a request:

$client->request('POST', '/posts', ['title' => 'Hello']);
$client->followRedirect();

$this->assertContains(
    'Saved.',
    $client->getRequest()->getSession()->getFlashBag()->get('success')
);

In Laravel, use assertSessionHas('success', 'Saved.').

Use it for transient UI feedback only. Success/error toasts after redirects are the sweet spot. Do not use flash messages for audit logs, email notifications, or anything that must survive more than one request.

Gotchas and Tips

The biggest gotcha: this is not a Laravel package. Do not add it to a Laravel app expecting php artisan vendor:publish or Blade views. Composer may install it, but you will inherit Symfony bundle structure and dependencies with no Laravel integration. Use mercuryseries/flashy or native Laravel flashes instead.

v5.1.0 is a compatibility release, and it cuts both ways. It added Symfony 6.0 support, which means the bundle is no longer automatically out of the question on a Symfony 6 app — previously you would have been fighting constraint resolution before writing a line of code. But it also dropped Symfony 3, so any legacy app still on Symfony 3 must stay on the old major. Treat the major bump as breaking: review composer.json constraints and run your test suite on a branch before upgrading an existing install. If you are on Symfony 7, nothing in this release helps you; expect the constraint to exclude it.

Maintenance risk remains, just less acute. The repo is still small (roughly 28 stars, no dependents), and the release cadence is driven by someone else’s upgrade needs — Symfony 6 arrived late, and Symfony 7 is not covered here. Pin an explicit constraint in composer.json, commit the lockfile, and be prepared to vendor or override the template yourself rather than waiting on a tagged release.

Confirm which flash mechanism the bundle uses. Some bundles render Symfony’s native addFlash() bag; others expose their own service or Twig function. If you call addFlash() and nothing renders, inspect src/Resources/views/ and the Twig extension/service to see which session key or method it expects.

Watch for duplicate rendering. Including the notification partial in both the base layout and a page template will render messages twice. Include it exactly once, usually in the base layout.

Escape untrusted content. Flash messages often include user input or model names. Keep Twig/Blade escaping on. Only use raw output for messages you fully control, otherwise you create an XSS path.

Asset handling differs from Laravel. The bundle may rely on CDN assets, published public assets, or Symfony’s asset/importmap setup. There is no Laravel Vite or Mix integration. On Symfony 6 the asset story is likely Encore or AssetMapper rather than whatever the bundle was originally built against — verify the CSS/JS actually loads after install. If you are in a Laravel app, this is another reason to use the Laravel sibling or a small Blade component.

Clear caches after config changes. In Symfony, run bin/console cache:clear after changing bundle config or overriding templates. After a major bump like v5.1.0, also clear the container build (bin/console cache:clear --no-warmup then warm) so stale bundle metadata does not mask a registration error.

Be careful with flash lifetime. Flash messages survive exactly one redirect. If an API request, health check, or intermediate redirect consumes the session, the user may never see the message. For multi-step flows, render the message on the immediate next page or use a dedicated notification table.

Extension points to prefer: override the Twig template in templates/bundles/FlashyBundle/, adjust the bundle config for theme/position/timeout, and decorate or wrap the bundle service if you need custom message formatting. In the Laravel sibling, publish config/views and wrap the helper in your own Notify service if you want a stable internal API.