Release v1.6.2: demo FRANKENPHP_MODE classic/worker switch.

Add Compose-driven FrankenPHP mode via entrypoint (worker default, classic for Caddyfile.dev) and align DEMO docs; no consumer API changes.

Author: HecFranco

README.md

@@ -118,7 +118,7 @@ Generate keys in Beacon project settings, or run `make seed` in the `symfony-bea
 
 ## FrankenPHP worker
 
-The bundled demo uses FrankenPHP. Its production-style Caddyfile enables worker mode, while local dev defaults to `Caddyfile.dev` without workers so code changes show up immediately. See [Demo/FrankenPHP](docs/DEMO-FRANKENPHP.md).
+The bundled demo uses FrankenPHP. Default **`FRANKENPHP_MODE=worker`**; set `classic` for `Caddyfile.dev` (hot-reload friendly). See [Demo/FrankenPHP](docs/DEMO-FRANKENPHP.md).
 
 ## Documentation
 

composer.json

@@ -80,7 +80,7 @@
     },
     "config": {
         "sort-packages": true,
-        "root-version": "1.6.1-dev",
+        "root-version": "1.6.2-dev",
         "allow-plugins": {
             "phpstan/extension-installer": true
         },

demo/README.md

@@ -17,7 +17,7 @@ make up-symfony8
 
 The demo includes:
 
-- FrankenPHP with Caddy (HTTP on `:80` inside container). Default **`APP_ENV=dev`** uses **Caddyfile.dev** (no PHP worker); see [docs/DEMO-FRANKENPHP.md](../docs/DEMO-FRANKENPHP.md) for production (worker) vs development.
+- FrankenPHP with Caddy (HTTP on `:80` inside container). Default **`FRANKENPHP_MODE=worker`**; set `classic` in `.env` for `Caddyfile.dev` (no PHP worker). See [docs/DEMO-FRANKENPHP.md](../docs/DEMO-FRANKENPHP.md).
 - Web Profiler enabled in `dev`
 - Nowo Twig Inspector enabled in `dev`
 - `symfony/messenger` + console boom command

demo/symfony8/.env.example

@@ -4,6 +4,10 @@ APP_ENV=dev
 # APP_DEBUG: Enable/disable detailed debug output (usually `1` in dev).
 APP_DEBUG=1
 
+# FRANKENPHP_MODE: FrankenPHP runtime mode — `classic` (one process per request) or `worker` (long-lived workers).
+# Default: worker. Set classic for per-request PHP / easier hot-reload. Recreate with `docker compose up -d` after change.
+FRANKENPHP_MODE=worker
+
 # APP_SECRET: Secret used for signing/tokens. Use a local-only value in demos.
 APP_SECRET=CHANGE_ME_LOCAL_SECRET
 

demo/symfony8/Dockerfile

@@ -19,12 +19,7 @@ ENV SERVER_NAME=:80
 COPY docker/frankenphp/Caddyfile /etc/frankenphp/Caddyfile
 COPY docker/frankenphp/Caddyfile.dev /etc/frankenphp/Caddyfile.dev
 
-RUN echo '#!/bin/sh' > /usr/local/bin/docker-entrypoint.sh && \
-    echo 'set -e' >> /usr/local/bin/docker-entrypoint.sh && \
-    echo 'if [ "${APP_ENV:-prod}" = "dev" ]; then cp /etc/frankenphp/Caddyfile.dev /etc/frankenphp/Caddyfile; fi' >> /usr/local/bin/docker-entrypoint.sh && \
-    echo 'mkdir -p /app/var/cache /app/var/log' >> /usr/local/bin/docker-entrypoint.sh && \
-    echo 'chmod -R 777 /app/var' >> /usr/local/bin/docker-entrypoint.sh && \
-    echo 'exec frankenphp run --config /etc/frankenphp/Caddyfile --adapter caddyfile' >> /usr/local/bin/docker-entrypoint.sh && \
-    chmod +x /usr/local/bin/docker-entrypoint.sh
+COPY docker/entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 
 ENTRYPOINT ["docker-entrypoint.sh"]

demo/symfony8/docker-compose.yml

@@ -19,6 +19,7 @@ services:
       - APP_ENV=dev
       - APP_DEBUG=1
       - APP_SECRET=${APP_SECRET:-demo-secret}
+      - FRANKENPHP_MODE=${FRANKENPHP_MODE:-worker}
     # Reach Symfony Beacon published on the host (HTTP :9081 / HTTPS :9444).
     extra_hosts:
       - "host.docker.internal:host-gateway"

demo/symfony8/docker/entrypoint.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+set -e
+
+# FRANKENPHP_MODE: classic | worker (REQ-DEMO-010). Default: worker.
+# Set via .env / Compose only — not baked into the image ENV.
+MODE="${FRANKENPHP_MODE:-worker}"
+case "$MODE" in
+	classic)
+		cp /etc/frankenphp/Caddyfile.dev /etc/frankenphp/Caddyfile
+		;;
+	worker)
+		# Prefer bind-mounted project file so edits apply without rebuild.
+		if [ -f /app/docker/frankenphp/Caddyfile ]; then
+			cp /app/docker/frankenphp/Caddyfile /etc/frankenphp/Caddyfile
+		fi
+		# else keep the image-baked worker Caddyfile
+		;;
+	*)
+		echo "Unknown FRANKENPHP_MODE=$MODE (expected classic|worker)" >&2
+		exit 1
+		;;
+esac
+echo "FrankenPHP mode: $MODE"
+
+mkdir -p /app/var/cache /app/var/log
+chmod -R 777 /app/var
+exec frankenphp run --config /etc/frankenphp/Caddyfile --adapter caddyfile

docs/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.6.2] - 2026-07-22
+
+### Added
+
+- Demo Symfony 8: `FRANKENPHP_MODE` (`worker` default / `classic`) via Compose + `docker/entrypoint.sh` (selects worker Caddyfile vs `Caddyfile.dev` without rebuilding the image)
+
+### Changed
+
+- Docs (`DEMO-FRANKENPHP.md`, demo/README, root README): document classic vs worker switching; recreate containers after changing `.env`
+
 ## [1.6.1] - 2026-07-21
 
 ### Added
@@ -218,7 +228,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Expanded documentation set for installation, configuration, usage, release, security, performance, Engram, and Spec Kit workflows.
 - Demo routes covering message capture, manual exception capture, listener-triggered exceptions, ignored exceptions, fingerprints, and runtime status.
 
-[Unreleased]: https://github.com/nowo-tech/BeaconBundle/compare/v1.6.1...HEAD
+[Unreleased]: https://github.com/nowo-tech/BeaconBundle/compare/v1.6.2...HEAD
+[1.6.2]: https://github.com/nowo-tech/BeaconBundle/compare/v1.6.1...v1.6.2
 [1.6.1]: https://github.com/nowo-tech/BeaconBundle/compare/v1.6.0...v1.6.1
 [1.6.0]: https://github.com/nowo-tech/BeaconBundle/compare/v1.5.1...v1.6.0
 [1.5.1]: https://github.com/nowo-tech/BeaconBundle/compare/v1.5.0...v1.5.1

docs/DEMO-FRANKENPHP.md

@@ -1,6 +1,6 @@
 # Demo / FrankenPHP
 
-BeaconBundle demos use **FrankenPHP + Caddy**. The production Caddyfile enables worker mode, while the default development setup uses `Caddyfile.dev` without workers so file changes are visible on refresh.
+BeaconBundle demos use **FrankenPHP + Caddy**. Runtime mode is selected with **`FRANKENPHP_MODE`** (`worker` by default; set `classic` for hot-reload-friendly `Caddyfile.dev`). See [Switching classic vs worker](#switching-classic-vs-worker-frankenphp_mode).
 
 ## Worker-mode snippet
 
@@ -16,7 +16,7 @@ From `demo/symfony8/docker/frankenphp/Caddyfile`:
 }
 ```
 
