Prerequisites for Building WASM Components with TypePHP: Complete Setup Guide

To build WebAssembly components with TypePHP, you must install the WASI SDK, ensure the Wasmtime binary is available in your system PATH, and enable Wasm compilation by setting wasm: true in your project.yml file.

The swoole/typephp repository allows you to compile annotated PHP functions into portable WASI-compliant WebAssembly modules. Because the build pipeline relies on external system toolchains rather than pure PHP libraries, satisfying the environment prerequisites is mandatory before the compiler can generate .wasm binaries. This guide details the exact dependencies, configuration flags, and validation logic implemented in src/compiler.php that govern the Wasm build process.

System Toolchain Requirements

TypePHP does not bundle a C compiler or Wasm runtime. The compileWasmProgram() function in src/compiler.php explicitly searches for two external dependencies and aborts with the error Add WASI SDK and Wasmtime bin directories to PATH if either is missing.

WASI SDK

The WASI SDK provides the clang compiler, wasm-ld linker, and sysroot headers required to target the wasm32-wasi ABI. Download the latest release from the official WebAssembly repository and expose the binary directory:

export WASI_SDK_PATH=/opt/wasi-sdk
export PATH=$PATH:$WASI_SDK_PATH/bin

The compiler invokes $WASI_SDK_PATH/bin/clang during the compileWasmProgram() execution to translate generated C glue code into a Wasm module.

Wasmtime Runtime

Wasmtime serves as the reference runtime for both testing and executing the resulting binaries. The shouldCompileWasm() utility verifies that wasmtime is executable before proceeding with the build.

Install Wasmtime and verify accessibility:

curl https://wasmtime.dev/install.sh -sSf | bash

# Verify

which wasmtime

PHP Environment

You need PHP 8.2 or newer with CLI support and Composer to install the TypePHP library:

composer require swoole/typephp

The compiler entry point at src/compiler.php bootstraps the build pipeline only after confirming the PHP version satisfies this constraint.

Project-Level Configuration

Wasm generation is opt-in. The WasiProjectConfig class (defined in src/Build/WasiProjectConfig.php) scans project.yml for a boolean flag that triggers the Wasm build path.

Add the following to your configuration file:

wasm: true

When this flag is present, the WasmInterfaceGenerator (located in src/Build/WasmInterfaceGenerator.php) processes PHP files containing the #[WasmExport] attribute and emits the necessary C shims.

Optional Environment Variables

For continuous integration or internal testing scenarios, you can bypass the external Clang invocation by setting:

export TYPEPHP_WASM_INTERNAL_COMPILE=1

When this variable equals 1, compileWasmProgram() skips the toolchain execution, allowing you to test the PHP-to-C transpilation without a full Wasm binary.

Implicit Build Dependencies

Although TypePHP does not explicitly check for them, the generated build scripts assume standard Unix tooling is available. Ensure make, ninja, or cmake are installed if your project links additional native libraries.

Compiling a WASM Component

Once prerequisites are satisfied, annotate your PHP code and invoke the compiler.

Example PHP Function (src/Math.php):

<?php
use TypePHP\Wasm\WasmExport;

#[WasmExport(name: 'add')]
function add(int $x, int $y): int {
    return $x + $y;
}

Compilation Command:

php src/compiler.php --config=project.yml --wasm

The compiler first calls shouldCompileWasm() to validate the WASI SDK and Wasmtime paths. Upon success, compileWasmProgram() generates the Wasm binary in your configured output directory (typically target/wasm/).

Running the Result:

wasmtime target/wasm/math.wasm --invoke add 10 20

Key Source Files in the Repository

Understanding the following files helps debug build failures and extend the Wasm pipeline:

• src/compiler.php – Contains shouldCompileWasm() for prerequisite validation and compileWasmProgram() for orchestrating the Clang and Wasmtime toolchain.
• src/Build/WasiProjectConfig.php – Parses project.yml to determine if the Wasm generator should activate.
• src/Build/WasmInterfaceGenerator.php – Generates C interface code for functions marked with #[WasmExport].
• wasm/README.md – Official documentation for advanced Wasm build options.
• phpunit/code/wasm-export-valid.php – Reference test fixture demonstrating valid #[WasmExport] syntax.

Summary

• Install the WASI SDK and add its bin directory to your PATH to provide the wasm32-wasi compiler.
• Install Wasmtime and ensure it is available in your PATH for runtime validation and execution.
• Set wasm: true in project.yml to enable the WasiProjectConfig and WasmInterfaceGenerator pipeline.
• Annotate target functions with #[WasmExport] to expose them in the generated module.
• Use TYPEPHP_WASM_INTERNAL_COMPILE=1 only when you need to skip the actual Wasm binary creation in CI environments.
• The compiler enforces all prerequisites in src/compiler.php before invoking the external build tools.

Frequently Asked Questions

Do I need Emscripten to compile TypePHP to Wasm?

No. TypePHP targets the WASI standard exclusively using the WASI SDK's Clang distribution. The compileWasmProgram() function in src/compiler.php invokes the SDK's clang with wasm32-wasi targets, bypassing Emscripten's proprietary runtime and glue code entirely.

What happens if wasm: true is missing from project.yml?

If WasiProjectConfig.php does not detect the wasm flag, the WasmInterfaceGenerator skips all processing. Your PHP code will compile normally for the PHP runtime, but no .wasm output will be produced even if #[WasmExport] attributes are present.

Can I build TypePHP Wasm components on Windows natively?

The current implementation in src/compiler.php assumes Unix-style PATH resolution and shell command execution for clang and wasmtime. While the WASI SDK and Wasmtime offer Windows binaries, you should use WSL2 or a Linux container to satisfy the compiler's environment expectations.

Is the TYPEPHP_WASM_INTERNAL_COMPILE variable required for production?

No. This variable is intended strictly for internal testing and CI pipelines where you want to validate the PHP-to-C transpilation without executing the full Clang toolchain. In production builds, omit this variable so that compileWasmProgram() produces the actual Wasm binary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}