Ux Notify Laravel Package

Getting Started

v3.6.0 is a maintenance/feature release of symfony/ux-notify — a Symfony UX package, not a Laravel package. Nothing here is Laravel-native, so the first decision is whether Mercure/SSE is worth it versus Laravel's first-class broadcasting stack (Reverb/Pusher + Echo).

• Check the constraints before installing: PHP 8.1+, Symfony 6.4/7.x components, a running Mercure hub. composer require symfony/ux-notify; JS side npm i @symfony/ux-notify.
• Look first at Symfony\UX\Notify\NotifierInterface::send(string $topic, array $payload) and the @symfony/ux-notify JS export createNotificationStream().
• First use case: push a notification to a single user's channel (e.g. /users/42) after an order ships, replacing a polling endpoint.
• Because the Symfony bundle/DependencyInjection layer does not activate in Laravel, budget for manual wiring: a singleton binding that constructs the notifier around a Mercure Hub instance.

Implementation Patterns

• Server publish: $notifier->send('/users/42', ['type' => 'order_shipped', 'order' => 123]); Topic is a Mercure topic IRI, payload is JSON-serializable.
• Client subscribe: const stream = createNotificationStream(hubUrl, { topics: ['/users/42'] }); stream.onmessage = e => handle(JSON.parse(e.data));
• Laravel wiring: bind NotifierInterface in a service provider; either pull symfony/mercure's Hub or skip the Symfony stack entirely and publish with Laravel's Http client to /.well-known/mercure using a publisher JWT cookie/header. The latter is fewer dependencies and easier to test.
• Event-driven fan-out: dispatch from a queued listener (ShouldQueue) or wrap in DB::afterCommit() so subscribers never receive notifications for rolled-back transactions.
• Topic design: per-user (/users/{id}), per-tenant (/tenants/{id}), and per-resource topics; keep payloads thin and let the client re-fetch authoritative data.
• Auth split: publisher JWT carries mercure.publish; subscriber JWT carries mercure.subscribe with topic patterns. Generate with lcobucci/jwt or Symfony's Mercure JWT factory; keep publisher secrets server-side only.
• Coexistence: if the app already uses Echo/Reverb, run Mercure alongside rather than migrating — createNotificationStream is isolated and won't conflict.

Gotchas and Tips

• No Laravel integration ships here. Don't expect a service provider, config file, or facade; the Symfony bundle auto-configuration simply won't run.
• MercureBundle ^0.5 / ^0.6 support (features #4036, #4056) only affects you if you install the Symfony bundle path. Standalone Laravel + symfony/mercure is unaffected by these constraints.
• New conflict with symfony/asset-mapper >= 8.2 (bug #3919). Irrelevant unless you also run the Symfony bundle with AssetMapper; don't try to co-install in one app.
• README install snippets now use an explicit X.Y.Z placeholder (#3907). If you copy a composer require / npm i line from the docs, pin the real version yourself — the literal X.Y.Z will fail.
• Shipped assets are checked against Web Platform Baseline (#3904). The prebuilt bundle targets modern browsers; if you must support older ones, add your own transpile step rather than assuming the dist file covers you.
• Topic mismatch is the #1 failure. /users/42 ≠ /users/42/ ≠ users/42. A 401/406 in the browser Network tab usually means JWT claim/topic mismatch, not a code bug.
• Debug in two halves: curl -d 'topic=/users/42' -d 'data={"ping":1}' <hub>/.well-known/mercure isolates server publishing from client subscription.
• SSE and PHP-FPM don't mix well. Never proxy long-lived SSE through PHP workers; the hub should terminate the connection at the reverse proxy.
• Extension point: createNotificationStream accepts a custom EventSource factory — use it for reconnect/backoff and heartbeat tuning rather than forking the package.