Step‑by‑Step: Build Your First TypePHP Native Binary (Windows Tetris Demo)

The article walks through compiling a PHP script into a native executable using TypePHP, covering both Windows (pre‑packaged toolchain) and Linux (manual setup).

Prerequisites

PHP 8.4 ZTS with embed SAPI

Compiler: GCC/Clang on Linux, MSVC (Visual Studio 2022) on Windows

TypePHP compiler binary tpc (download from GitHub releases)

All PHP headers, php‑config and libphp must come from the same build

Windows: Quick Path

Install Visual Studio 2022 Community, enable "Desktop development with C++".

Download the official TypePHP Windows package from https://github.com/swoole/typephp/releases and extract, e.g. D:\workspace\tpc_v1096_windows_x86_64.

Set environment variables:

PHP_HOME=D:\workspace\tpc_v1096_windows_x86_64
PHPX_HOME=D:\workspace\tpc_v1096_windows_x86_64\phpx
Path=%PATH%;D:\workspace\tpc_v1096_windows_x86_64

Open "x64 Native Tools Command Prompt for VS 2022", run:

cd D:\workspace\tpc_v1096_windows_x86_64
tpc.exe examples\hello.php
hello.exe

The build log shows MSVC commands and ends with Build successful: hello.exe. Running hello.exe prints version information and confirms the binary contains no PHP source.

Linux: Seven‑Step Process

Download and extract the appropriate typephp‑linux‑x86_64.tar.gz to $HOME/typephp.

Ensure PHP embed SAPI is available:

export PHP_HOME=/opt/php-8.4
$PHP_HOME/bin/php-config --php-sapis   # must list embed

Build PHPX from the same PHP sources:

sudo apt-get install -y build-essential cmake pkg-config libgmp-dev libmpfr-dev
git clone https://github.com/swoole/phpx.git /opt/phpx
cmake -S /opt/phpx -B /opt/phpx/build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF -Dphp_dir=$PHP_HOME
cmake --build /opt/phpx/build --parallel 4 --target phpx

Set environment variables PHP_HOME, PHPX_HOME, PATH, LD_LIBRARY_PATH (optionally add to ~/.bashrc or /etc/ld.so.conf.d/typephp.conf).

Verify that both libphp.so and libphpx.so are found:

ldd $HOME/typephp/tpc | grep -E 'libphp(x)?\.so'

Check the compiler works: tpc --version.

Compile the first program, e.g. tpc hello.php -O2 -o hello and run ./hello.

Hello TypePHP

A TypePHP program must provide a global main() function as the entry point, similar to C:

function main(): void {
    echo "Hello TypePHP
";
}

Compile with tpc hello.php -O2 -o hello or tpc hello.php -O2 --run. The resulting hello binary runs without a PHP interpreter.

Project.yml – Real‑World Projects

For larger code bases, a project.yml file describes sources, ignore patterns, build directory, optimization level and parallel jobs. Example snippet:

name: my-app
version: 1.0.0
sources:
  - src
  - main.php
ignore:
  - src/tests/
  - src/vendor/
build-dir: build
optimize: 2
job: 8

Key features include conditional compilation based on PHP_VERSION_ID, cross‑compilation via target-platform, mixing C++ files, and WASM component output. Command‑line options override YAML values, and the priority order is CLI > YAML > defaults.

Three Build Modes

bin

(default): produces an executable. lib: produces a shared library for linking by other TypePHP projects. ext: produces a PHP extension ( .so) that can be loaded by a standard PHP interpreter.

The ext mode enables gradual migration of hot modules to native code.

Case Study – Windows Tetris

The official example compiles a Tetris game where the game logic resides in main.php and the Win32 graphics are implemented in cpp-src/tetris.cc. The directory layout is:

examples\tetris-win32\
├─ project.yml
├─ main.php          # PHP game rules and loop
├─ php-src\tetris.stub.php   # PHP declarations of C++ functions
└─ cpp-src\tetris.cc         # Win32 window, keyboard, GDI drawing

Compiling with:

.\tpc.exe .\examples\tetris-win32\project.yml -O2

produces tetris.exe, a native Windows binary that runs the full game without a PHP runtime. The article lists the key controls and notes two runtime bugs that were fixed (game‑over restart and bitmap resource leak).

Common Errors and Troubleshooting

tpc: command not found

– add the tpc directory to PATH.

Missing shared libraries – use ldd … | grep not found and adjust LD_LIBRARY_PATH.

ABI mismatch between libphpx.so and PHP – rebuild PHPX with the same php-config.

Windows “cl not found” – ensure the MSVC environment is initialized via vcvars64.bat or the x64 Native Tools prompt.

Conflicting link.exe from Git for Windows – verify which one is used with where.exe link.

Conclusion

On Windows the official toolchain works out‑of‑the‑box; on Linux the critical rule is to use a single, consistent build of PHP, PHP‑embed and PHPX. TypePHP requires a global main(), supports three output modes, and its project.yml enables conditional, cross‑compilation and mixed C++/PHP projects. The Tetris example demonstrates a practical mixed‑language native binary.