docs: prepare release 1.2.1

Demo FrankenPHP mode via FRANKENPHP_MODE; align changelog and upgrading notes.

Author: HecFranco

README.md

@@ -6,7 +6,7 @@
 
 Symfony bundle: **`Ckeditor5EditorType`** stores HTML in a textarea while **CKEditor 5 classic** (GPL open-source plugins only) runs in the browser. YAML profiles (FOS-style), **Vite** IIFE build (`ckeditor5-editor.js`) under `src/Resources/public/`.
 
-**FrankenPHP worker mode:** Supported for production-style demo runs (worker-enabled `Caddyfile`). Development demos use classic `php_server` without `worker` so PHP/Twig changes apply on refresh — see [docs/DEMO-FRANKENPHP.md](docs/DEMO-FRANKENPHP.md).
+**FrankenPHP:** Demo runtime is selected with **`FRANKENPHP_MODE`** (`worker` default, or `classic` for per-request PHP / hot-reload). See [docs/DEMO-FRANKENPHP.md](docs/DEMO-FRANKENPHP.md).
 
 ## Features
 

demo/symfony8/.env.example

@@ -4,6 +4,10 @@ PORT=8021
 ###> symfony/framework-bundle ###
 APP_ENV=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=change_this_secret_key_to_a_random_value
 ###< symfony/framework-bundle ###
 

demo/symfony8/Dockerfile

@@ -17,16 +17,10 @@ ENV PATH="/app/vendor/bin:${PATH}"
 ENV SERVER_NAME=:80
 
 COPY docker/frankenphp/Caddyfile /etc/frankenphp/Caddyfile
+COPY docker/frankenphp/Caddyfile /etc/frankenphp/Caddyfile.worker
 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 'git config --global --add safe.directory /app 2>/dev/null || true' >> /usr/local/bin/docker-entrypoint.sh && \
-    echo 'git config --global --add safe.directory /var/ckeditor5-editor-bundle 2>/dev/null || true' >> /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 2>/dev/null || true' >> /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 '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/README.md

@@ -1,6 +1,6 @@
 # CKEditor 5 Editor Bundle — Demo (Symfony 8.1)
 
-This demo runs with **FrankenPHP** (Caddy, HTTP on port 80 inside the container). In **dev** (`APP_ENV=dev`), worker mode is disabled so each request runs in a new PHP process and **code/template changes are visible on refresh** without restarting the container.
+This demo runs with **FrankenPHP** (Caddy, HTTP on port 80 inside the container). Runtime mode is **`FRANKENPHP_MODE`** in `.env` (default **`worker`**). Set **`classic`** for per-request PHP so **code/template changes are visible on refresh**, then recreate the container (`docker compose up -d` / `make up`). `APP_ENV=dev` still enables the Web Profiler.
 
 The app pins **Symfony 8.1.*** via `extra.symfony.require` in `composer.json`. **Symfony 8** requires **PHP ≥8.4** (see the demo Dockerfile / Compose PHP image). Symfony **6.4** / **7.x** compatibility is covered by the CI PHPUnit matrix.
 

demo/symfony8/docker-compose.yml

@@ -21,6 +21,7 @@ services:
       - APP_ENV=dev
       - APP_DEBUG=1
       - APP_SECRET=${APP_SECRET:-demo-secret}
+      - FRANKENPHP_MODE=${FRANKENPHP_MODE:-worker}
     # Mitigate Docker/WSL DNS failures resolving repo.packagist.org (composer curl error 6).
     dns:
       - 8.8.8.8

demo/symfony8/docker/entrypoint.sh

@@ -0,0 +1,35 @@
+#!/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)
+		if [ -f /app/docker/frankenphp/Caddyfile.dev ]; then
+			cp /app/docker/frankenphp/Caddyfile.dev /etc/frankenphp/Caddyfile
+		elif [ -f /etc/frankenphp/Caddyfile.dev ]; then
+			cp /etc/frankenphp/Caddyfile.dev /etc/frankenphp/Caddyfile
+		fi
+		;;
+	worker)
+		if [ -f /app/docker/frankenphp/Caddyfile ]; then
+			cp /app/docker/frankenphp/Caddyfile /etc/frankenphp/Caddyfile
+		elif [ -f /etc/frankenphp/Caddyfile.worker ]; then
+			cp /etc/frankenphp/Caddyfile.worker /etc/frankenphp/Caddyfile
+		fi
+		# else keep image default Caddyfile (worker enabled at build time)
+		;;
+	*)
+		echo "Unknown FRANKENPHP_MODE=$MODE (expected classic|worker)" >&2
+		exit 1
+		;;
+esac
+echo "FrankenPHP mode: $MODE"
+
+git config --global --add safe.directory /app 2>/dev/null || true
+git config --global --add safe.directory /var/ckeditor5-editor-bundle 2>/dev/null || true
+mkdir -p /app/var/cache /app/var/log
+chmod -R 777 /app/var 2>/dev/null || true
+
+exec frankenphp run --config /etc/frankenphp/Caddyfile --adapter caddyfile

