Debug Php Wasm Main Module

Debugging PHP.wasm Main Module

Patterns for diagnosing and fixing crashes in the main PHP.wasm binary — Asyncify unwind/rewind failures, JSPI suspension errors, memory growth bugs, and runtime WASM traps.

Error Message Interpretation

Asyncify errors

Secondary errors (undefined variable, corrupted state) after any of these are red herrings caused by the corrupted Asyncify rewind.

JSPI errors

Same root cause, different errors across PHP versions

A single missing ASYNCIFY_ONLY function produces different WASM error types depending on the PHP version:

• PHP 5.6: table index is out of bounds
• PHP 7.0: null function or function signature mismatch
• PHP 7.2/8.2: memory access out of bounds
• PHP 7.4/8.0/8.1: unreachable or memory access out of bounds

Each PHP version compiles to different WASM code for the same opcode handler. Don't assume different error messages mean different bugs — always check the function at the top of the WASM stack trace.

Asyncify Crash Debugging Strategy

Step-by-step process

1. Run the test with --stack-trace-limit=200 (default 10 is too shallow for Asyncify crashes)
2. Identify the async trigger in the stack trace (e.g. _emscripten_sleep, _wasm_recv)
3. Work backwards through the call chain from the trigger
4. Start with the opcode handler — it's usually the critical missing function. Adding deeper utility functions first won't help if the opcode handler isn't instrumented.
5. Add one function at a time to ASYNCIFY_ONLY. Recompile and re-test after each addition. This reveals which function was actually needed and whether deeper functions are now exposed.
6. Repeat until the crash is fixed or a new crash surfaces (often deeper in the stack — fixing one crash reveals the next)

What needs ASYNCIFY_ONLY

Every function on the call stack at the moment of the async call needs Asyncify instrumentation. This includes:

• Opcode handlers (ZEND_*_SPEC_*_HANDLER) — always check these first
• Bridge functions between the opcode and the async call (e.g. zend_user_it_get_new_iterator for iterator creation)
• Cleanup functions that run in the same scope before the suspension point (var_destroy, _efree_large, php_var_unserialize_destroy) — these are NOT just post-crash artifacts

What does NOT need ASYNCIFY_ONLY

• Functions that run after the async operation returns
• Error formatting functions (xbuf_format_converter, php_printf_to_smart_str) that appear because the failed rewind triggered zend_error — these are red herrings

Common function categories to instrument

Iterator operations (spread, foreach, array unpack):

• ZEND_ADD_ARRAY_UNPACK_SPEC_HANDLER, ZEND_FE_FETCH_R_SPEC_VAR_HANDLER
• zend_user_it_get_new_iterator, zend_user_it_move_forward

Stream operations:

• _php_stream_make_seekable, _php_stream_copy_to_stream_ex
• _php_stream_flush, _php_stream_cast, zif_stream_select

Object operations:

• zend_std_write_property, zend_std_cast_object_tostring
• zend_objects_clone_obj, zend_objects_clone_members

Error/exception handling:

• zend_error, zend_error_zstr, zend_throw_exception
• zend_undefined_index

Serialization:

• zif_serialize, zif_unserialize, php_var_unserialize_destroy

JSPI Debugging

Vitest must have --experimental-wasm-jspi

Node.js requires this flag for JSPI. Without it, wasm-feature-detect's jspi() returns false and getPHPLoaderModule silently loads the asyncify build. All JSPI bugs become invisible.

Add to vite.config.ts:

poolOptions: {
    forks: {
        execArgv: ['--expose-gc', '--experimental-wasm-jspi'],
    },
},

Always verify which build is loaded by adding a console.log to the JS glue file.

Gate JSPI vs Asyncify paths

Use wasm-feature-detect's jspi() function to branch between JSPI (dynamic extensions) and Asyncify (static extensions) code paths — both in runtime loading and in test files.

Synchronous JS imports must NOT be marked async

When a WASM JS import has isAsync = true, JSPI wraps it with WebAssembly.Suspending. Even if the implementation never suspends (returns a value, not a Promise), the wrapper corrupts the WASM call stack — V8's native stack bookkeeping desynchronizes __stack_pointer, causing heap corruption that manifests later as zend_mm_panic in _efree.

Symptoms: crash only during PHP startup (php_module_startup), heap corruption in unrelated code (zend_hash_destroy, zend_file_handle_dtor).

Debugging strategy: neuter the JS import (return 0 immediately). If the crash persists, the problem is the JSPI wrapping, not the import's implementation. Check functionName.isAsync in the compiled JS glue. Fix by setting functionName__async: false in the Emscripten JS library.

Check JSPI wrapping in compiled glue

Search the compiled JS glue for:

• instrumentWasmImports → importPattern regex (imports wrapped with WebAssembly.Suspending)
• instrumentWasmExports → exportPattern regex (exports wrapped with WebAssembly.promising)

A function in the import pattern that shouldn't suspend causes heap corruption. A function that needs to suspend but isn't in the pattern returns immediately instead of waiting.

PHP Startup Lifecycle in WASM

loadNodeRuntime() / loadWebRuntime()  →  WASM module loads, FS ready
new PHP(runtime)                      →  initializeRuntime(), writes default php.ini
php.run()                             →  php_wasm_init() → php_module_startup()
                                         → parses ini, initializes modules

Crashes only during step 3 (startup) but not at runtime point to WASM-JS boundary issues (JSPI wrapping, calling conventions) rather than PHP logic bugs.