Ux Notify Laravel Package

Getting Started

This is a Symfony UX bundle (krystal-sf/ux-notify), not a Laravel package — so for a Laravel dev the "getting started" is really twofold: boot it inside a Symfony app if you're working in a Krystal project, or read it as a reference implementation to port into Laravel. There's no Packagist support signal (0 stars, 0 dependents), so assume you'll be reading src/ before you trust it.

Minimal boot in a Symfony app:

composer require krystal-sf/ux-notify
php bin/console assets:install

// config/bundles.php
return [
    KrystalSF\UxNotify\UxNotifyBundle::class => ['all' => true],
];

If the app uses Symfony UX with importmap/Stimulus, the bundle's controller should register itself; with Webpack Encore you'll usually need to import its entrypoint manually in assets/app.js. Check src/DependencyInjection/ for the config tree — that's where the toast position, timeout, and transport settings live.

Where to look first, in order:

1. src/ — the injected service (typically something like UxNotify or Notifier) and any Twig extension.
2. templates/ — the Twig component(s) rendering the toast/badge container.
3. assets/ — the Stimulus controller; this is where timing, stacking, and dismissal behavior actually live.
4. README for a config/packages/ux_notify.yaml sample.

First use case: flash a toast after a form submit.

#[Route('/orders', methods: ['POST'])]
public function store(Request $request, UxNotify $notify): Response
{
    // ... persist
    $notify->success('Order created.');
    return $this->redirectToRoute('orders_index');
}

Then drop the container component into your base layout, once, before </body>:

{{ ux_notify_render() }}  {# name will vary — grep templates/ for the component tag #}

If the redirect doesn't show the toast, the package is using session flashes and your layout isn't rendering the container on the target page — the single most common integration miss.

Laravel translation: the equivalent is flasher/laravel-flash plus a Blade partial, or spatie/laravel-flash. The pattern is identical; the package isn't portable as-is.

Implementation Patterns

Service injection over helpers. Prefer constructor-injecting the notifier into controllers and services rather than calling a global helper. It makes the class testable and lets you swap the implementation for a null notifier in unit tests.

final class OrderService
{
    public function __construct(private UxNotify $notify) {}

    public function ship(Order $order): void
    {
        // ...
        $this->notify->info("Order #{$order->id} shipped.");
    }
}

Level as an enum, not a string. If the package ships an enum (Level::Success, etc.) use it. String levels are the first thing to break when someone typos 'sucess' — an enum turns that into a static-analysis error.

Decouple emission from rendering. The valuable pattern here is: services emit notifications into a queue/session, and the Stimulus controller on the frontend renders them whenever the page loads or a Mercure message arrives. Keep that boundary clean in your own code — don't call the frontend directly, don't hardcode HTML in a service.

Real-time notifications via Mercure. If the bundle wires into Symfony's Mercure hub, the high-leverage pattern is a domain event + listener:

#[AsEventListener]
final class OrderShippedListener
{
    public function __invoke(OrderShipped $event): void
    {
        $this->notify->success("Order #{$event->orderId} shipped.");
    }
}

This keeps controllers thin and means the same notification fires whether the action came from HTTP, a console command, or a message handler. In Laravel you'd mirror this with events/listeners plus broadcasting on a private channel.

Request-scoped vs. persistent. Two distinct mechanisms, easy to conflate:

• Flash — survives one redirect, session-backed. Use for post-redirect-get flows.
• Stream — pushed over Mercure/SSE, rendered by the Stimulus controller without a reload. Use for background job completion and cross-tab updates.

Pick deliberately. Using stream for a simple post-submit message means you're paying WebSocket infrastructure for a flash.

Testing. Assert on the notifier interface, not on rendered HTML:

$notify = $this->createMock(UxNotify::class);
$notify->expects($this->once())->method('success')->with('Order created.');

For the frontend half, a functional test that follows the redirect and asserts the toast markup appears is worth having once — it catches the "container not rendered in layout" class of bug.

Integration tips. Register the container component in base.html.twig only, never in partials, or you'll get duplicate stacks. If you use Turbo, make sure the container lives outside the Turbo frame that gets replaced — otherwise the controller re-initializes and drops queued toasts.

Gotchas and Tips

It is Symfony-only, and effectively unsupported. Zero dependents and no stars means: no Stack Overflow answers, no issue triage, no security advisories. Pin it to an exact tag or a commit SHA, vendor it, and be prepared to fork. Read composer.json for the minimum-stability and Symfony version constraint — an abandoned bundle pinned to Symfony 6.3 will silently block your 7.x upgrade.

Check what it actually delegates to. Most "UX Notify" bundles are thin wrappers over symfony/notifier plus a Stimulus controller. If so, the real surface area is tiny and you can inline it into your app in an afternoon — which is usually the right call for a Laravel-bound team rather than maintaining a Symfony dependency you can't use.

Session flash timing. If notifications are session-backed, they render on the next request. A controller that calls success() and returns a template directly (no redirect) may show nothing, or show the message twice if the layout and the action template both render the container. Debug by inspecting the session in the profiler.

Asset registration is the #1 silent failure. Toast "not working" almost always means the Stimulus controller never booted: wrong importmap entry, missing assets:install, or Encore not importing the bundle's entrypoint. Check the browser console for a Missing controller warning before touching PHP.

Timeout and stacking config lives in two places. PHP-side config controls payload shape; the Stimulus controller controls display duration. If a toast vanishes too fast, the fix is in assets/, not YAML — and if you're consuming the package read-only you may need to override the controller in your app's assets/controllers.json.

Escaping. Notification messages often interpolate user data ("Order {id} shipped"). Verify the Twig component uses autoescaping and does not |raw the message. If it does, sanitize at the service boundary.

Extension points to look for: a NotifierInterface or similar to swap the transport, a Twig namespace for overriding templates, and a tagged-service/compiler-pass hook for custom renderers. If none exist, the package is not designed for extension and you should not build on top of it.

Porting to Laravel. If you're evaluating this for the pattern rather than the code: symfony/notifier → laravel-flash or a small Notifier service bound as a singleton; the Stimulus controller → Alpine.js x-data toast stack or Livewire dispatch('notify'); Mercure → Laravel Reverb/Echo private channels. The architecture maps cleanly; nothing here justifies pulling Symfony into a Laravel app.

Verdict for a Laravel dev: read it for the emit/render separation and the flash-vs-stream distinction, adopt neither the dependency nor the code. If you're actually staffed on a Krystal Symfony project, pin the version, read src/ end-to-end first (it's small), and budget time to fork.