Say Goodbye to the PHP Interpreter: Build Webman as a Pure Native Binary

Core Build Workflow

On Windows the process is driven by two batch scripts. build.bat runs tpc.exe project.yml, which invokes the MSVC toolchain ( cl.exe + link.exe) to compile the C++ code generated from the Webman AST and link it with the static libraries phpx and libphp8embed, producing build/webman_server.exe. package.bat then assembles the executable, runtime DLLs ( php8ts.dll, phpx.dll), the ext/ directory, configuration files ( config/), and static assets ( public/, view/) into a standalone dist/ folder. It also generates dist/run.bat, which injects PHPRC and PATH so the binary can be started from any terminal.

Static‑Compilation Conflicts and Deep Adaptations

1. Symbol ambiguity between route annotations and router objects – When both the annotation class and the router object are imported in App.php, the AOT compiler may bind Route::dispatch() to the annotation class, breaking routing. Solution: use fully‑qualified class names such as \Webman\Route::dispatch(), \Webman\Route::getFallback(), and static::setCollector() to eliminate ambiguity.

2. Closure argument count enforcement – Workerman’s silent‑error closures (e.g., set_error_handler(static fn (): bool => true);) pass four arguments at runtime, which the PHP CLI silently discards. The strict C++ runtime throws ArgumentCountError (expects 0, 4 given). Solution: replace such closures with a variadic signature static fn (...$args): bool => true and apply the same fix to Worker::stopAll() where array_walk closures are used.

3. Embed SAPI support – The compiled binary runs under the embed SAPI provided by libphp8embed. Workerman’s environment check only allows cli and micro, causing startup failure. Solution: add 'embed' to the whitelist in Worker::checkSapiEnv().

4. Windows event‑driven callbacks visibility – Methods like acceptTcpConnection(), acceptUdpConnection(), checkErrors(), and signalHandler() are declared protected, which the static compiler blocks when invoked across class boundaries. Solution: change them to public and use PHP 8.1+ first‑class callable syntax static::signalHandler(...), eliminating the TypeError: Argument must be of type callable, array given.

5. Dynamic view engine features – The default Raw.php view engine relies on extract() and the $$ variable syntax, which the compiler cannot resolve at build time. Solution: refactor the engine to a deterministic variable traversal and placeholder replacement, removing the need for extract().

Final Execution and Full‑Stack Verification

After all adaptations, the distribution package runs on a bare machine without any PHP installation. The startup commands are:

cd dist
.\webman-server.exe

The console shows normal Workerman startup information and confirms that all core routes respond correctly:

GET / → HTTP 200, welcome page

GET /index/json → HTTP 200, {"code":0,"msg":"ok"} GET /index/view → HTTP 200, hello webman GET /not-found → HTTP 404, standard error page

Open‑Source Contributions

The modifications made during this compilation were contributed back to the upstream projects via pull requests:

Workerman core:

fix: improve PHP 8 strict callback compatibility, visibility, and allow embed SAPI

Webman framework:

fix: eliminate symbol ambiguity and improve strict callback compatibility

All configuration files, batch scripts, and adaptation details are publicly available for further experimentation and discussion.