Flag of Ukraine
SymfonyCasts stands united with the people of Ukraine

Mercure: Pushing Stream Updates Async

Keep on Learning!

If you liked what you've learned so far, dive in!
Subscribe to get access to this tutorial plus
video, code and script downloads.

Start your All-Access Pass
Buy just this tutorial for $12.00

With a Subscription, click any sentence in the script to jump to that part of the video!

Login Subscribe

Turbo streams would be much more interesting if we could subscribe to something that could send us stream updates in real time.

The Use-Case: Pushing Streams Directly to Users

Like, imagine we're viewing a page... and generally minding our own business. At the same moment, someone else - on the other side of the world - adds a new review to this same product. What if that review instantly popped onto our page and the quick stats updated? That would be... incredible!

Or imagine if, in ProductController, inside of the reviews action, after a successful form submit, we could still return a redirect like we were doing before... but we could also push a stream to the user that updates some other parts of the page, like the quick stats area. I said earlier that returning a redirect and a stream isn't possible. But... that's not entirely true.

The truthiest truth is that both of these scenarios are totally possible. How? Turbo Streams comes with built-in support to listen to a web socket the returns Turbo Stream HTML. It also supports doing that same thing with server-sent events, which are kind of a modern web socket: it's a way for a web server to push information to a browser without us needing to make an Ajax call to ask for it.

Hello Mercure!

And fortunately, in the Symfony world, we have great support for a technology that enables server-sent events: Mercure. Mercure could... probably be its own tutorial, so we'll just cover the basics.

Mercure is a "service" that you run, kind of like your database service, Elasticsearch or Redis. It allows, in JavaScript for example, to subscribe to messages. Then, in PHP, we can publish messages to Mercure. Anything that has subscribed will instantly receive those messages and can do something with them. If you're familiar with WebSockets, it has a similar feel.

Installing the Mercure Libraries

We're going to get Mercure rocking... and it's going to really make things fun. To start, install a package that makes it easy to work with Mercure and Turbo. At the command line, run:

composer require "symfony/ux-turbo-mercure:^1.3"


The symfony/ux-turbo-mercure is deprecated in favor of symfony/ux-turbo which already contains the cool Mercure stuff. Just install symfony/mercure-bundle to get it working:

composer require symfony/mercure-bundle

Or to get the version used in the tutorial, continue with:

composer require "symfony/ux-turbo-mercure:^1.3"

This installs several things. First, a PHP library called mercure that helps talk to the Mercure service in PHP. Second, a MercureBundle that makes that even easier in Symfony. And third, a symfony/ux-turbo-mercure library that gives us a special Stimulus controller that helps Mercure and Turbo Streams work together. Go team!

This executed a recipe... so run git status to see what it did.

git status

Ok cool. Let's look at .env first. At the bottom, we have three new environment variables that will help us talk to Mercure. More about these in a few minutes. The recipe also modified controllers.json. Remember: this means that a new Stimulus controller is now available that lives inside this bundle. We'll use that 2 chapters from now.


Instead of a new section in this file, find the existing `@symfony/ux-turbo section. It will have a key called mercure-turbo-stream. Change its enabled key to true` to activate the Stimulus controller we'll be using.

This also enabled a bundle... and added a new library to our package.json file. We've seen this several times before with UX packages: this adds a new package to our project... but instead of downloading the code, it already lives in the vendor/ directory.

To get that part properly set up, near the bottom of the terminal output, it tells us to stop Encore and run yarn install --force.

In the other tab, hit Ctrl+C to stop Encore and run:

yarn install --force

When that finishes, restart Encore:

yarn watch

Ok, we just installed some PHP and JavaScript code that's going to help us communicate with Mercure. But... we don't actually have a Mercure service running yet! That's like installing Doctrine... but without MySQL or Postgresql running!

So next, let's get the Mercure service running. There are a bunch of ways to do this. But if you're using the Symfony binary web server like we are... then... it's already done!

Leave a comment!

Login or Register to join the conversation
jmsche Avatar
jmsche Avatar jmsche | posted 9 months ago | edited | HIGHLIGHTED

