feat: hot reloading #2031

dunglas · 2025-11-24T23:18:00Z

This patch brings hot reloading capabilities to PHP apps: in development, the browser will automatically refresh the page when any source file changes!
It's similar to HMR in JavaScript.

It is built on top of the watcher mechanism and of the Mercure integration.

Each time a watched file is modified, a Mercure update is sent, giving the ability to the client to reload the page, or part of the page (assets, images...).

Here is an example implementation:

root ./public


mercure {
      subscriber_jwt {env.MERCURE_SUBSCRIBER_JWT_KEY}
      anonymous
}

php_server {
      hot_reload
}

<?php
header('Content-Type: text/html');
?>
<!DOCTYPE html>
<html lang="en">
<head>
<title>Test</title>
<script>
    const es = new EventSource('<?=$_SERVER['FRANKENPHP_HOT_RELOAD']?>');
    es.onmessage = () => location.reload();
</script>
</head>
<body>
Hello

I plan to create a helper JS library to handle more advanced cases (reloading CSS, JS, etc), similar to HotWire Spark. Be sure to attend my SymfonyCon to learn more!

There is still room for improvement:

Provide an option to only trigger the update without reloading the worker for some files (ex, images, JS, CSS...)
Support classic mode (currently, only the worker mode is supported)
Don't reload all workers when only the files used by one change

However, this PR is working as-is and can be merged as a first step.

This patch heavily refactors the watcher module. Maybe it will be possible to extract it as a standalone library at some point (would be useful to add a similar feature but not tight to PHP as a Caddy module).

Copilot

Pull request overview

This PR introduces hot reloading capabilities for PHP applications in FrankenPHP, enabling automatic browser refresh when source files change during development. The implementation is built on top of the existing watcher mechanism and Mercure integration, sending Mercure updates when watched files are modified so clients can reload the page or specific assets.

Key changes include:

Refactored watcher module to support per-pattern callbacks and event metadata
Added Mercure integration to publish file change events as hot reloading updates
Introduced new Event type system with structured event types (EffectType, PathType) and JSON marshaling

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
worker.go	Integrates watcher patterns with worker-specific hot reloading callbacks and configures Mercure hub
state.go	Code formatting improvements and initialization cleanup
options.go	Adds mercureContext field to workerOpt struct
mercure.go	Implements hot reloading update publishing via Mercure hub and environment variable configuration
mercure-skip.go	Provides stub implementations for nomercure build tag
internal/watcher/watcher.h	Updates C function signatures with renamed parameters
internal/watcher/watcher.go	Major refactor: introduces PatternGroup concept, per-pattern callbacks, and event-driven architecture
internal/watcher/watcher.c	Updates C event handler to pass full event struct
internal/watcher/watcher-skip.go	Provides stub implementation for nowatcher build tag
internal/watcher/watch_pattern_test.go	Updates tests to use new Event-based API
internal/watcher/watch_pattern.go	Refactors pattern matching to work with Event objects and adds CGO integration for watcher events
internal/watcher/types.go	Defines Event type system with EffectType and PathType enums and JSON marshaling
caddy/workerconfig.go	Adds mercureContext field to workerConfig
caddy/module.go	Updates to use new assignMercureHub method name
caddy/mercure.go	Implements Mercure hub assignment for workers and adds appendMercureHubOption helper
caddy/mercure-skip.go	Provides stub implementations for nomercure build tag with corrected function name
caddy/app.go	Simplifies worker options initialization using appendMercureHubOption

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

internal/watcher/watcher-skip.go

mercure.go

internal/watcher/watch_pattern.go

caddy/mercure-skip.go

internal/watcher/watch_pattern_test.go

internal/watcher/watcher.go

internal/watcher/watch_pattern.go

henderkes · 2025-11-25T13:09:17Z

I'll add a review later, but very cool! I currently have this running through PhpStorm (forces a F5), but we could even go further with mercure + turbo and send a morph update (configurable by users, of course).

