Bug: watcher in FrankenPHP mode worker after changes .env

[ddevsr]

PHP Version

8.5

CodeIgniter4 Version

4.7.0

CodeIgniter4 Installation Method

Composer (using codeigniter4/appstarter)

Which operating systems have you tested for this bug?

Linux

Which server did you use?

apache

Environment

development

Database

none

What happened?

After running well, we changes value in .env, watcher auto restart service. When i open my web running well but i see error in logging like below

{"level":"error","ts":1770026066.662407,"logger":"frankenphp","msg":"PHP Fatal error:  Cannot redeclare class Config\\Paths (previously declared in /home/myproject/app/Config/Paths.php:16) in /home/myproject/app/Config/Paths.php on line 16\nStack trace:\n#0 /home/myproject/public/frankenphp-worker.php(52): require()\n#1 {main}","syslog_level":"err","stacktrace":"github.com/dunglas/frankenphp.go_log\n\t/go/src/app/frankenphp.go:696\n_cgoexp_634fea83287e_go_log\n\t_cgo_gotypes.go:2015\nruntime.cgocallbackg1\n\t/usr/local/go/src/runtime/cgocall.go:446\nruntime.cgocallbackg\n\t/usr/local/go/src/runtime/cgocall.go:350\nruntime.cgocallback\n\t/usr/local/go/src/runtime/asm_amd64.s:1082"}

root@devserver:/home/myproject# docker logs eclaim-monitor
{"level":"info","ts":1770023148.190232,"msg":"maxprocs: Leaving GOMAXPROCS=8: CPU quota undefined"}
{"level":"info","ts":1770023148.1913888,"msg":"GOMEMLIMIT is updated","package":"github.com/KimMachineGun/automemlimit/memlimit","GOMEMLIMIT":1808308224,"previous":9223372036854775807}
{"level":"info","ts":1770023148.191685,"msg":"using config from file","file":"/Caddyfile"}
{"level":"info","ts":1770023148.2195253,"msg":"adapted config to JSON","adapter":"caddyfile"}
{"level":"warn","ts":1770023148.219635,"msg":"Caddyfile input is not formatted; run 'caddy fmt --overwrite' to fix inconsistencies","adapter":"caddyfile","file":"/Caddyfile","line":7}
{"level":"warn","ts":1770023148.220112,"logger":"admin","msg":"admin endpoint disabled"}
{"level":"info","ts":1770023148.22098,"logger":"tls.cache.maintenance","msg":"started background certificate maintenance","cache":"0xc00032f900"}
{"level":"info","ts":1770023151.8490129,"logger":"frankenphp","msg":"FrankenPHP started 🐘","php_version":"8.5.2","num_threads":8,"max_threads":8}
{"level":"warn","ts":1770023151.8509414,"logger":"http","msg":"HTTP/2 skipped because it requires TLS","network":"tcp","addr":":2000"}
{"level":"warn","ts":1770023151.850975,"logger":"http","msg":"HTTP/3 skipped because it requires TLS","network":"tcp","addr":":2000"}
{"level":"info","ts":1770023151.8509815,"logger":"http.log","msg":"server running","name":"srv0","protocols":["h1","h2","h3"]}
{"level":"info","ts":1770023151.8894033,"msg":"autosaved config (load with --resume flag)","file":"/config/caddy/autosave.json"}
{"level":"info","ts":1770023151.8894334,"msg":"serving initial configuration"}
{"level":"info","ts":1770023152.024021,"logger":"tls","msg":"cleaning storage unit","storage":"FileStorage:/data/caddy"}
{"level":"info","ts":1770023152.0857525,"logger":"tls","msg":"finished cleaning storage units"}
{"level":"info","ts":1770026066.6598158,"logger":"frankenphp","msg":"filesystem changes detected","events":[{"effect_time":"2026-02-02T09:54:26.5067319Z","path_name":"/home/myproject/.env","effect_type":"modify","path_type":"file"},{"effect_time":"2026-02-02T09:54:26.508755955Z","path_name":"/home/myproject/.env","effect_type":"modify","path_type":"file"}]}
{"level":"error","ts":1770026066.662407,"logger":"frankenphp","msg":"PHP Fatal error:  Cannot redeclare class Config\\Paths (previously declared in /home/myproject/app/Config/Paths.php:16) in /home/myproject/app/Config/Paths.php on line 16\nStack trace:\n#0 /home/myproject/public/frankenphp-worker.php(52): require()\n#1 {main}","syslog_level":"err","stacktrace":"github.com/dunglas/frankenphp.go_log\n\t/go/src/app/frankenphp.go:696\n_cgoexp_634fea83287e_go_log\n\t_cgo_gotypes.go:2015\nruntime.cgocallbackg1\n\t/usr/local/go/src/runtime/cgocall.go:446\nruntime.cgocallbackg\n\t/usr/local/go/src/runtime/cgocall.go:350\nruntime.cgocallback\n\t/usr/local/go/src/runtime/asm_amd64.s:1082"}
{"level":"error","ts":1770026066.6624215,"logger":"frankenphp","msg":"PHP Fatal error:  Cannot redeclare class Config\\Paths (previously declared in /home/myproject/app/Config/Paths.php:16) in /home/myproject/app/Config/Paths.php on line 16\nStack trace:\n#0 /home/myproject/public/frankenphp-worker.php(52): require()\n#1 {main}","syslog_level":"err","stacktrace":"github.com/dunglas/frankenphp.go_log\n\t/go/src/app/frankenphp.go:696\n_cgoexp_634fea83287e_go_log\n\t_cgo_gotypes.go:2015\nruntime.cgocallbackg1\n\t/usr/local/go/src/runtime/cgocall.go:446\nruntime.cgocallbackg\n\t/usr/local/go/src/runtime/cgocall.go:350\nruntime.cgocallback\n\t/usr/local/go/src/runtime/asm_amd64.s:1082"}
{"level":"warn","ts":1770026066.6631985,"logger":"frankenphp","msg":"(watcher enabled) worker script has not reached frankenphp_handle_request()","worker":"/home/myproject/public/frankenphp-worker.php","thread":6}
{"level":"warn","ts":1770026066.6632814,"logger":"frankenphp","msg":"(watcher enabled) worker script has not reached frankenphp_handle_request()","worker":"/home/myproject/public/frankenphp-worker.php","thread":5}
{"level":"error","ts":1770026066.663518,"logger":"frankenphp","msg":"PHP Fatal error:  Cannot redeclare class Config\\Paths (previously declared in /home/myproject/app/Config/Paths.php:16) in /home/myproject/app/Config/Paths.php on line 16\nStack trace:\n#0 /home/myproject/public/frankenphp-worker.php(52): require()\n#1 {main}","syslog_level":"err","stacktrace":"github.com/dunglas/frankenphp.go_log\n\t/go/src/app/frankenphp.go:696\n_cgoexp_634fea83287e_go_log\n\t_cgo_gotypes.go:2015\nruntime.cgocallbackg1\n\t/usr/local/go/src/runtime/cgocall.go:446\nruntime.cgocallbackg\n\t/usr/local/go/src/runtime/cgocall.go:350\nruntime.cgocallback\n\t/usr/local/go/src/runtime/asm_amd64.s:1082"}
{"level":"warn","ts":1770026066.6635737,"logger":"frankenphp","msg":"(watcher enabled) worker script has not reached frankenphp_handle_request()","worker":"/home/myproject/public/frankenphp-worker.php","thread":6}
{"level":"error","ts":1770026066.6636019,"logger":"frankenphp","msg":"PHP Fatal error:  Cannot redeclare class Config\\Paths (previously declared in /home/myproject/app/Config/Paths.php:16) in /home/myproject/app/Config/Paths.php on line 16\nStack trace:\n#0 /home/myproject/public/frankenphp-worker.php(52): require()\n#1 {main}","syslog_level":"err","stacktrace":"github.com/dunglas/frankenphp.go_log\n\t/go/src/app/frankenphp.go:696\n_cgoexp_634fea83287e_go_log\n\t_cgo_gotypes.go:2015\nruntime.cgocallbackg1\n\t/usr/local/go/src/runtime/cgocall.go:446\nruntime.cgocallbackg\n\t/usr/local/go/src/runtime/cgocall.go:350\nruntime.cgocallback\n\t/usr/local/go/src/runtime/asm_amd64.s:1082"}
{"level":"warn","ts":1770026066.663666,"logger":"frankenphp","msg":"(watcher enabled) worker script has not reached frankenphp_handle_request()","worker":"/home/myproject/public/frankenphp-worker.php","thread":5}

