Debug Php Wasm Side Modules

Debugging PHP.wasm Side Modules

Patterns for diagnosing and fixing issues with dynamic PHP extensions built as WASM side modules and loaded via dlopen.

_dlopen_js Must Be Synchronous

Emscripten marks _dlopen_js as async by default (isAsync = true). With JSPI, this wraps the import with WebAssembly.Suspending. Even when the implementation returns a plain value (not a Promise), the JSPI wrapper corrupts the WASM call stack — V8's native stack bookkeeping desynchronizes __stack_pointer in linear memory, causing heap corruption that manifests later as zend_mm_panic in _efree.

Fix: Set _dlopen_js__async: false in the Emscripten JS library (phpwasm-emscripten-library-dynamic-linking.js).

Symptoms: zend_extension= in php.ini crashes PHP on ANY subsequent code. dl() at runtime works fine. Neutering _dlopen_js to return 0 still crashes — the corruption is in the JSPI wrapping, not the function's implementation.

Side Module JSPI Suspension Pattern

Side modules import functions from the main module. When a side module calls a blocking C function (e.g. recv), the call resolves to the main module's compiled WASM implementation — NOT a JS import, so it cannot be wrapped with WebAssembly.Suspending. The call returns immediately (EAGAIN) instead of waiting for data.

The general fix has three parts:

1. JS wrapper in phpwasm-emscripten-library.js:

   wasm_recv: function(sockfd, buf, len, flags) {
       // Try synchronous recv; if EAGAIN, return Promise
   },
   wasm_recv__async: true,

2. JSPI_IMPORTS — add wasm_recv to the Dockerfile so the main module imports it from JS.

3. Preprocessor redirect — compile the side module with -Drecv=wasm_recv so C recv() calls become wasm_recv(), resolving to the JS import instead of the main module's WASM function.

This pattern applies to ANY blocking C function a side module needs to suspend on: recv, select, sleep, read, connect, etc.

Extension Loading Lifecycle

Files (.so binary, ini config) must be written at a specific point:

loadNodeRuntime()  →  WASM loads, FS ready
new PHP(runtime)   →  initializeRuntime(), writes default php.ini
                      *** WRITE FILES HERE ***
php.run()          →  php_wasm_init() → php_module_startup() → reads ini

Two traps:

• loadNodeRuntime overwrites onRuntimeInitialized — it spreads user options then sets its own callback AFTER the spread. Files written in a user-provided callback are silently lost. No error, the extension just never loads.
• preRun fires before initRuntime() / FS init. Writing files there crashes.

Use php.writeFile() / php.readFileAsText() after new PHP(runtime).

Asyncify + SIDE_MODULE: ASYNCIFY_IMPORTS Is Required

When compiling a side module with -sASYNCIFY and the module uses custom renamed imports (e.g. -Drecv=wasm_recv), you MUST pass -sASYNCIFY_IMPORTS=<custom_name>.

Binaryen's Asyncify pass only knows about its default async imports (emscripten_sleep, etc.). Custom import names are unknown to it. Without -sASYNCIFY_IMPORTS, Binaryen won't instrument the call sites — no save/restore of locals around the call.

export EMCC_FLAGS="-sSIDE_MODULE -sASYNCIFY -sASYNCIFY_IMPORTS=wasm_recv"

Symptom: table index is out of bounds during Asyncify rewind (not unwind) at a side module offset that doesn't appear in the original stack trace. Corrupt locals used as call_indirect table indices.

Do NOT add ASYNCIFY_EXPORTS for imported functions — that flag is for functions the module exports.

Verifying instrumentation

Disassemble the .so before and after adding ASYNCIFY_IMPORTS:

wasm-opt --print module.so | grep -c '__asyncify_state'

A correctly instrumented module has significantly more __asyncify_state checks than an uninstrumented one.

Asyncify Shared Globals

Side modules need to import __asyncify_state and __asyncify_data as shared globals from the main module. The main module provides them as WebAssembly.Global objects. Verify with:

WebAssembly.Module.imports(mod)
    .filter(i => i.name.includes('asyncify'))

If these imports are missing, the side module's Asyncify instrumentation has no shared state with the main module — unwind/rewind will silently malfunction.

JSPI + C++ Side Modules: Weak Symbol Crashes

C++ libraries may call syscalls like close() during internal operations (e.g. after memory-mapping data files). When a side module makes such a call, it can trigger JSPI suspension. This fails with SuspendError: trying to suspend JS frames because C++ weak symbol env imports are resolved through JS closure stubs in the dynamic linker, and those JS frames block JSPI suspension.

Root cause

When a side module imports C++ weak symbols (templates, inline functions, virtual destructors) NOT present in the main module, Emscripten's dynamic linker creates JS closure stubs that resolve lazily. Any JSPI suspension in a call chain that includes these stubs fails.