Can PHP Be Compiled to EXE? A Practical Guide with ThinkPHP 8 and TypePHP

TypePHP × ThinkPHP 8.0 native AOT compilation creates a Windows binary that runs without a PHP interpreter, Nginx/Apache, or visible .php files, delivering more than a 9.2× throughput increase compared with traditional PHP‑FPM.

Architecture principle : In the classic PHP‑FPM/CLI model a request passes through lexical analysis → syntax analysis → OPCODE generation → Zend VM interpretation. TypePHP’s AOT compiler instead translates PHP source directly to C++ code, which MSVC compiles into a native .exe that embeds the PHP 8.5 embed SAPI, eliminating interpreter overhead.

Step 1 – Environment preparation : Required OS is Windows 10/11 64‑bit, C++ toolchain is Visual Studio 2022 (Community), and the TypePHP SDK (tpc_v0.6.5_windows_x86_64) is downloaded from the official GitHub releases. System variables PHP_HOME and PHPX_HOME are set to the SDK directory, and the SDK path is added to PATH. Windows Defender real‑time protection must whitelist the SDK and project directories to avoid minutes‑long compile stalls.

Step 2 – Project adaptation and build configuration : A project.yml file declares the source roots (ThinkPHP core, vendor packages, app code) and output settings (binary name myapp, mode bin, optimization level 2, parallel jobs 16). An build_env.bat script sets the environment, detects the MSVC toolchain, prepares the build folder, synchronises php.ini, and invokes tpc.exe to perform AOT compilation.

Running .\build_env.bat triggers a full compilation of about 390 source files (≈1–2 minutes). Subsequent incremental builds after PHP code changes finish in 2–4 seconds because only the changed objects are relinked.

Step 3 – Execution and verification : A run_env.bat script launches the generated myapp.exe. .\run_env.bat info prints runtime details (PHP 8.5.10, embed SAPI, loaded extensions, HTTP 200). Starting the server with .\run_env.bat run -p 8788 -H 0.0.0.0 and visiting http://localhost:8788/hello/world shows a fully AOT‑driven ThinkPHP page with sub‑millisecond response time.

Deep‑dive pitfalls (with causes and fixes):

Compiled exe cannot find autoload.php after moving directories because __DIR__ is baked in; fix by using getcwd() to build a dynamic path.

Missing build/ folder after cloning (Git omits empty directories); fix by adding a .gitkeep and creating the folder in the batch script. php.ini hard‑codes extension_dir, causing extension load failures; fix by using the environment‑variable syntax extension_dir="${PHP_HOME}/ext".

TypeError for the port argument because the CLI returns a string while ThinkPHP expects an int; fix by casting to (int) in RunServer.php.

File‑lock error when recompiling because the previous myapp.exe remains running; fix by stopping the process via PowerShell before rebuilding.

Linker conflicts when tpc.exe picks up Git’s link.exe instead of MSVC’s; fix by using the "x64 Native Tools Command Prompt for VS 2022" or the provided build_env.bat which forces the correct toolchain.

Conclusion and outlook : AOT compilation turns PHP applications into single‑file native binaries, simplifying delivery, providing strong source‑code protection, and achieving cloud‑native performance with near‑zero startup latency and controllable memory usage. The author invites further discussion on PHP AOT compilation and cloud‑native architecture.