> JavaScript Frameworks & Tools > Symfony UX: Turbo
Login to bookmark this video
Buy Access to Course
48.

Running the Mercure Service in the symfony Binary

Share this awesome video!

|

Keep on Learning!

Start your All-Access Pass

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

Login Subscribe

Mercure itself is a "service" or "server" - kind of like MySQL or Elasticsearch. The Mercure server is called the "hub"... and there are several good ways to get it running. First, they have a managed version where they handle it all for you. This is great for production: it keeps things simple and you can help support the project.

Or, you can download Mercure and set it up locally. Or you can set up Mercure with Docker - that's totally supported. Or the final or is... if you're using the Symfony binary as your local web server then... well... it's already running!

The Embedded Mercure Hub

Head to your open terminal tab, clear the screen and run:

symfony server:status

As a reminder, way back at the start of this tutorial, we used the Symfony binary to run a local web server for us. Back at the browser, open a new tab and go to https://127.0.0.1:8000 - the URL to our site - then /.well-known/mercure.

Tip

The latest symfony binary no longer embeds Mercure. But it's still easy to set up. First, add a mercure service to your docker-compose.yaml file:

version: '3.7'
services:
# ...
###> symfony/mercure-bundle ###
    mercure:
        image: dunglas/mercure
        restart: unless-stopped
        environment:
            # Uncomment the following line to disable HTTPS,
            SERVER_NAME: ':80'
            MERCURE_PUBLISHER_JWT_KEY: '!ChangeThisMercureHubJWTSecretKey!'
            MERCURE_SUBSCRIBER_JWT_KEY: '!ChangeThisMercureHubJWTSecretKey!'
            # Set the URL of your Symfony project (without trailing slash!) as value of the cors_origins directive
            MERCURE_EXTRA_DIRECTIVES: |
                cors_origins http://127.0.0.1:8000
        # Comment the following line to disable the development mode
        command: /usr/bin/caddy run --config /etc/caddy/dev.Caddyfile
        healthcheck:
            test: ["CMD", "curl", "-f", "https://localhost/healthz"]
            timeout: 5s
            retries: 5
            start_period: 60s
        volumes:
            - mercure_data:/data
            - mercure_config:/config
        ports: ['80']
###< symfony/mercure-bundle ###

volumes:
###> symfony/mercure-bundle ###
    mercure_data:
    mercure_config:
###< symfony/mercure-bundle ###

Also, notice that the config file now is dev.Caddyfile instead of Caddyfile.dev used in the tutorial! And now start the container by running:

docker compose up -d

That's it! But instead of being accessible at the URL you see in the tutorial, the Mercure hub will be exposed on a random port. To find it, run:

symfony var:export --multiline | grep MERCURE

And look for the MERCURE_URL value - it should equal something similar to http://127.0.0.1:64150/.well-known/mercure. Put this into your address bar to see your Mercure Hub (you'll see the same error as in the video).

If everything is working... yes! You should see this error:

Missing "topic" parameter.

This is a Mercure hub. Yup, the Symfony binary comes with Mercure already running at this URL. We get that for free.

The Environment Variables

To communicate with this, head back over to your editor and open the .env file.

39 lines | .env
// ... lines 1 - 29
###> symfony/mercure-bundle ###
# See https://symfony.com/doc/current/mercure.html#configuration
# The URL of the Mercure hub, used by the app to publish updates (can be a local URL)
MERCURE_URL=https://127.0.0.1:8000/.well-known/mercure
# The public URL of the Mercure hub, used by the browser to connect
MERCURE_PUBLIC_URL=https://127.0.0.1:8000/.well-known/mercure
# The secret used to sign the JWTs
MERCURE_JWT_SECRET="!ChangeMe!"
###< symfony/mercure-bundle ###

These three environment variables define values that are used in a new config file: config/packages/mercure.yaml. MERCURE_PUBLIC_URL is the public URL to the Mercure hub that our JavaScript will use to subscribe to messages and MERCURE_URL is the URL that our PHP code will use to publish messages. These are usually the same. MERCURE_SECRET is basically a password that will allow us to publish: more on that later.

9 lines | config/packages/mercure.yaml
mercure:
hubs:
default:
url: '%env(MERCURE_URL)%'
public_url: '%env(MERCURE_PUBLIC_URL)%'
jwt:
secret: '%env(MERCURE_JWT_SECRET)%'
publish: '*'

In our case, both URL variables already, by chance, point to the correct URL! Yay! But actually, if you're using the latest version of the Symfony binary... we don't even need these variables in this file! Why? Well, in addition to setting up Mercure for us, the Symfony binary also sets these environment variables automatically to their correct values.

Check it out. Back over in our editor, open public/index.php. Let me close a few things... then open it. Cool. Right after the runtime load, I'll paste in some code.

14 lines | public/index.php
<?php
use App\Kernel;
require_once dirname(__DIR__).'/vendor/autoload_runtime.php';
dd(array_filter($_SERVER, function($item) {
return str_contains($item, 'MERCURE');
}, ARRAY_FILTER_USE_KEY));
return function (array $context) {
return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
};

This looks fancy, but I'm basically dumping the $_SERVER variable... except only the keys that contain MERCURE. The $_SERVER variable - among other things - will contain all environment variables. I'm filtering for MERCURE basically... because I don't want to accidentally publish any secret keys from my computer to the internet... as much fun as that would be.

Anyways, this will run before the .env file is loaded, so it will only print real environment variables. Back over on our site, refresh!

Tip

If you're using the docker-compose.yaml setup described earlier, you will only see 2 environment variables here... which are the only 2 you need anyways.

Yay! We see 4 environment variables including 2 we need! The first one is just a flag that tells us that the Symfony binary is running Mercure... and that last one is there for legacy reasons: we don't need it.

This means that our app is already configured and ready to talk to our Mercure Hub! In production, you'll need to run a real Mercure Hub and set these environment variables manually, however you do that in your hosting environment.

So... we have a Mercure hub running! What does that... mean? Well, it's a central place where some things can listen for messages and other things can publish messages. Next, let's do both of these things: listen to a Mercure "topic" in JavaScript and publish messages to it, both from the command line - just to see how it works - and from PHP, which is our real goal.