docs/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.1] - 2026-07-22
+
+### Changed
+
+- Demo FrankenPHP: select runtime with **`FRANKENPHP_MODE`** (`worker` default / `classic`) via `.env` + Compose; extract `docker/entrypoint.sh` (no longer inline in the Dockerfile).
+- Documentation: [`DEMO-FRANKENPHP.md`](DEMO-FRANKENPHP.md), demo README, and root README aligned with `FRANKENPHP_MODE` (no longer implies `APP_ENV=dev` alone disables workers).
+
 ## [1.2.0] - 2026-07-18
 
 ### Changed
@@ -109,7 +116,8 @@ First semver release (documented stable line, CI and Packagist aligned with tag
 - PHPUnit: integration suite + unit test for `upload_url` CSRF branch (**100%** PHP Clover on `src/`).
 - PHP-CS-Fixer finder excludes generated integration fixture cache and `tests/Fixtures/app/config/reference.php`.
 
-[Unreleased]: https://github.com/nowo-tech/Ckeditor5EditorBundle/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/nowo-tech/Ckeditor5EditorBundle/compare/v1.2.1...HEAD
+[1.2.1]: https://github.com/nowo-tech/Ckeditor5EditorBundle/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/nowo-tech/Ckeditor5EditorBundle/compare/v1.1.4...v1.2.0
 [1.1.4]: https://github.com/nowo-tech/Ckeditor5EditorBundle/compare/v1.1.3...v1.1.4
 [1.1.3]: https://github.com/nowo-tech/Ckeditor5EditorBundle/compare/v1.1.2...v1.1.3

docs/DEMO-FRANKENPHP.md

@@ -1,6 +1,6 @@
 # Demo applications with FrankenPHP (development and production)
 
-This document describes how the **CKEditor 5 Editor Bundle** demos run under **FrankenPHP** in Docker: development (no worker, changes on refresh) vs production-style (worker). Reuse the same pattern in other Symfony bundles with FrankenPHP demos.
+This document describes how the **CKEditor 5 Editor Bundle** demos run under **FrankenPHP** in Docker: **`classic`** (no worker, changes on refresh) vs **`worker`** (production-style). Switch with **`FRANKENPHP_MODE`**. Reuse the same pattern in other Symfony bundles with FrankenPHP demos.
 
 ## Contents
 
@@ -9,6 +9,7 @@ This document describes how the **CKEditor 5 Editor Bundle** demos run under **F
 - [Development](#development)
 - [Production / worker mode](#production--worker-mode)
 - [Ports and URLs](#ports-and-urls)
+- [Switching classic vs worker (`FRANKENPHP_MODE`)](#switching-classic-vs-worker-frankenphp_mode)
 - [Troubleshooting](#troubleshooting)
 
 ## Overview
@@ -20,7 +21,7 @@ Each demo uses:
 - **FrankenPHP** (Caddy + PHP) in one container.
 - **Docker Compose** mounting the demo app and the parent bundle at **`/var/ckeditor5-editor-bundle`** for the Composer **path** repository.
 - **`Caddyfile`** (production-oriented, worker) and **`Caddyfile.dev`** (development, classic `php_server`).
-- An **entrypoint** that, when running in dev, activates `Caddyfile.dev` so Twig and bundle changes are visible without restarting workers.
+- An **entrypoint** that selects the Caddyfile from **`FRANKENPHP_MODE`** (`worker` or `classic`). Use **`classic`** so Twig and bundle changes are visible without restarting workers.
 
 There is one demo: **`demo/symfony8`** (Symfony **8.1.***, default HTTP port **8021**). From the bundle root:
 
@@ -40,15 +41,16 @@ The bundle under test is **`nowo-tech/ckeditor5-editor-bundle`**, installed from
 
 ### FrankenPHP worker mode (compatibility)
 
-**FrankenPHP worker mode:** Supported for production-style runs (worker-enabled `Caddyfile`, e.g. `worker /app/public/index.php 2` inside `php_server`). The **bundle itself** is a form widget + static JS; it does not require workers. Development demos intentionally **disable** worker mode so PHP/Twig changes apply on refresh — see each demo’s `docker/frankenphp/` files (`Caddyfile` vs `Caddyfile.dev`).
+**FrankenPHP worker mode:** Supported for production-style runs (worker-enabled `Caddyfile`, e.g. `worker /app/public/index.php 2` inside `php_server`). The **bundle itself** is a form widget + static JS; it does not require workers. For local editing with refresh, set **`FRANKENPHP_MODE=classic`** — see each demo’s `docker/frankenphp/` files (`Caddyfile` vs `Caddyfile.dev`).
 
 ## Development
 
 Goal: edit PHP, Twig, YAML, or bundle sources and see changes after a browser refresh.
 
-- Use **`Caddyfile.dev`**: classic **`php_server`** without **`worker`** inside `php_server`.
+- Set **`FRANKENPHP_MODE=classic`** in the demo `.env` (entrypoint activates **`Caddyfile.dev`**: classic **`php_server`** without **`worker`**).
+- Recreate the container after changing `.env` (`docker compose up -d` / `make up`); a plain restart does not reload env.
 - **`docker/php-dev.ini`**: short OPcache revalidation interval for dev.
-- **`APP_ENV=dev`**, **`APP_DEBUG=1`** in Compose (see each demo’s `docker-compose.yml`).
+- **`APP_ENV=dev`**, **`APP_DEBUG=1`** in Compose (see each demo’s `docker-compose.yml`) for Profiler / debug tooling.
 - **DNS**: Compose sets **`dns: 8.8.8.8` / `8.8.4.4`** so Composer can resolve Packagist inside Docker/WSL.
 
 Start from **`demo/symfony8`** with `make up` (see **`demo/README.md`**).
@@ -57,8 +59,8 @@ Start from **`demo/symfony8`** with `make up` (see **`demo/README.md`**).
 
 For production-like behaviour:
 
-- Use **`APP_ENV=prod`**, **`APP_DEBUG=0`**, and the **`Caddyfile`** that enables FrankenPHP workers.
-- Warm Symfony cache and follow deployment hardening for `var/` and secrets.
+- Keep **`FRANKENPHP_MODE=worker`** (default) so the entrypoint uses the worker **`Caddyfile`**.
+- Optionally use **`APP_ENV=prod`**, **`APP_DEBUG=0`**, warm Symfony cache, and follow deployment hardening for `var/` and secrets.
 
 Compare **`Caddyfile`** vs **`Caddyfile.dev`** in `demo/symfony8/docker/frankenphp/`.
 
@@ -70,8 +72,19 @@ Compare **`Caddyfile`** vs **`Caddyfile.dev`** in `demo/symfony8/docker/frankenp
 
 Override `PORT` in the demo `.env` (from `.env.example`) if ports clash.
 
+## 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.
+
 ## Troubleshooting
 
 - **Composer cannot resolve `repo.packagist.org`**: Ensure Docker DNS is set (this repo’s compose files include public DNS). On corporate networks you may need internal DNS forwarders.
-- **Changes not visible**: Confirm you are in **dev** with **`Caddyfile.dev`** (no worker). Restart the container after switching Caddyfiles.
+- **Changes not visible**: Set **`FRANKENPHP_MODE=classic`** and recreate the container so **`Caddyfile.dev`** is active (no worker).
 - **Bundle not updating**: Run **`make update-bundle`** in the demo or `composer update nowo-tech/ckeditor5-editor-bundle` inside the container after editing the path-mounted bundle.

docs/UPGRADING.md

@@ -127,6 +127,15 @@ nowo_ckeditor5_editor:
 
 See [`CHANGELOG.md`](CHANGELOG.md) (section **1.2.0**) and [`CONFIGURATION.md`](CONFIGURATION.md).
 
+## To 1.2.1 from 1.2.0
+
+Patch release: FrankenPHP **demo** runtime switch via **`FRANKENPHP_MODE`** and documentation alignment. No bundle API, YAML, or runtime behaviour changes for applications.
+
+- **Contributors / local demos**: default is **`worker`**. For hot-reload on refresh, set **`FRANKENPHP_MODE=classic`** in `demo/symfony8/.env` and recreate the container (`docker compose up -d` / `make up`). See [`DEMO-FRANKENPHP.md`](DEMO-FRANKENPHP.md).
+- **Composer**: `composer update nowo-tech/ckeditor5-editor-bundle` only if you pin an exact patch (e.g. `1.2.0`); with `^1.0` or `^1.2`, **1.2.1** is included on update.
+
+See [`CHANGELOG.md`](CHANGELOG.md) (section **1.2.1**).
+
 ## To 1.x (first documented stable line)
 
 When upgrading from snapshots without semver tags in your project: