Weave Code
Mercure Bundle Laravel Package
symfony/mercure-bundle
Symfony bundle that integrates the Mercure Component into full-stack Symfony applications, making it easy to add real-time push updates over Server-Sent Events. Provides configuration, dependency injection setup, and seamless hub integration for publishing and subscribing to live updates.
The MercureBundle allows to easily push updates to web browsers and other HTTP clients in the Symfony full-stack framework, using the Mercure protocol.
Frequently asked questions about Mercure Bundle
- Is symfony/mercure-bundle a Laravel package?
- No. It is a Symfony bundle that integrates the framework-agnostic symfony/mercure component into full-stack Symfony applications, and its config tree, autowiring and FrankenPHP hub factory are Symfony kernel features. In a Laravel app the realistic path is the underlying symfony/mercure client at ^0.9, wired through your own service provider. The bundle itself only pays off if you also run Symfony services in a mixed estate.
- How do I add Mercure real-time push to a Laravel application?
- Require symfony/mercure:^0.9 with Composer, then bind HubInterface or RemoteHubInterface as a singleton in a service provider built from values in config/mercure.php (hub URL, public URL, JWT). Publish from controllers or jobs through that binding and let browsers subscribe directly to the hub over Server-Sent Events. Budget roughly half a day to a day for the wiring, since there is no bundle config tree or autowiring to lean on.
- Do I need the Symfony MercureBundle installed to use Mercure with Laravel?
- No. The bundle only adds Symfony-side configuration and dependency injection, while the Mercure protocol and the client work independently of it. Installing it in Laravel gains you nothing because its extension and config tree are never loaded by the framework. Use symfony/mercure plus a small Laravel service provider instead.
- How do I configure JWT authentication for a private Mercure hub?
- For hubs configured with jwt.secret, the iss, sub and client_id claims must be present, and in v0.6.1 the default aud claim for protocol 1.0 publisher tokens includes the hub url. That means a hub reached at an internal URL by your app and a different public URL by browsers no longer needs the resource_identifier workaround. Keep the signing key and claim values in environment variables so every environment sets them explicitly.
- What changed in MercureBundle v0.6.1 compared with v0.6.0?
- v0.6.1 is a patch that adds url to the default aud claim of protocol 1.0 publisher tokens, making dual-URL topologies first-class without hand-configuring aud. The runtime Hub versus FrankenPhpHub factory selection introduced in v0.6.0 is unchanged, as is the 1.0 protocol default. The practical effect is less bespoke JWT configuration per environment and one fewer config branch to carry.
- How do I use a different internal and public Mercure hub URL?
- Set the hub URL your app publishes to and the public_url that browsers subscribe to separately; both default to null in v0.6.0 and later. Because a missing environment variable silently falls back to the embedded hub instead of failing loudly, validate the values at boot in your service provider. With protocol 1.0 the aud claim now carries the hub url, so publications are accepted without the resource_identifier workaround.
- Should I publish Mercure updates from queued jobs in Laravel?
- Yes, in most cases. Separating publish from subscribe pairs naturally with Laravel queues, keeping request latency independent of fan-out to many subscribers. Publishing from a job also gives you retries and a dedicated, short-timeout HTTP client for the hub. The http_client per-hub option is the highest-value runtime lever for isolating Mercure publish latency from your app's default HTTP client.
- How do I test Mercure publishing in a Laravel test suite?
- Because you own the container binding, you can swap HubInterface or RemoteHubInterface for a fake in your test case and assert on the Update objects your code publishes. That keeps tests fast and free of network calls to a real hub. Cover the JWT claim assembly separately so missing iss, sub or client_id values fail before deployment rather than at runtime.
- What are the alternatives to Mercure for real-time updates in Laravel?
- Laravel Reverb, Pusher, Soketi and other WebSocket brokers are the common alternatives, and Laravel Echo has first-class support for them. Mercure's difference is that it pushes over plain HTTP and Server-Sent Events, so there is no bespoke WebSocket infrastructure to run and it works with ordinary HTTP clients. Choose Mercure when you want simple server-to-client fan-out such as live notifications or dashboards rather than bidirectional channels.
- Is symfony/mercure-bundle production ready and actively maintained?
- The current release is v0.6.1 on top of the stable Mercure 1.0 protocol, which is what matters when sizing a long-lived commitment. The transport contract is documented and unchanged, and hub clustering and scale characteristics are unaffected by the patch. Note the pre-1.0 version number and the protocol coupling: hub and client should be upgraded together, and the protocol_version 0.x setting is only a short-lived bridge.
Weaver
How can I help you explore Laravel packages today?