-That is the production-style worker setup. In local dev, the demo uses `Caddyfile.dev` instead, which keeps plain `php_server` and disables cache headers.
+That is the default **`worker`** Caddyfile baked into the image. With `FRANKENPHP_MODE=classic`, the entrypoint switches to `Caddyfile.dev` (plain `php_server`, friendlier for file refresh).
 
 ## Running the demo with Symfony Beacon (direct error ingest)
 
@@ -77,3 +77,14 @@ Its default ports are:
 - HTTP ingest (Docker clients / this demo): `http://localhost:9081`
 
 See [`USAGE.md`](USAGE.md) for the end-to-end scenario matrix.
+
+## Switching classic vs worker (`FRANKENPHP_MODE`)
+
+Demos select the FrankenPHP runtime via **`FRANKENPHP_MODE`** in `.env` / `.env.example` (not a Dockerfile `ENV`):
+
+| Value | Behaviour |
+| --- | --- |
+| **`worker`** (default) | Keep the worker Caddyfile (`php_server { worker ... }`) |
+| **`classic`** | Entrypoint copies `Caddyfile.dev` (plain `php_server`, hot-reload friendly) |
+
+Compose passes `FRANKENPHP_MODE=${FRANKENPHP_MODE:-worker}` into the PHP service. After changing `.env`, run `docker compose up -d` (or `make up`) so the container is **recreated** — a plain `restart` does not reload env. No image rebuild is required.

docs/UPGRADING.md

@@ -229,6 +229,13 @@ No consumer API or config changes. Additive only:
 - Optional golden Envelope contract fixtures / `make check-envelope-goldens` for maintainers aligning with Symfony Beacon ingest.
 - PHPUnit discovers `tests/Contract` via a dedicated testsuite.
 
-## Upgrading from 1.6.1 to the next release
+## Upgrading from 1.6.1 to 1.6.2
+
+Demo / docs only. **No consumer API or config changes.**
+
+- FrankenPHP demo: set `FRANKENPHP_MODE=worker` (default) or `classic` in `demo/symfony8/.env`. After changing it, recreate containers (`docker compose up -d` / `make up`), not a plain restart.
+- See [DEMO-FRANKENPHP.md](DEMO-FRANKENPHP.md).
+
+## Upgrading from 1.6.2 to the next release
 
 No further consumer changes documented yet.