Weave Code
Mercure Laravel Package
symfony/mercure
Symfony Mercure is the PHP publisher component for the Mercure protocol, letting you push real-time updates from your app to browsers and HTTP clients. It handles JWT authentication and dispatching updates to a Mercure hub.
The Mercure Component allows to easily push updates to web browsers and other HTTP clients using the Mercure protocol.
Frequently asked questions about Mercure
- Do I need a Laravel package to use symfony/mercure, or do I have to wire it up myself?
- symfony/mercure is framework-agnostic and ships no Laravel service provider, facade, or publishable config, so you wire it yourself. In practice that means binding HubInterface as a singleton from your hub URL plus a TokenProviderInterface, and setting the protocol version explicitly. It works fine in Laravel, but treat the boilerplate as your own code to maintain.
- How do I install symfony/mercure in a Laravel application?
- Run composer require symfony/mercure lcobucci/jwt, then register your hub URL and a token provider in a service provider. LcobucciFactory signs JWTs from your hub secret, and FactoryTokenProvider wraps it with publish claims. Finally, bind Symfony\Component\Mercure\Hub to HubInterface and inject it wherever you dispatch updates.
- Which Laravel and PHP versions does symfony/mercure support?
- The component is framework-agnostic and tracks Symfony's PHP requirements rather than Laravel's, so it runs anywhere a supported PHP version and symfony/http-client are available. It has no Laravel version constraint of its own because there is no service provider. Check the package composer.json for the current PHP floor before committing to it on older Laravel installs.
- How do I push a real-time update to browsers from Laravel with symfony/mercure?
- Construct a Symfony\Component\Mercure\Update with the topic IRI and the JSON payload, then call publish() on the Hub. The component serializes the update and POSTs it to your hub, which fans it out to subscribed browsers over SSE. The browser side is plain EventSource or a Mercure client library, not part of this package.
- How does JWT authentication work with symfony/mercure?
- Your app mints a JWT authorizing publishing to specific topics, and the hub validates it against the shared secret. LcobucciFactory or WebTokenFactory handles signing, while FactoryTokenProvider or StaticTokenProvider supplies tokens to the Hub. In 0.9.0 the claims moved under authorization_details and now require iss, aud, sub, and client_id, so migrated token configs need updating.
- What changed in symfony/mercure 0.9.0 and how do I handle the protocol 1.0 default?
- Version 0.9.0 defaults the client to Mercure protocol 1.0 and changes the subscriber query parameter to match, renames the access token cookie to __Secure-mercure_access_token, and tightens the JWT claim shape. Pin the protocol version explicitly in config instead of relying on the default so an upgrade cannot silently flip the wire format. Upgrade the PHP client, the hub, and your browser subscribe URLs together, because a mismatch fails wholesale with no application-level error.
- Can I publish Mercure updates from a Laravel queued job?
- Yes, publishing from a queue worker is a sensible pattern, since the HTTP POST to the hub is a natural place for retries and backoff. Note that FrankenPHP's in-process mercure_publish() helper only works in worker-mode request context, not in CLI, so that optimization is incompatible with a standard queue:work setup. Pick one approach deliberately rather than assuming they compose.
- Is symfony/mercure a replacement for Laravel broadcasting, Pusher, or Reverb?
- No. It is only a publisher-side client for the Mercure protocol: it serializes an update, POSTs it to a hub, and the hub fans out over SSE. It is not a queue, a broadcast driver, or a replacement for Laravel's event dispatcher. It fits well downstream of committed domain events, but not for bidirectional features like presence, typing indicators, or multiplayer state.
- How do I test Mercure publishing in a Laravel application?
- Because Hub is a plain class behind HubInterface, you can bind a fake or mock in the container during tests and assert that publish() was called with the expected Update and topic. Add a lightweight smoke test against a real hub in CI to catch protocol or version mismatches that mocks cannot. Keep the hub version pinned in your infrastructure so the test reflects production.
- Is symfony/mercure actively maintained, and what are the alternatives?
- It ships inside the Symfony organization and tracks the Mercure spec, so maintenance follows Symfony's release cadence rather than resting on one maintainer. The 0.9.0 release is a breaking change on a 0.x line, so pin versions and budget upgrades as small projects. Alternatives include writing your own HTTP client for the hub's publish endpoint, or using Laravel Reverb and native broadcasting if you want a first-party Laravel path instead of a separate Mercure hub.
Weaver
How can I help you explore Laravel packages today?