fix: FrankenPHP fallback to chokidar on poll

[AlliBalliBaba]

Fixes #1034

FrankenPHP's built in watcher does not support polling. If --poll is passed, the watcher should fallback to chokidar. This fixes setups where the repo might be in a mount like the windows mount on wsl.

@IranMine123 can you try if this branch makes --watch --poll work for you on WSL?

[IranMine123]

@AlliBalliBaba I think It should install chokidar too right? tried php artisan octane:install but still chokidar is missing

   INFO  Server running….


  Local: http://127.0.0.1:8000 

  Press Ctrl+C to stop the server

   ERROR  Watcher process has terminated. Please ensure Node and chokidar are installed. node:internal/modules/package_json_reader:173 const result = modulesBinding.getNearestParentPackageJSON(checkPath); ^ Error: Invalid package config package.json. at Object.getNearestParentPackageJSON (node:internal/modules/package_json_reader:173:33) at trySelf (node:internal/modules/cjs/loader:634:33) at Module._resolveFilename (node:internal/modules/cjs/loader:1432:24) at defaultResolveImpl (node:internal/modules/cjs/loader:1066:19) at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1071:22) at Module._load (node:internal/modules/cjs/loader:1242:25) at wrapModuleLoad (node:internal/modules/cjs/loader:255:19) at Module.require (node:internal/modules/cjs/loader:1556:12) at require (node:internal/modules/helpers:152:16) at Object.<anonymous> (vendor/laravel/octane/bin/file-watcher.cjs:1:18) { code: 'ERR_INVALID_PACKAGE_CONFIG' } Node.js v24.14.0 .

[AlliBalliBaba]

Yeah with the default watcher you sadly need node and chokidar installed as well. Something like:

sudo apt install -y nodejs
sudo npm install -g chokidar

[IranMine123]

@AlliBalliBaba ok it's working for now but there are some issues here:

• I had to install the chokidar on the project, it cannot find the global package one
• changes on .env are detected, but not getting applied

   INFO  Server running….


  Local: http://127.0.0.1:8000 

  Press Ctrl+C to stop the server

  204    GET /sanctum/csrf-cookie ........................................................................... 4000.91 ms
  200    POST /login ........................................................................................ 4209.63 ms

   INFO  Application change detected. Restarting workers….

   ERROR  stopping current admin endpoint.  

  204    GET /sanctum/csrf-cookie ........................................................................... 3983.01 ms
  200    POST /login ........................................................................................ 1240.75 ms

About the first one I think it is possible to add chokidar installation on octane:install but no idea about the second one.

[AlliBalliBaba]

.env not updating seems strange, do you maybe have your config cached? (try php artisan optimize:clear)

If you are updating env variables that affect the octane process itself you might have to completely restart manually. Watching will only restart the workers, not the octane:start wrapper process

[IranMine123]

well tried to change DB_HOST to a random thing so it throws an error, but looks like the changes are not applying, even after optimize:clear.
another thing I noticed is that the watcher restarts the server based on every file change, for example after I cleared the cache (optimize:clear, which removed packages.php and services.php for me), which makes the reload time worse.

[AlliBalliBaba]

another thing I noticed is that the watcher restarts the server based on every file change, for example after I cleared the cache (optimize:clear, which removed packages.php and services.php for me), which makes the reload time worse.

This is expected behaviour and means the polling works. The watcher will restart on any change to .php files (you can configure which directories in the octane.php config).

which makes the reload time worse.

If you care about performance, I'd still recommend moving the project inside of WSL, which will be much faster overall. You'll have to properly set up your IDE though. Windows is just really slow with file access.

well tried to change DB_HOST to a random thing so it throws an error, but looks like the changes are not applying, even after optimize:clear.

That seems like a bug independent from this PR. If you decide to move into WSL, you can also try running FrankenPHP directly, without octane:start and see if that resolves the issue.

# replace /path/to/laravel with the absolute path to the Laravel project
# replace /path/to/Caddyfile with the path to the Caddyfile below
APP_BASE_PATH=/path/to/laravel frankenphp run -c /path/to/Caddyfile

Caddyfile example:

{
    # https://caddyserver.com/docs/caddyfile
    # https://frankenphp.dev/docs/config
    admin localhost:2019

    frankenphp {
        php_ini {
            max_execution_time 30 # you can add more php.ini settings here
        }
    }
}

:80 { # running on HTTP port 80
    route {
        encode zstd br gzip # enable compression
        php_server {
            root {$APP_BASE_PATH}/public # public path of laravel
            worker {
                file "{$APP_BASE_PATH}/vendor/laravel/octane/bin/frankenphp-worker.php"
                num 4 # initial threads, roughly number of CPU cores, can also be higher
                max_threads 20 # maximum of threads, roughly 5x CPU cores, can also be higher
                match * # send all requests to this worker
                watch {$APP_BASE_PATH} # watcher enabled
            }
        }
    }
}