Copilot

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 9 comments.

Comments suppressed due to low confidence (1)

internal/watcher/watcher.go:77

If activeWatcher.startWatching() returns an error (line 73), the function returns immediately without cleaning up. The watcherIsActive atomic bool is set to true (line 60), but it's not reset to false on error. This could prevent subsequent attempts to initialize the watcher. Consider adding cleanup logic:

if err := activeWatcher.startWatching(); err != nil {
	watcherIsActive.Store(false)
	activeWatcher = nil
	return err
}

	if err := activeWatcher.startWatching(); err != nil {
		return err
	}

	return nil

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

internal/watcher/pattern.go

internal/watcher/types.go

internal/watcher/pattern.go

internal/watcher/watcher.go

workerextension_test.go

mercure.go

internal/watcher/types.go

Copilot

Pull request overview

Copilot reviewed 25 out of 25 changed files in this pull request and generated 8 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

internal/watcher/pattern.go

worker.go

mercure.go

internal/watcher/watcher.go

internal/watcher/watcher.h

internal/watcher/watcher.go

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

AlliBalliBaba · 2025-12-04T19:27:19Z

internal/watcher/watcher.go

+	for i, w := range g.watchers {
+		w.events = g.events
+		if err := w.startSession(); err != nil {
+			for j := 0; j < i; j++ {
+				g.watchers[j].stop()
+			}


Would the mercure events start a separate instance of the watcher here?

Hmm I think all this would be much easier if we just stick to 1 callback, something like this:

func(events) { if watchingWorkers { RestartWorkers() } if watchingWithMercure{ broadcastHotReloadEvents(events) } }()

Or if the callback of the pattern group already contains both worker restarting and hot reload broadcasting

I'm not sure if it is worth it, because patterns can be different for hot reloading and for Mercure.
For instance, you don't want to restart the workers when a JS file changes, but you want to notify through Mercure.

AlliBalliBaba · 2025-12-06T13:26:11Z

Just tested this branch and it's actually a pretty cool feature 👍 .

Some more things I noticed:

the server will hang forever on shutdown if someone is still listening on the mercure endpoint, I think ideally everyone should just be disconnected.
on file change, if both watching and hot-reloading are active, every event will be logged twice:

log and message can pretty much grow limitlessly if lots of file changes are done in quick succession. There probably should be some kind of cap on the amount of file events that can be forwarded at once.

dunglas · 2025-12-06T13:38:58Z

The "eternal grace" issue is something that I should fix Mercure-side and is unrelated to this specific feature.
A workaround is to configure an explicit grace period in the Caddyfile.

withinboredom

This is actually really cool. I'm pretty excited to use it on my hugo generator. Developing with it is a pita because its mostly generated html (other than the API + interactive blog posts), and this would work perfectly for that.

internal/watcher/watcher.go

caddy/mercure-skip.go

internal/watcher/pattern.go

caddy/module.go

Fixes #2114 This early [Shutdown](https://github.com/php/frankenphp/blob/11160fb7b31171d706cf9933abb9102dbb1cdb3c/frankenphp.go#L281) introduced in #2031 segfaults instead of returning an error since threads have not started yet.

dunglas requested review from AlliBalliBaba and Copilot November 24, 2025 23:18

Copilot started reviewing on behalf of dunglas November 24, 2025 23:24 View session

Copilot finished reviewing on behalf of dunglas November 24, 2025 23:28

Copilot AI reviewed Nov 24, 2025

View reviewed changes

dunglas force-pushed the feat/hot-reloading branch from a46e160 to d840b63 Compare November 25, 2025 11:05

dunglas requested a review from Copilot November 25, 2025 13:55

Copilot started reviewing on behalf of dunglas November 25, 2025 13:59 View session

Copilot finished reviewing on behalf of dunglas November 25, 2025 14:04

Copilot AI reviewed Nov 25, 2025

View reviewed changes

dunglas requested a review from Copilot November 25, 2025 14:54

Copilot started reviewing on behalf of dunglas November 25, 2025 14:55 View session

Copilot finished reviewing on behalf of dunglas November 25, 2025 14:59

Copilot AI reviewed Nov 25, 2025

View reviewed changes

AlliBalliBaba reviewed Nov 25, 2025

View reviewed changes

worker.go Outdated Show resolved Hide resolved

mercure.go Outdated Show resolved Hide resolved

internal/watcher/watcher.go Outdated Show resolved Hide resolved

henderkes reviewed Nov 28, 2025

View reviewed changes

internal/watcher/watcher.h Outdated Show resolved Hide resolved

AlliBalliBaba reviewed Nov 29, 2025

View reviewed changes

internal/watcher/watcher.go Show resolved Hide resolved

dunglas and others added 12 commits December 1, 2025 16:56

feat: hot reloading

c62bd99

various fixes

ed37d2d

fix

f6083ad

fix nomercure and nowatcher tags

6074d60

tidy

585f9d4

fix tests when workers are disabled

6a080d5

fix race condition

c94dba9

fixes

ae50db0

Update internal/watcher/pattern.go

6d0ad18

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update internal/watcher/pattern.go

43afabb

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update pattern.go

d533e3d

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update pattern.go

16fb1bb

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

AlliBalliBaba reviewed Dec 4, 2025

View reviewed changes

dunglas added 7 commits December 4, 2025 22:26

simplify restart workers logic

9038cb6

simplify

2402892

fix AssociatedPathName

417a3ab

simplify

7062abb

fix tests

ac67a68

simplify

a233e30

fix tests

77da2a1

dunglas mentioned this pull request Dec 5, 2025

feat: Go module e-dant/watcher#96

Merged

dunglas added 2 commits December 5, 2025 16:35

cleanup

b8257ee

fix tests

80bc973

withinboredom reviewed Dec 7, 2025

View reviewed changes

internal/watcher/watcher.go Show resolved Hide resolved

caddy/mercure-skip.go Show resolved Hide resolved

internal/watcher/pattern.go Show resolved Hide resolved

internal/watcher/pattern.go Show resolved Hide resolved

AlliBalliBaba reviewed Dec 7, 2025

View reviewed changes

caddy/module.go Outdated Show resolved Hide resolved

dunglas mentioned this pull request Dec 9, 2025

fix(caddy): prevent Caddy to never stop because of the eternal grace period dunglas/mercure#1138

Merged

dunglas added 4 commits December 9, 2025 16:17

Merge branch 'main' into feat/hot-reloading

3e3683f

use watcher-go

2f1897f

fix tests

cadeb42

remove remaining debug log

14ebc1d

dunglas force-pushed the feat/hot-reloading branch from 933ada1 to 14ebc1d Compare December 11, 2025 10:10

dunglas added 2 commits December 11, 2025 13:21

new config

25885da

fix tests

cabb101

dunglas force-pushed the feat/hot-reloading branch from 6a14220 to cabb101 Compare December 11, 2025 12:26

dunglas added 2 commits December 11, 2025 14:39

fix tests

51a6283

fix tests provided by @withinboredom

73f5a69

dunglas merged commit 225ca40 into main Dec 12, 2025
71 of 88 checks passed

dunglas deleted the feat/hot-reloading branch December 12, 2025 13:29

AlliBalliBaba mentioned this pull request Jan 10, 2026

fix: prevents segfault on early shutdown. #2120

Merged

feat: hot reloading #2031

feat: hot reloading #2031

Uh oh!

Conversation

dunglas commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

henderkes commented Nov 25, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AlliBalliBaba Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

AlliBalliBaba Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dunglas Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

AlliBalliBaba commented Dec 6, 2025

Uh oh!

dunglas commented Dec 6, 2025

Uh oh!

withinboredom left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

dunglas commented Nov 24, 2025 •

edited

Loading

AlliBalliBaba Dec 4, 2025 •

edited

Loading