From 895f169ec61523b91f6c5815f87289975c75bf57 Mon Sep 17 00:00:00 2001 From: matthieu Date: Mon, 29 Dec 2025 16:16:00 +0100 Subject: [PATCH 1/5] 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 6192436b6e71712f5e5ab4db252484f77f2674cd Mon Sep 17 00:00:00 2001 From: matthieu Date: Wed, 25 Feb 2026 08:53:05 +0100 Subject: [PATCH 2/5] 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 aef80fde475685f589c41cf95a3bf3e3f7980cf8 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/5] 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. From 9be9d58a0e13f07d0b437c1ad7c92c090e88cc2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Mon, 9 Mar 2026 16:37:40 +0100 Subject: [PATCH 4/5] Clarify hot reload functionality and security notes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated text for clarity and improved security warnings regarding hot reload feature. Signed-off-by: Kévin Dunglas --- docs/fr/hot-reload.md | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/docs/fr/hot-reload.md b/docs/fr/hot-reload.md index 320b132121..f704ec0536 100644 --- a/docs/fr/hot-reload.md +++ b/docs/fr/hot-reload.md @@ -2,11 +2,11 @@ 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) +![Hot Reload](../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. +FrankenPHP met à jour le contenu de la page en temps réel. Le Hot Reload fonctionne nativement avec WordPress, Laravel, Symfony et toute autre application ou framework PHP. @@ -23,8 +23,9 @@ Selon votre configuration, le navigateur va soit : 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. +> N'activez pas `hot_reload` en production, car cette fonctionnalité n'est pas sécurisée (expose des détails internes sensibles) et ralentit l'application. ```caddyfile localhost @@ -39,9 +40,9 @@ php_server { } ``` -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}` +Par défaut, FrankenPHP surveillera tous les fichiers du répertoire de travail actuel correspondant au motif glob suivant : `./**/*.{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 le glob pattern : +Il est possible de définir explicitement les fichiers à surveiller en utilisant un motif glob : ```caddyfile localhost @@ -56,7 +57,7 @@ php_server { } ``` -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` : +Utilisez la forme longue de `hot_reload` pour spécifier le *topic* Mercure à utiliser ainsi que les répertoires ou fichiers à surveiller : ```caddyfile localhost @@ -79,11 +80,11 @@ php_server { ## 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. +Le serveur détecte les modifications et publie les modifications automatiquement. 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 : +Pour l'utiliser, ajoutez ce qui suit à votre gabarit (*layout*) principal : ```php @@ -100,12 +101,22 @@ Elle est disponible en tant que package [npm](https://www.npmjs.com/package/fran 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 +### Conserver les nœuds DOM existants + +Dans de rares cas, comme lors de l'utilisation d'outils de développement tels que [la *web debug toolbar* de Symfony](https://github.com/symfony/symfony/pull/62970), +vous pouvez souhaiter conserver des nœuds DOM spécifiques. +Pour ce faire, ajoutez l'attribut `data-frankenphp-hot-reload-preserve` à l'élément HTML concerné : + +```html +
+``` + +## 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. +Cela signifie que les modifications de votre code PHP ne seront pas reflétées immédiatement, même si le navigateur recharge la page. -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). +Pour une meilleure expérience de développement, 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 @@ -127,9 +138,9 @@ php_server { } ``` -### Comment ça fonctionne +## 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). +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é à son 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. From 601d07a4ca6fbf422bc7a137781b1b4cb0057e6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Mon, 9 Mar 2026 16:44:37 +0100 Subject: [PATCH 5/5] Refine language for clarity in hot-reload documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Dunglas --- docs/fr/hot-reload.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/fr/hot-reload.md b/docs/fr/hot-reload.md index f704ec0536..fc26a6541f 100644 --- a/docs/fr/hot-reload.md +++ b/docs/fr/hot-reload.md @@ -83,8 +83,8 @@ php_server { Le serveur détecte les modifications et publie les modifications automatiquement. 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 gabarit (*layout*) principal : +La bibliothèque JavaScript [frankenphp-hot-reload](https://www.npmjs.com/package/frankenphp-hot-reload) gére la logique côté client. +Pour l'utiliser, ajoutez le code suivant à votre gabarit (*layout*) principal : ```php @@ -116,7 +116,7 @@ Pour ce faire, ajoutez l'attribut `data-frankenphp-hot-reload-preserve` à l'él 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 recharge la page. -Pour une meilleure expérience de développement, vous devriez combiner `hot_reload` avec [la sous-directive `watch` dans la directive `worker`](config.md#surveillance-des-modifications-de-fichier). +Pour une meilleure expérience de développement, combinez `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