As symfony/ux-turbo-mercure has been abandoned (files are located in symfony/ux-turbo), you now should run composer req symfony/mercure-bundle instead.
Also, set enabled to true in assets/controllers.json for the mercure-turbo-stream config.

2 Reply
CDesign Avatar
CDesign Avatar CDesign | jmsche | posted 4 months ago | edited

I just wanted to add to jmsche's post. I'm running this tutorial with Symfony 5.3 and PHP 8.1 (as of 5/24/2023).

When attempting to run composer require symfony/mercure-bundle I get the following error:

The following exception probably indicates you have misconfigured DNS resolver(s)

In CurlDownloader.php line 365:
  curl error 6 while downloading https://flex.symfony.com/versions.json: Could not resolve host: flex.symfony.com

To resolve this, I first had to update symfony/flex with composer update symfony/flex --no-plugins --no-scripts (per this post) and I also had to downgrade PHP to 7.4 (from 8.1).

Then mercure installed fine. Hope that helps someone!

1 Reply
Fabrice Avatar
Fabrice Avatar Fabrice | posted 1 year ago

Hey! Is there really a Mercury tutorial planned? That would be great ! If yes, for when could we have access to it?

Do you plan to do a Mercury training again combining it with Turbo, or this time, with a traditional Symfony project not using Turbo?

1 Reply

Hey Kiuega,

Thank you for your interest in SymfonyCasts tutorials. Yes, we do plan a tutorial about Turbo... and it might happen this year. About Mercury - I'm not sure, but most probably it might be covered / partially covered in that Turbo tutorial. Though, we don't have specific plans for this yet, and we have some other pending tutorials that will be released first. In short, we would love to release a tutorial about Mercury and Turbo, but I can't tell you when it might be released yet.

Thank you for your patience!


1 Reply
Dang Avatar

Hello guys,
In the Mercure's doc there are a feature named Discover which is not very clear for me of its purpose. So if I understand correctly, the client will make a request to a controller Discover, it will add the Link with Mercure public hub URL in the Header so the client code could extract to get that URL to subscribe. From the docs :

