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"

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.

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!

5
Login or Register to join the conversation
Fabrice Avatar

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!

Cheers!

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

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="">
https://bestofreactjs.com/r...

my mercure hub url: <http: localhost:3000="" .well-known="" mercure="">
my mercure publish url <https: myip:3000="" notifications="">
here is my react native code


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

const es = new EventSource(url);

const listener: EventSourceListener = event => {
console.log("test");
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);
console.log(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 (
<view>
<text>Streaming!</text>
</view>
);
}
}
Reply

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!

Cheers!

Reply
Roozbeh S. Avatar

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

Thank you.

Reply
Cat in space

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

What PHP libraries does this tutorial use?

// composer.json
{
    "require": {
        "php": ">=7.4.0",
        "ext-ctype": "*",
        "ext-iconv": "*",
        "composer/package-versions-deprecated": "1.11.99.1", // 1.11.99.1
        "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
    }
}