From 588f952465357e0d85bcde94173b407c97d6cf38 Mon Sep 17 00:00:00 2001 From: matthieu Date: Mon, 29 Dec 2025 16:16:00 +0100 Subject: [PATCH 1/3] add fr trad for hot-reload.md --- docs/fr/hot-reload.md | 139 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 docs/fr/hot-reload.md diff --git a/docs/fr/hot-reload.md b/docs/fr/hot-reload.md new file mode 100644 index 0000000000..969303a756 --- /dev/null +++ b/docs/fr/hot-reload.md @@ -0,0 +1,139 @@ +# Hot Reload + +FrankenPHP inclut une fonctionnalité de **hot reload** intégrée, conçue pour améliorer considérablement l'expérience développeur. + +![Mercure](../hot-reload.png) + +Cette fonctionnalité offre un workflow similaire au **Hot Module Replacement (HMR)** présent dans les outils JavaScript modernes (comme Vite ou webpack). +Au lieu de rafraîchir manuellement le navigateur après chaque modification de fichier (code PHP, templates, fichiers JavaScript et CSS...), +FrankenPHP met à jour le contenu en temps réel. + +Le Hot Reload fonctionne nativement avec WordPress, Laravel, Symfony et tout autre application ou framework PHP. + +Lorsqu'il est activé, FrankenPHP surveille votre répertoire de travail actuel pour détecter les modifications du système de fichiers. +Quand un fichier est modifié, il envoie une mise à jour [Mercure](mercure.md) au navigateur. + +Selon votre configuration, le navigateur va soit : + +- **Transformer le DOM** (en préservant la position de défilement et l'état des champs de saisie) si [Idiomorph](https://github.com/bigskysoftware/idiomorph) est chargé. +- **Recharger la page** (rechargement standard) si Idiomorph n'est pas présent. + +## Configuration + +Pour activer le hot reload, activez Mercure, puis ajoutez la sous-directive `hot_reload` à la directive `php_server` dans votre `Caddyfile`. + +> [!WARNING] +> Cette fonctionnalité est destinée **uniquement aux environnements de développement**. +> N'activez pas `hot_reload` en production, car la surveillance du système de fichiers entraîne une surcharge de performance et expose des endpoints internes. + +```caddyfile +localhost + +mercure { + anonymous +} + +root public/ +php_server { + hot_reload +} +``` + +Par défaut, FrankenPHP surveillera tous les fichiers du répertoire de travail actuel correspondant à cette syntaxe globale : `./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}` + +Il est possible de définir explicitement les fichiers à surveiller en utilisant la syntaxe globale : + +```caddyfile +localhost + +mercure { + anonymous +} + +root public/ +php_server { + hot_reload src/**/*{.php,.js} config/**/*.yaml +} +``` + +Utilisez la forme longue pour spécifier le topic Mercure à utiliser ainsi que les répertoires ou fichiers à surveiller en fournissant des chemins à l'option `hot_reload` : + +```caddyfile +localhost + +mercure { + anonymous +} + +root public/ +php_server { + hot_reload { + topic hot-reload-topic + watch src/**/*.php + watch assets/**/*.{ts,json} + watch templates/ + watch public/css/ + } +} +``` + +## Intégration côté client + +Bien que le serveur détecte les modifications, le navigateur doit s'abonner à ces événements pour mettre à jour la page. +FrankenPHP expose l'URL du Hub Mercure à utiliser pour s'abonner aux modifications de fichiers via la variable d'environnement `$_SERVER['FRANKENPHP_HOT_RELOAD']`. + +Une bibliothèque JavaScript pratique, [frankenphp-hot-reload](https://www.npmjs.com/package/frankenphp-hot-reload), est également disponible pour gérer la logique côté client. +Pour l'utiliser, ajoutez ce qui suit à votre layout principal : + +```php + +FrankenPHP Hot Reload + + + + + +``` + +La bibliothèque s'abonnera automatiquement au hub Mercure, récupérera l'URL actuelle en arrière-plan lorsqu'une modification de fichier est détectée et transformera le DOM. +Elle est disponible en tant que package [npm](https://www.npmjs.com/package/frankenphp-hot-reload) et sur [GitHub](https://github.com/dunglas/frankenphp-hot-reload). + +Alternativement, vous pouvez implémenter votre propre logique côté client en vous abonnant directement au hub Mercure en utilisant la classe JavaScript native `EventSource`. + +### Mode Worker + +Si vous exécutez votre application en [mode Worker](worker.md), le script de votre application reste en mémoire. +Cela signifie que les modifications de votre code PHP ne seront pas reflétées immédiatement, même si le navigateur se recharge. + +Pour la meilleure expérience développeur, vous devriez combiner `hot_reload` avec [la sous-directive `watch` dans la directive `worker`](config.md#surveillance-des-modifications-de-fichier). + +- `hot_reload` : rafraîchit le **navigateur** lorsque les fichiers changent +- `worker.watch` : redémarre le worker lorsque les fichiers changent + +```caddy +localhost + +mercure { + anonymous +} + +root public/ +php_server { + hot_reload + worker { + file /path/to/my_worker.php + watch + } +} +``` + +### Comment ça fonctionne + +1. **Surveillance** : FrankenPHP surveille le système de fichiers pour les modifications en utilisant [la bibliothèque `e-dant/watcher`](https://github.com/e-dant/watcher) en interne (nous avons contribué au binding Go). +2. **Redémarrage (mode Worker)** : si `watch` est activé dans la configuration du worker, le worker PHP est redémarré pour charger le nouveau code. +3. **Envoi** : un payload JSON contenant la liste des fichiers modifiés est envoyé au [hub Mercure](https://mercure.rocks) intégré. +4. **Réception** : le navigateur, à l'écoute via la bibliothèque JavaScript, reçoit l'événement Mercure. +5. **Mise à jour** : + +- Si **Idiomorph** est détecté, il récupère le contenu mis à jour et transforme le HTML actuel pour correspondre au nouvel état, appliquant les modifications instantanément sans perdre l'état. +- Sinon, `window.location.reload()` est appelé pour rafraîchir la page. From 75bac57e96004156dc4352f5f25ae44dfac5a75f Mon Sep 17 00:00:00 2001 From: matthieu Date: Wed, 25 Feb 2026 08:53:05 +0100 Subject: [PATCH 2/3] update "syntaxe globale" to keep english "glob pattern" --- docs/fr/hot-reload.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fr/hot-reload.md b/docs/fr/hot-reload.md index 969303a756..76d0456834 100644 --- a/docs/fr/hot-reload.md +++ b/docs/fr/hot-reload.md @@ -39,9 +39,9 @@ php_server { } ``` -Par défaut, FrankenPHP surveillera tous les fichiers du répertoire de travail actuel correspondant à cette syntaxe globale : `./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}` +Par défaut, FrankenPHP surveillera tous les fichiers du répertoire de travail actuel correspondant au glob pattern : `./**/*.{css,env,gif,htm,html,jpg,jpeg,js,mjs,php,png,svg,twig,webp,xml,yaml,yml}` -Il est possible de définir explicitement les fichiers à surveiller en utilisant la syntaxe globale : +Il est possible de définir explicitement les fichiers à surveiller en utilisant le glob pattern : ```caddyfile localhost From 617b02c8e90d8de062e51611f6550efa446c7c44 Mon Sep 17 00:00:00 2001 From: Alexandre Daubois <2144837+alexandre-daubois@users.noreply.github.com> Date: Wed, 25 Feb 2026 09:44:51 +0100 Subject: [PATCH 3/3] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Alexandre Daubois <2144837+alexandre-daubois@users.noreply.github.com> --- docs/fr/hot-reload.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fr/hot-reload.md b/docs/fr/hot-reload.md index 76d0456834..320b132121 100644 --- a/docs/fr/hot-reload.md +++ b/docs/fr/hot-reload.md @@ -8,7 +8,7 @@ Cette fonctionnalité offre un workflow similaire au **Hot Module Replacement (H Au lieu de rafraîchir manuellement le navigateur après chaque modification de fichier (code PHP, templates, fichiers JavaScript et CSS...), FrankenPHP met à jour le contenu en temps réel. -Le Hot Reload fonctionne nativement avec WordPress, Laravel, Symfony et tout autre application ou framework PHP. +Le Hot Reload fonctionne nativement avec WordPress, Laravel, Symfony et toute autre application ou framework PHP. Lorsqu'il est activé, FrankenPHP surveille votre répertoire de travail actuel pour détecter les modifications du système de fichiers. Quand un fichier est modifié, il envoie une mise à jour [Mercure](mercure.md) au navigateur.