Install¶

The first step to be able to "push" with Symfony is to install the official Symfony Flex recipe for the Mercure integration:

1

$ composer require mercure

To manage persistent connections, Mercure relies on a Hub: a dedicated server that handles persistent SSE connections with the clients. The Symfony app publishes the updates to the hub, that will broadcast them to clients.

An official and open source (AGPL) implementation of a Hub can be downloaded as a static binary from Mercure.rocks.

Run the following command to start it:

1

$ JWT_KEY='aVerySecretKey' ADDR='localhost:3000' ALLOW_ANONYMOUS=1 ./mercure

Now, set the URL of your hub as the value of the MERCURE_PUBLISH_URL env var. The .env file of your project has been updated by the Flex recipe to provide example values. Set it to the URL of the Mercure Hub (https://localhost:3000/hub by default).

In addition, the Symfony application must bear a JSON Web Token (JWT) to the Mercure Hub to be authorized to publish updates. This JWT should be stored in the MERCURE_JWT_SECRET environment variable.

The JWT must be signed with the same secret key than the one used by the Hub to verify the JWT (aVerySecretKey in our example). Its payload must contain at least the following structure to be allowed to publish:

1
2
3
4
5

{
    "mercure": {
        "publish": []
    }
}

Because the array is empty, the Symfony app will only be authorized to publish public updates.

Publishing¶

The Mercure Component provides an Update value object representing the update to publish. It also provides a Publisher service to dispatch updates to the Hub.

The Publisher service can be injected in any other services, including controllers, using the service autowiring feature:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// src/Controller/PublishController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Mercure\Publisher;
use Symfony\Component\Mercure\Update;

class PublishController
{
    public function __invoke(Publisher $publisher): Response
    {
        $update = new Update(
            'https://example.com/books/1',
            json_encode(['status' => 'OutOfStock'])
        );

        // The Publisher service is an invokable object
        $publisher($update);

        return new Response('published!');
    }
}

The first parameter to pass to the Update constructor is the topic being updated. This topic should be an IRI (Internationalized Resource Identifier, RFC 3987): a unique identifier of the resource being dispatched.

Usually, this parameter contains the original URL of the resource transmitted to the client, but it can be any valid IRI, it doesn't have to be an URL that exists (similarly to XML namespaces).

The second parameter of the constructor is the content of the update. It can be anything, stored in any format. However, serializing the resource in a hypermedia format such as JSON-LD, Atom, HTML or XML is recommended.

Subscribing¶

Subscribing to updates in JavaScript is straightforward:

1
2
3
4
5

const es = new EventSource('https://localhost:3000/hub?topic=' + encodeURIComponent('https://example.com/books/1'));
es.onmessage = e => {
    // Will be called every time an update is published by the server
    console.log(JSON.parse(e.data));
}

As you can see, you don't need any JS library or SDK. It just works!

Mercure also allows to subscribe to several topics, and to use URI Templates as patterns:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// URL is a built-in JavaScript class to manipulate URLs
const u = new URL('https://localhost:3000/hub');
u.searchParams.append('topic', 'https://example.com/books/1');
// Subscribe to updates of several Book resources
u.searchParams.append('topic', 'https://example.com/books/2');
// All Review resources will match this pattern
u.searchParams.append('topic', 'https://example.com/reviews/{id}');

const es = new EventSource(u);
es.onmessage = e => {
    console.log(JSON.parse(e.data));
}

Tip

Google Chrome DevTools natively integrate a practical UI displaying in live the received events.

To use it:

• open the DevTools
• select the "Network" tab
• click on the request to the Mercure hub
• click on the "EventStream" sub-tab.

Async dispatching¶

Instead of calling the Publisher service directly, you can also let Symfony dispatching the updates asynchronously thanks to the provided integration with the Messenger component.

First, install the Messenger component:

1

$ composer require messenger

You should also configure a transport (if you don't, the handler will be called synchronously).

Now, you can just dispatch the Mercure Update to the Messenger's Message Bus, it will be handled automatically:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// src/Controller/PublishController.php
namespace App\Controller;

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Mercure\Update;

class PublishController
{
    public function __invoke(MessageBusInterface $bus): Response
    {
        $update = new Update(
            'https://example.com/books/1',
            json_encode(['status' => 'OutOfStock'])
        );

        // Sync, or async (RabbitMQ, Kafka...)
        $bus->dispatch($update);

        return new Response('published!');
    }
}

Web APIs¶

When creating a web API, it's convenient to be able to instantly push new versions of the resources to all connected devices, and to update their views.

API Platform can use the Mercure Component to dispatch updates automatically, every time an API resource is created, modified or deleted.

Start by installing the library using its official recipe:

1

$ composer require api

Then, creating the following entity is enough to get a fully-featured hypermedia API, and automatic update broadcasting through the Mercure hub:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// src/Entity/Book.php
namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;

/**
* @ApiResource(mercure=true)
* @ORM\Entity
*/
class Book
{
    /**
     * @ORM\Id
     * @ORM\Column
     */
    public $name;

    /**
     * @ORM\Column
     */
    public $status;
}

As showcased in the previous recording, the API Platform Client Generator also allows to scaffold complete React and React Native apps from this API. These apps will automatically render the content of Mercure updates in real-time.

Checkout the dedicated API Platform documentation to learn more about its Mercure support.

Going Further¶

There is more! Symfony leverages all the features of the Mercure protocol, including authorization, discoverability through Web Linking and advanced SSE configuration. Checkout the brand new Symfony Docs articles about Mercure to learn all the details!