compiler/wasm

TypePHP WASI SDK layout

TypePHP application builds never compile PHP, PHPX, GMP, MPFR, or mpdecimal. The integrated PHPX installer places their prebuilt wasm32-wasip2 SDK at:

<phpx>/wasm/wasm32-wasip2/
├── include/
│   ├── php/                 PHP installed and generated headers
│   ├── phpx/                PHPX public and TypePHP runtime headers
│   ├── zlib.h               zlib API used by PHP's static zlib extension
│   ├── zconf.h
│   ├── sodium.h
│   ├── openssl/             OpenSSL crypto-only public headers
│   ├── libxml2/             libxml2 public headers
│   ├── sqlite3.h
│   ├── zip.h
│   ├── bzlib.h
│   ├── gmp.h
│   ├── gmpxx.h
│   ├── mpfr.h
│   ├── mpdecimal.h
│   └── decimal.hh
├── lib/
│   ├── libphp.a
│   ├── libphpx.a
│   ├── libgmp.a
│   ├── libgmpxx.a
│   ├── libmpfr.a
│   ├── libmpdec.a
│   └── libmpdec++.a
└── .typephp-wasi-sdk-abi

The zlib, bzip2, libsodium, libcrypto, libxml2, SQLite, and libzip objects are embedded in libphp.a; the SDK intentionally does not ship or link their dependency archives separately.

The ABI file must contain exactly:

typephp-wasip2-sdk-abi-v4

TypePHP locates PHPX through the existing PHPX_HOME setting, Composer's swoole/phpx installation metadata, or vendor/swoole/phpx. TypePHP developers who independently clone and build the matching php-8.5.9-wasm and PHPX repositories install the complete SDK below that PHPX checkout. There is no additional WASI SDK environment variable and no set of per-library search paths: all headers, archives, and the ABI marker must be installed together so an application cannot accidentally mix incompatible builds.

TypePHP owns complete SDK orchestration. From the compiler repository, build and install the matching PHP and PHPX portions with:

./wasm/build-sdk.sh \
    --prefix "${PHPX_HOME}/wasm/wasm32-wasip2" \
    --jobs 16

The PHP build produces only libphp.a and PHP headers. The PHPX build owns GMP, MPFR, the vendored mpdecimal, libphpx.a, and their headers. The orchestrator validates the combined installation before writing .typephp-wasi-sdk-abi.

Autoconf, Bison, re2c, and the PHP/PHPX source trees are SDK producer dependencies only. They are never searched for by an application build. Library components additionally require the pinned host-side wit-bindgen-cli 0.60.0 in PATH; command components do not use it.

WASM integration checks live in tests/wasm and run through run-tests.php. The target-independent high-precision TypePHP example lives at examples/high-precision.php.

Language-level component exports

A WASI command remains the default and defines main(). A callable component uses library mode and exports explicitly annotated, statically typed functions:

#[WasmExport]
function add(int $left, int $right): int
{
    return $left + $right;
}

#[WasmExport(name: 'greet-user')]
function greetUser(string $name): string
{
    return "Hello, $name";
}

name: calculator
mode: library
wasm: browser
wasm-package: app:calculator@1.0.0
wasm-world: calculator
sources:
  - src

The first ABI version supports bool, int, float, string, nullable versions of those types, and void. PHP int maps to WIT s64 and therefore to JavaScript bigint. Untyped values, arrays, objects, references, variadic or optional parameters, generators, and exported methods are compile-time errors. Every exported call uses a WIT result so PHP exceptions and Zend bailouts are converted before crossing the Canonical ABI boundary.

tpc writes the generated .wit next to its intermediate interface manifest, invokes PHPX's bundled generator, and links a reactor component. Browser mode then uses Jco exactly as command components do. The generated create-runtime() function returns a WIT runtime resource. Creating it starts one NTS PHP request; dropping it runs RSHUTDOWN before the request memory pool is released. Methods on the same resource must remain serialized, and only one runtime resource may be active in a component instance.

Jco exposes the resource as a JavaScript class. Browser code creates one runtime and reuses it for hot calls:

const runtime = await api.createRuntime();
console.log(await runtime.add(20n, 22n));
console.log(await runtime.greetUser('TypePHP'));

// Release deterministically instead of waiting for JavaScript GC.
runtime[Symbol.dispose]();

Top-level WIT result errors are surfaced by Jco as JavaScript exceptions.