# Prerequisites for Building WASM Components with TypePHP: Complete Setup Guide

> Learn the prerequisites for building WASM components with TypePHP. Install WASI SDK, add Wasmtime to PATH, and enable Wasm compilation in project.yml for seamless development.

- Repository: [Swoole Project/typephp](https://github.com/swoole/typephp)
- Tags: how-to-guide
- Published: 2026-08-30

---

**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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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:

```bash
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:

```bash
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:

```bash
composer require swoole/typephp

```

The compiler entry point at [`src/compiler.php`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/src/Build/WasiProjectConfig.php)) scans [`project.yml`](https://github.com/swoole/typephp/blob/main/project.yml) for a boolean flag that triggers the Wasm build path.

Add the following to your configuration file:

```yaml
wasm: true

```

When this flag is present, the `WasmInterfaceGenerator` (located in [`src/Build/WasmInterfaceGenerator.php`](https://github.com/swoole/typephp/blob/main/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:

```bash
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`](https://github.com/swoole/typephp/blob/main/src/Math.php)):**

```php
<?php
use TypePHP\Wasm\WasmExport;

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

```

**Compilation Command:**

```bash
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:**

```bash
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`](https://github.com/swoole/typephp/blob/main/src/compiler.php)** – Contains `shouldCompileWasm()` for prerequisite validation and `compileWasmProgram()` for orchestrating the Clang and Wasmtime toolchain.
- **[`src/Build/WasiProjectConfig.php`](https://github.com/swoole/typephp/blob/main/src/Build/WasiProjectConfig.php)** – Parses [`project.yml`](https://github.com/swoole/typephp/blob/main/project.yml) to determine if the Wasm generator should activate.
- **[`src/Build/WasmInterfaceGenerator.php`](https://github.com/swoole/typephp/blob/main/src/Build/WasmInterfaceGenerator.php)** – Generates C interface code for functions marked with `#[WasmExport]`.
- **[`wasm/README.md`](https://github.com/swoole/typephp/blob/main/wasm/README.md)** – Official documentation for advanced Wasm build options.
- **[`phpunit/code/wasm-export-valid.php`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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.