class DiscoverController extends AbstractController
    #[Route('/discover',name: 'app_discover_mercure')]
    public function discover(Request $request, Discovery $discovery): JsonResponse
        // Link: <https://hub.example.com/.well-known/mercure>; rel="mercure"

        return $this->json([
            '@id' => '/books/1',
            'availability' => 'https://schema.org/InStock',

But with twig we have a function for example {{ mercure("mytopic")|escape('js') }} to get the full link of mercure URL and topic. Or, why in controller we don't get the hub URL and then just return it. Why we want to make another request to DiscoverController just to get that Hub URL for the client?

Victor Avatar Victor | SFCASTS | Dang | posted 4 months ago | edited

Hey Dang,

Most probably you don't need it if you are not sure why it might be useful for you :) The most preferable way - use that mercure() Twig function if it fits your needs well. What about the discovery feature - I didn't use it on my own, so difficult to say. It might be useful for third-party clients, e.g. who are using your Mercure Hub from a different website, or maybe even via API requests, as usually those headers are mostly used in API.

In other words, I think it might be useful for all your clients who want to know your Mercure hub URL outside of your project. But in your project, it's more convenient to use that Twig function that would help you to build the correct URL to the specific resources for you.

I hope it makes sense to you :)


Nick-F Avatar
Nick-F Avatar Nick-F | posted 9 months ago | edited

I do not think you should be advertising for Mercure's "managed service".
I tried it. There are no free trials or demonstrations of how the managed service works so you're basically throwing $30 into a black hole and hoping something cool pops back out.
I get in, and the user interface is extremely oversimplified with absolutely no help or guide on how to set it up. All of the documentation on the site have to do with setting up a local demo hub on your own server, and I could find nothing on actually using the managed service.
I tried my best, but kept getting ssl and authorization errors and there's no way to try and fix it, you don't have access to the Caddyfile.
I ended up going through the grueling process of setting up a mercure hub on an aws server myself and got it to work,
but that money is gone.

dunglas Avatar
dunglas Avatar dunglas | Nick-F | posted 9 months ago | edited

Hi Nick,

I am very sad to hear that you had a bad experience with Mercure.

The interface is intentionally simple, to use the managed version you just need to set up a secure JWT key. Optionally, you can set a custom domain (for CORS and performance) and use the user interface to set the options available on the free version as well. Everything works exactly as with the free version, and you have access to the same options without having to deal with a Caddyfile (the managed version uses a custom build on top of the free version under the hood).

If you (or anyone else in the same situation) try our service again and have problems with the configuration, support (contact@mercure.rocks) will be happy to help. Also, feel free to contact us at the same address for a refund.

I hope that you'll give us another try in the future.


Hi Nick!

Oh man, that is a terrible experience - but I really appreciate the honest feedback. I'm going to pass this along to someone I know in the Mercure space - hopefully it can be useful to them. And I'd like to get some answers from them also to make sure it's a smoother process. The idea of mentioning it in the tutorial is so that you could have an EASIER time using Mercure - but you had the opposite :/. Btw, I'd also message the Mercure people and ask for a refund - you can't get your time back, but they should refund your money.


Roozbeh S. Avatar
Roozbeh S. Avatar Roozbeh S. | posted 1 year ago | edited

Hi Ryan,

I'm working on getting connection between Mercure and React Native Mobile App and I am almost disappointed on finding a way how it works!
The Mercure debugging tools works on my local Host and I can publish data on client side (i have tested this with a simple Symfony page) and when it comes to React Native I use Server Sent Event(SSE) to listen to updates from Back-end! But I'm not receiving anything!

Any help or tip will be appreciated!

the library i use is the following <React Native EventSource>

my mercure hub url: <http://localhost:3000/.well-known/mercure&gt;
my mercure publish url <https://myIP:3000/notifications&gt;
here is my react native code

class App extends React.Component {
  componentDidMount() {
    const url = new URL("http://myIP:3000/.well-known/mercure");

    const es = new EventSource(url);

    const listener: EventSourceListener = event => {
      if (event.type === "open") {
        console.log("Open SSE connection.");
        const data = JSON.parse(event.data);
      } else if (event.type === "message") {
        const data = JSON.parse(event.data);
      } else if (event.type === "error") {
        console.error("Connection error:", event.message);
      } else if (event.type === "exception") {
        console.error("Error:", event.message, event.error);

    es.addEventListener("open", listener);
    es.addEventListener("message", listener);
    es.addEventListener("error", listener);
    es.addEventListener("ping", event => {
      console.log("Received ping with data:", event.data);
    es.addEventListener("clientConnected", event => {
      console.log("Client connected:", event.data);
  render() {
    return (

Hey Roozbeh S.!

Hmm, unfortunately, I'm also not sure what could be the problem or how you could debug better :/. Are you able to go directly to http://myIP:3000/.well-known/mercure?topic=https%3A%2F%2FmyIP%3A3000%2Fnotifications in your browser and see the updates being loaded there? You may have already done this - I wasn't totally sure you have yet. If that DOES work, then you know things are publishing correctly and I would look closer at the JS code... though your code looks pretty similar to the core Mercure + Turbo code (it's not exactly the same use-case, but the EventSource stuff is the same - https://github.com/symfony/... )

Sorry I can't be more help!


Roozbeh S. Avatar

Hi Ryan,
on the browser (Mercure Debugging Tools) works perfectly!

Thank you.

Cat in space

"Houston: no signs of life"
Start the conversation!

What PHP libraries does this tutorial use?

// composer.json
    "require": {
        "php": ">=8.1",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "composer/package-versions-deprecated": "", //
        "doctrine/annotations": "^1.0", // 1.13.1
        "doctrine/doctrine-bundle": "^2.2", // 2.3.2
        "doctrine/orm": "^2.8", // 2.9.1
        "phpdocumentor/reflection-docblock": "^5.2", // 5.2.2
        "sensio/framework-extra-bundle": "^6.1", // v6.1.4
        "symfony/asset": "5.3.*", // v5.3.0-RC1
        "symfony/console": "5.3.*", // v5.3.0-RC1
        "symfony/dotenv": "5.3.*", // v5.3.0-RC1
        "symfony/flex": "^1.3.1", // v1.18.5
        "symfony/form": "5.3.*", // v5.3.0-RC1
        "symfony/framework-bundle": "5.3.*", // v5.3.0-RC1
        "symfony/property-access": "5.3.*", // v5.3.0-RC1
        "symfony/property-info": "5.3.*", // v5.3.0-RC1
        "symfony/proxy-manager-bridge": "5.3.*", // v5.3.0-RC1
        "symfony/runtime": "5.3.*", // v5.3.0-RC1
        "symfony/security-bundle": "5.3.*", // v5.3.0-RC1
        "symfony/serializer": "5.3.*", // v5.3.0-RC1
        "symfony/twig-bundle": "5.3.*", // v5.3.0-RC1
        "symfony/ux-chartjs": "^1.1", // v1.3.0
        "symfony/ux-turbo": "^1.3", // v1.3.0
        "symfony/ux-turbo-mercure": "^1.3", // v1.3.0
        "symfony/validator": "5.3.*", // v5.3.0-RC1
        "symfony/webpack-encore-bundle": "^1.9", // v1.11.2
        "symfony/yaml": "5.3.*", // v5.3.0-RC1
        "twig/extra-bundle": "^2.12|^3.0", // v3.3.1
        "twig/intl-extra": "^3.2", // v3.3.0
        "twig/string-extra": "^3.3", // v3.3.1
        "twig/twig": "^2.12|^3.0" // v3.3.2
    "require-dev": {
        "doctrine/doctrine-fixtures-bundle": "^3.4", // 3.4.0
        "symfony/debug-bundle": "^5.2", // v5.3.0-RC1
        "symfony/maker-bundle": "^1.27", // v1.31.1
        "symfony/monolog-bundle": "^3.0", // v3.7.0
        "symfony/stopwatch": "^5.2", // v5.3.0-RC1
        "symfony/var-dumper": "^5.2", // v5.3.0-RC1
        "symfony/web-profiler-bundle": "^5.2", // v5.3.0-RC1
        "zenstruck/foundry": "^1.10" // v1.10.0

What JavaScript libraries does this tutorial use?

// package.json
    "devDependencies": {
        "@babel/preset-react": "^7.0.0", // 7.13.13
        "@fortawesome/fontawesome-free": "^5.15.3", // 5.15.3
        "@hotwired/turbo": "^7.0.0-beta.5", // 1.2.6
        "@popperjs/core": "^2.9.1", // 2.9.2
        "@symfony/stimulus-bridge": "^2.0.0", // 2.1.0
        "@symfony/ux-chartjs": "file:vendor/symfony/ux-chartjs/Resources/assets", // 1.1.0
        "@symfony/ux-turbo": "file:vendor/symfony/ux-turbo/Resources/assets", // 0.1.0
        "@symfony/ux-turbo-mercure": "file:vendor/symfony/ux-turbo-mercure/Resources/assets", // 0.1.0
        "@symfony/webpack-encore": "^1.0.0", // 1.3.0
        "bootstrap": "^5.0.0-beta2", // 5.0.1
        "chart.js": "^2.9.4",
        "core-js": "^3.0.0", // 3.13.0
        "jquery": "^3.6.0", // 3.6.0
        "react": "^17.0.1", // 17.0.2
        "react-dom": "^17.0.1", // 17.0.2
        "regenerator-runtime": "^0.13.2", // 0.13.7
        "stimulus": "^2.0.0", // 2.0.0
        "stimulus-autocomplete": "https://github.com/weaverryan/stimulus-autocomplete#toggle-event-always-dist", // 2.0.0
        "stimulus-use": "^0.24.0-1", // 0.24.0-2
        "sweetalert2": "^11.0.8", // 11.0.12
        "webpack-bundle-analyzer": "^4.4.0", // 4.4.2
        "webpack-notifier": "^1.6.0" // 1.13.0