[PHP] Add php-wasm extension compile helper

[adamziel]

What it does

Adds @php-wasm/compile-extension, a Docker-backed CLI for compiling phpize extension source into PHP.wasm side modules across a PHP version x async mode matrix.

npx @php-wasm/compile-extension \
  --source ./ext-src \
  --name wp_mysql_parser \
  --php-versions 8.1,8.2,8.3,8.4 \
  --async-modes jspi,asyncify \
  --out ./dist

It writes artifacts like wp_mysql_parser-php8.3-jspi.so plus manifest.json, and adds loadExtension({ manifestUrl }) in @php-wasm/universal to pick, fetch, verify, install, and register the matching artifact at runtime.

The README now also documents dependency-backed extensions: Playground-built libraries, vendored non-Playground libraries, CMake dependencies, and plain Makefile dependencies.

Rationale

Extension authors currently have to rediscover the right phpize, Emscripten side-module, JSPI, and Asyncify flags. The CLI gives them one command and one publishable dist/ directory.

Dependencies are the sharp edge: a PHP.wasm side module can only link WebAssembly objects built with the same Emscripten toolchain and async mode. The docs call out that native host libraries from /usr/lib, Homebrew, apt, or npm packages cannot be linked into the .so.

Implementation

Adds packages/php-wasm/compile-extension with CLI parsing, matrix orchestration, Docker image selection, manifest writing with SHA-256 hashes, and config.m4 extension-name detection.

The canonical container recipe runs:

phpize
emconfigure ./configure --enable-<name>
emmake make

Side modules are built with -sSIDE_MODULE=1, -sWASM_BIGINT, -fPIC, -O2, and the matching async flags for jspi or asyncify.

Dependency archives passed through --extra-ldflags are kept out of configure-time LDFLAGS, then force-linked into the final side module with --whole-archive. That lets extensions link WebAssembly .a files without breaking Autoconf compiler smoke tests.

The README includes the author workflow for CMake dependencies:

emcmake cmake \
  -S vendor/libfoo \
  -B vendor/libfoo/build \
  -DCMAKE_INSTALL_PREFIX="$PWD/vendor/libfoo/install" \
  -DBUILD_SHARED_LIBS=OFF
emmake cmake --build vendor/libfoo/build --target install

npx @php-wasm/compile-extension \
  --source . \
  --name my_extension \
  --extra-cflags "-I/build/vendor/libfoo/install/include" \
  --extra-ldflags "/build/vendor/libfoo/install/lib/libfoo.a"

For plain Makefile dependencies, the docs show the same pattern using emmake make, CC=emcc, CXX=em++, AR=emar, and RANLIB=emranlib. The final PHP extension still needs phpize/config.m4; CMake/Make output is treated as dependency code in v1.

loadExtension() fetches manifest.json, matches { phpVersion, asyncMode }, fetches the selected .so, verifies sha256 when present, writes the extension and .ini, and updates PHP_INI_SCAN_DIR.

Testing instructions

Run the focused package checks:

npx nx test php-wasm-compile-extension
npx nx typecheck php-wasm-compile-extension
npx nx lint php-wasm-compile-extension
npx nx build php-wasm-compile-extension

Run the Docker integration test:

npx nx test-compile-extension-integration php-wasm-compile-extension

The integration test builds and loads:

• a minimal playground_hello extension
• php-src ext/calendar
• a zlib_probe extension linked against Playground-built libz
• external_lib_probe, linked against a vendored non-Playground string-score archive

[adamziel]

Superseded by #3566, which consolidates the extension loader, Blueprint API, compile helper, and bundled extension migration into one trunk-based PR.