Steps to Reproduce

1. Install fresh starter Codeingiter4
2. Settings config FrankenPHP mode Worker
3. Run your application (OK)
4. Changes value in file like .env

Expected Output

No issue

Anything else?

No response

[miladjef]

The .env file should never trigger a worker reload. Modify your Caddyfile:

    frankenphp {
        worker {
            file /home/myproject/public/frankenphp-worker.php
            num 8

            # Only watch PHP files, NOT .env
            watch /home/myproject/app/**/*.php
            watch /home/myproject/public/**/*.php
        }
    }
}

:2000 {
    root * /home/myproject/public
    php_server
}`


or

The default worker script uses require which causes redeclaration on reload. Replace public/frankenphp-worker.php with:

`<?php

declare(strict_types=1);

use CodeIgniter\Config\Services;

/**
 * Define FCPATH once
 */
if (!defined('FCPATH')) {
    define('FCPATH', __DIR__ . DIRECTORY_SEPARATOR);
}

/**
 * Load Paths config only once - prevents redeclaration
 */
if (!class_exists('Config\Paths', false)) {
    require_once FCPATH . '../app/Config/Paths.php';
}

$paths = new Config\Paths();

/**
 * Bootstrap framework only once
 */
if (!defined('SYSTEMPATH')) {
    require_once rtrim($paths->systemDirectory, '\\/ ') . DIRECTORY_SEPARATOR . 'bootstrap.php';
}

/**
 * Boot CodeIgniter
 */
CodeIgniter\Boot::bootWeb($paths);

/**
 * Create application instance
 */
$app = Services::codeigniter();
$app->initialize();
$app->setContext('web');

/**
 * Request handler for each incoming request
 */
$handler = static function () use ($app): void {
    // Reset services between requests to prevent state pollution
    Services::reset(true);

    $app->initialize();
    $app->setContext('web');

    try {
        $app->run();
    } catch (Throwable $e) {
        log_message('critical', $e->getMessage());
        http_response_code(500);
        echo 'Internal Server Error';
    }
};

/**
 * FrankenPHP worker loop
 */
while (frankenphp_handle_request($handler)) {
    gc_collect_cycles();
}```

[michalsn]

@ddevsr I'm unable to reproduce this on my end:

• bare metal (macOS): FrankenPHP v1.11.1 PHP 8.4.16 Caddy v2.10.2
• with Docker: FrankenPHP v1.11.1 PHP 8.5.2 Caddy v2.10.2

Does it occur only when the .env file changes, or also when other watched PHP files are modified? What exactly are you changing, does it matter? Additionally, have you tested this without using Docker?

[michalsn]

@miladjef We intentionally watch .env in development. It ensures that any changes to environment variables immediately trigger a worker reload, so developers don't have to restart manually. This is meant only for the dev environment - in production, we should never use the watch directive.