Installation et configuration
Installer le bundle Symfony Mercure et configurer le Hub pour le projet SymfoLivraison
Avant de commencer, assurez-vous de disposer d'un projet Symfony avec la webapp. Si ce n'est pas le cas, créez-en un :
symfony new symfolivraison --webapp
Notions théoriques
Le bundle Mercure pour Symfony
Symfony propose un bundle officiel (symfony/mercure-bundle) qui intègre le protocole Mercure dans l'injection de dépendances. Une fois installé, il fournit :
- L'interface
HubInterfacepour publier des mises à jour depuis un contrôleur ou un service - La classe
Updatequi représente une mise à jour à envoyer au Hub - La fonction Twig
mercure()pour générer l'URL de souscription côté JavaScript
Le Hub Mercure
Le Hub Mercure est un serveur indépendant (écrit en Go) qui maintient les connexions SSE ouvertes et redistribue les mises à jour aux subscribers. Il tourne en parallèle de l'application Symfony.
Le Symfony CLI intègre automatiquement un Hub Mercure local lorsque vous démarrez le serveur avec symfony serve. C'est la façon la plus rapide de travailler avec Mercure en développement — aucune configuration Docker requise.
Variables d'environnement Mercure
Mercure utilise trois variables d'environnement dans le fichier .env :
| Variable | Rôle |
|---|---|
MERCURE_URL | URL du Hub utilisée par Symfony pour publier (côté serveur) |
MERCURE_PUBLIC_URL | URL du Hub utilisée par le navigateur pour s'abonner (côté client) |
MERCURE_JWT_SECRET | Clé secrète partagée entre Symfony et le Hub pour signer les tokens JWT |
Ne committez jamais MERCURE_JWT_SECRET avec une valeur réelle dans un dépôt public. En production, injectez cette variable via les variables d'environnement système ou un gestionnaire de secrets.
Le token JWT
Mercure utilise des JSON Web Tokens (JWT) pour authentifier les publishers. Le bundle génère automatiquement ce token à partir de MERCURE_JWT_SECRET. Le Hub vérifie ce token avant d'accepter une mise à jour publiée.
Exemple de mise en application
1. Installer le bundle
composer require mercure
La recette Flex configure automatiquement les fichiers nécessaires et ajoute les variables d'environnement dans .env.
2. Vérifier le fichier .env
Après l'installation, vérifiez que les variables Mercure sont présentes dans .env :
MERCURE_URL=https://localhost/.well-known/mercure
MERCURE_PUBLIC_URL=https://localhost/.well-known/mercure
MERCURE_JWT_SECRET="!ChangeThisMercureHubJWTSecretKey!"
3. Démarrer le serveur avec Mercure intégré
symfony serve
Le Symfony CLI démarre automatiquement le Hub Mercure en arrière-plan. Vous devriez voir dans la console :
[OK] Web server listening on https://127.0.0.1:8000
4. Vérifier que le Hub répond
Ouvrez dans votre navigateur :
https://localhost/.well-known/mercure
Le Hub répond avec Missing "topic" parameter. — c'est le comportement attendu. Cela confirme que le Hub fonctionne et attend des abonnés.
Test de mémorisation/compréhension
TP pour réfléchir et résoudre des problèmes
Étape 1 — Créer le projet Symfony
Dans votre répertoire de travail, créez le projet symfolivraison, entrez dans ce répertoire puis démarrez le serveur de développement.
Étape 2 — Installer le bundle Mercure
Après composer require mercure, ouvrez le fichier .env et vérifiez que les trois variables Mercure ont bien été ajoutées automatiquement par la recette Flex. Si votre projet n'utilise pas Flex, ajoutez-les manuellement.
Étape 3 — Configurer le fichier .env
Vérifiez que les variables Mercure sont correctement définies :
En développement, la valeur par défaut !ChangeThisMercureHubJWTSecretKey! est acceptable. En production, remplacez-la par une chaîne aléatoire d'au moins 32 caractères et injectez-la via les variables d'environnement du serveur. Ajoutez .env.local à votre .gitignore pour éviter tout commit accidentel de valeurs sensibles.
Étape 4 — Vérifier que le Hub fonctionne
Démarrez le serveur avec symfony serve et accédez à https://localhost/.well-known/mercure dans votre navigateur.