This guide outlines Mercure Hub setup, and installation and configuration of the Mercure service and channel.

Installation

Composer dependencies

From a project with a pre-installed version of Notifier and Notifier Chat Channel, bring in the Mercure notifier and Mercure Drupal project dependencies:

composer require drupal/mercure symfony/mercure-notifier
drush module:enable mercure

Mercure Hub

Set up Mercure Hub by following the guide at https://mercure.rocks/docs/hub/install. It's likely you'll have radically different setups for local vs production. The following describes a Docker Compose setup which contains both Drupal and web server, alongside Mercure Hub.

The template here is very similar to the template provided in Mercure documentation, based on the Symfony template with minor deviations:

services:
  mercure:
    image: dunglas/mercure
    restart: unless-stopped
    ports:
      - "8099:80"
    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 Drupal project (without trailing slash!) as value of the cors_origins directive
      MERCURE_EXTRA_DIRECTIVES: |
        cors_origins http://localhost:8080
    # 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

  volumes:
    mercure_data:
    mercure_config:

Replace port 8080 with the port you access Drupal/HTTP server from.

Configuration

In the site directory, usually sites/default/, create a services.yml file.

Add to settings.php:

$settings['container_yamls'][] = __DIR__ . '/services.yml';

Add to services.yml:

parameters:
  chatter.transports:
    my_mercure_transport: 'mercure://HUB_ID?topic=TOPIC'

  mercure:
    hubs:
      default:
        url: 'http://mercure/.well-known/mercure'
        public_url: 'https://localhost:8099/.well-known/mercure'
        jwt:
          secret: '!ChangeThisMercureHubJWTSecretKey!'
          publish: '*'

Chatter transports

Modify the DSN by replacing the HUB_ID and TOPIC parts.

HUB_ID is the Mercure hub ID as configured in the Mercure module. If Mercure has not been customized heavily, this ID is likely default. TOPIC is the default topic, and may be overridden on the Notification level by passing a MercureOptions option object with topics. The default TOPIC also accepts multiple topics using square-bracket ([]) notation.

Mercure

Replace port 8099 with the port you can access the Mercure Hub from a host machine.

Replace mercure in url with the hostname your Drupal install can directly access the Mercure Hub in Docker networking.

WARNING

The provided configuration is for local testing only. Secrets must be updated appropriately when publicly accessible. See Mercure documentation.

---

Then clear Drupal caches:

drush cr

Sending

To send a message to a Mercure Hub, create a notification then send to the notifier service.

Pass the name of the Mercure transport as configured in chatter.transports to the Notification::channels() method, prefixed with chat/.

Message body

Chat notifications use subject() for message contents, not contents().

src/MyService.php

namespace Drupal\my_module;

final class MyService {
  public function __construct(
    private readonly \Symfony\Component\Notifier\NotifierInterface $notifier,
  ) {}
  public function myMethod(){
    $notification = (new \Symfony\Component\Notifier\Notification\Notification())
      ->subject('Foo bar!')
      # Specify the name of the Mercure transport as configured in `chatter.transports`.
      ->channels(['chat/my_mercure_transport']),
    $this->notifier->send($notification);
  }
}

mymodule.services.yml

services:
  _defaults:
    autowire: true
    
  my_service:
    class: Drupal\my_module\MyService

The above message dispatches this object to a browser listening for events:

{ 
   "@context": "https://www.w3.org/ns/activitystreams", 
   "type": "Announce", 
   "summary": "Foo bar!"
}

INFO

As of writing the Mercure integration is only capable of sending ActivityStream Announce activities, not arbitrary payloads. To send any payload, either customize MercureTransport, create a fully custom Mercure transport, or send data directly to Mercure Hub services.

Listening

To listen to events from a Mercure Hub, create HTML and Javascript including the minimum code:

<html>
<body>
<script>
const eventSource = new EventSource('http://localhost:8099/.well-known/mercure?topic=TOPIC');
eventSource.onmessage = event => {
  console.log(JSON.parse(event.data));
}
window.addEventListener('beforeunload', function () {
  eventSource.close();
})
</script>
</body>
</html>

No external libraries are necessary. EventSource is supported by all major web browsers.

Replace port 8099 with the port you can access the Mercure Hub from a host machine.

Replace TOPIC with the topic the notification was dispatched to, or the default TOPIC in the mercure DSN.

Debug UI

Mercure Hub provides an interface to test and debug messages at http://localhost:8099/.well-known/mercure/ui/.

Replace port 8099 with the port you can access the Mercure Hub from a host machine.

Resources

For more information about the Mercure integration, go to Mercure transport in the Symfony monorepo.

---

This documentation is not provided or endorsed by the maintainers of Mercure.