From 3bd995e1988b80d48f3915e3fa65220d0d52c88b Mon Sep 17 00:00:00 2001
From: "John Paul E. Balandan, CPA" <paulbalandan@gmail.com>
Date: Tue, 12 May 2026 02:21:54 +0800
Subject: [PATCH] fix: make frankenphp-worker.php template idempotent on
 watcher restart

---
 system/Commands/Worker/Views/frankenphp-worker.php.tpl |  8 +++++---
 user_guide_src/source/changelogs/v4.7.3.rst            |  1 +
 user_guide_src/source/installation/upgrade_473.rst     | 10 ++++++++++
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/system/Commands/Worker/Views/frankenphp-worker.php.tpl b/system/Commands/Worker/Views/frankenphp-worker.php.tpl
index 067d9d33dc1f..801bf796f343 100644
--- a/system/Commands/Worker/Views/frankenphp-worker.php.tpl
+++ b/system/Commands/Worker/Views/frankenphp-worker.php.tpl
@@ -36,7 +36,9 @@ if (version_compare(PHP_VERSION, $minPhpVersion, '<')) {
  *---------------------------------------------------------------
  */
 
-define('FCPATH', __DIR__ . DIRECTORY_SEPARATOR);
+if (! defined('FCPATH')) {
+    define('FCPATH', __DIR__ . DIRECTORY_SEPARATOR);
+}
 
 if (getcwd() . DIRECTORY_SEPARATOR !== FCPATH) {
     chdir(FCPATH);
@@ -49,11 +51,11 @@ if (getcwd() . DIRECTORY_SEPARATOR !== FCPATH) {
  */
 
 // This is the line that might need to be changed, depending on your folder structure.
-require FCPATH . '../app/Config/Paths.php';
+require_once FCPATH . '../app/Config/Paths.php';
 // ^^^ Change this line if you move your application folder
 $paths = new Paths();
 
-require $paths->systemDirectory . '/Boot.php';
+require_once $paths->systemDirectory . '/Boot.php';
 
 // One-time boot - loads autoloader, environment, helpers, etc.
 $app = Boot::bootWorker($paths);
diff --git a/user_guide_src/source/changelogs/v4.7.3.rst b/user_guide_src/source/changelogs/v4.7.3.rst
index f3653336233d..ceb707bb6aab 100644
--- a/user_guide_src/source/changelogs/v4.7.3.rst
+++ b/user_guide_src/source/changelogs/v4.7.3.rst
@@ -49,6 +49,7 @@ Bugs Fixed
 - **Toolbar:** Fixed a bug where the Logs collector raised an undefined property error when using a third-party PSR-3 logger.
 - **Time:** Fixed a bug where ``Time::createFromTimestamp()`` could fail for microsecond timestamps when ``LC_NUMERIC`` used a comma decimal separator.
 - **Validation:** Fixed a bug where ``Validation::getValidated()`` dropped fields whose validated value was explicitly ``null``.
+- **Worker Mode:** Fixed a bug where the ``frankenphp-worker.php`` template caused a ``Cannot redeclare class Config\Paths`` fatal error when FrankenPHP's watcher re-executed the worker script after a watched file changed.
 
 See the repo's
 `CHANGELOG.md <https://github.com/codeigniter4/CodeIgniter4/blob/develop/CHANGELOG.md>`_
diff --git a/user_guide_src/source/installation/upgrade_473.rst b/user_guide_src/source/installation/upgrade_473.rst
index 3a28c7db6824..50ec9a43d291 100644
--- a/user_guide_src/source/installation/upgrade_473.rst
+++ b/user_guide_src/source/installation/upgrade_473.rst
@@ -16,6 +16,16 @@ Please refer to the upgrade instructions corresponding to your installation meth
 Mandatory File Changes
 **********************
 
+Worker Mode
+===========
+
+If you are using Worker Mode, you must update **public/frankenphp-worker.php** after
+upgrading. The easiest way is to re-run the install command:
+
+.. code-block:: console
+
+    php spark worker:install --force
+
 ****************
 Breaking Changes
 ****************