[ php-wasm ] Add xdebug shared extension to @php-wasm/node ASYNCIFY (#2326)

## Motivation for the change

This is a pull request to dynamically load Xdebug in `@php-wasm` Node
ASYNCIFY.

[Roadmap](#2315)

## Related issues and pull requests

Relative to XDebug

- #2248
- #314
- #2288
- #831

Relative to dynamic library

- #89
- #2290
- #673

## Implementation details

Additional steps for asyncify are implemented : 

- new nx commands
- new `WITH_JSPI` and `WITH_DEBUG` arguments in Xdebug Dockerfile
- new `xdebug.so` files are compiled and dynamically loaded

## Zend extensions and PHP versions
> [!IMPORTANT]  
> Each version of PHP requires its own version of Xdebug because each
version of PHP has a specific Zend Engine API version. Consequently,
each version of Xdebug is designed to be compatible with a particular
Zend Engine API version.

Example using PHP `8.2` with Xdebug `8.3` :

```
Xdebug requires Zend Engine API version 420230831.
The Zend Engine API version 420220829 which is installed, is outdated.
 ```


## Testing Instructions

Two files are needed. A PHP file to test the step debugger. A JS file to run PHP 8.4 node ASYNCIFY.

`php/xdebug.php`

```php
<?php

$test = 42; // Set a breakpoint on this line

echo "Hello Xdebug World\n";
```


`scripts/node.js`

```javascript
import { PHP } from '@php-wasm/universal';
import { loadNodeRuntime } from '@php-wasm/node';


const php = new PHP( await loadNodeRuntime( '8.4', { withXdebug : true }
) );

await php.runStream( { scriptPath : `php/xdebug.php` } );
```


To achieve the test, you first need to start debugging [ with F5 or Run > Start debugging in VSCode ], then run :

```bash
node scripts/node.js
```

Author: mho22

packages/meta/src/node-es-module-loader/loader.mts

@@ -171,10 +171,10 @@ export async function load(
 		urlObj.search = '';
 		return {
 			format: 'module',
-			source: `export default ${JSON.stringify(urlObj.href)};`,
-			// TODO: Consider which is preferable and discuss with @adamziel.
-			// He implemented the pathname version.
-			//source: `export default ${JSON.stringify(urlObj.pathname)};`,
+			source: `export default ${JSON.stringify(urlObj.pathname)};`,
+			// As mentioned in
+			// https://github.com/WordPress/wordpress-playground/pull/2318
+			// using pathname is preferred over href.
 			shortCircuit: true,
 		};
 	}

packages/php-wasm/compile/php/Dockerfile

@@ -1644,6 +1644,8 @@ RUN export ASYNCIFY_IMPORTS=$'[\n\
 "zend_execute_script",\
 "zend_execute_scripts",\
 "zend_execute",\
+"zend_extension_statement_handler",\
+"ZEND_EXT_STMT_SPEC_HANDLER",\
 "ZEND_FE_FETCH_R_SPEC_VAR_HANDLER",\
 "zend_fe_reset_iterator",\
 "ZEND_FE_RESET_R_SPEC_VAR_HANDLER",\
@@ -1724,6 +1726,8 @@ RUN export ASYNCIFY_IMPORTS=$'[\n\
 "zend_objects_store_del_ref",\
 "zend_objects_store_del",\
 "zend_objects_store_free_object_storage",\
+"zend_observer_fcall_begin_prechecked",\
+"zend_observer_fcall_begin",\
 "zend_observer_fcall_end",\
 "zend_parse_arg_number_or_str_slow",\
 "zend_parse_arg_str_weak",\

packages/php-wasm/compile/php/php7.3.patch

@@ -68,13 +68,16 @@ diff --git a/php-src/main/streams/cast.c b/php-src/main/streams/cast.c
 
 
 diff --git a/php-src/Zend/zend_variables.c b/php-src/Zend/zend_variables.c
-index c2594274dd4..42fbacf8c6e 100644
+index c2594274dd4..2c3a01ece57 100644
 --- a/php-src/Zend/zend_variables.c
 +++ b/php-src/Zend/zend_variables.c
-@@ -44,6 +44,13 @@ static void ZEND_FASTCALL zend_ast_ref_destroy_wrapper(zend_ast_ref *ast);
+@@ -44,6 +44,16 @@ static void ZEND_FASTCALL zend_ast_ref_destroy_wrapper(zend_ast_ref *ast);
 
  typedef void (ZEND_FASTCALL *zend_rc_dtor_func_t)(zend_refcounted *p);
 
++// Note: zend_list_free_wrapper function is required because active streams
++// would otherwise cause a function signature mismatch. zend_list_free
++// returns an int, while zend_rc_dtor_func_t expects a void return type.
 +static void zend_list_free_wrapper(zend_refcounted *p) {
 +	zend_resource *res = (zend_resource*)p;
 +	zval zv;
@@ -85,12 +88,12 @@ index c2594274dd4..42fbacf8c6e 100644
  static const zend_rc_dtor_func_t zend_rc_dtor_func[] = {
  	/* IS_UNDEF        */ (zend_rc_dtor_func_t)zend_empty_destroy,
  	/* IS_NULL         */ (zend_rc_dtor_func_t)zend_empty_destroy,
-@@ -54,7 +61,9 @@ static const zend_rc_dtor_func_t zend_rc_dtor_func[] = {
+@@ -54,7 +64,9 @@ static const zend_rc_dtor_func_t zend_rc_dtor_func[] = {
  	/* IS_STRING       */ (zend_rc_dtor_func_t)zend_string_destroy,
  	/* IS_ARRAY        */ (zend_rc_dtor_func_t)zend_array_destroy_wrapper,
  	/* IS_OBJECT       */ (zend_rc_dtor_func_t)zend_object_destroy_wrapper,
 -	/* IS_RESOURCE     */ (zend_rc_dtor_func_t)zend_resource_destroy_wrapper,
-+	// Info: zend_resource_destroy_wrapper is an alias for zend_list_free
++	// Note: zend_resource_destroy_wrapper is an alias for zend_list_free
 +	// https://github.com/php/php-src/blob/PHP-7.3.33/Zend/zend_variables.c#L41
 +	/* IS_RESOURCE     */ zend_list_free_wrapper,
  	/* IS_REFERENCE    */ (zend_rc_dtor_func_t)zend_reference_destroy,

packages/php-wasm/compile/php/php7.4.patch

@@ -61,24 +61,27 @@ diff --git a/php-src/ext/standard/file.c b/php-src/ext/standard/file.c
 
 
 diff --git a/php-src/Zend/zend_variables.c b/php-src/Zend/zend_variables.c
-index 810866a1be2..fdd1c80fea5 100644
+index 810866a1be2..0cc2a95dcf2 100644
 --- a/php-src/Zend/zend_variables.c
 +++ b/php-src/Zend/zend_variables.c
-@@ -36,6 +36,13 @@ static void ZEND_FASTCALL zend_empty_destroy(zend_reference *ref);
+@@ -36,6 +36,16 @@ static void ZEND_FASTCALL zend_empty_destroy(zend_reference *ref);
 
  typedef void (ZEND_FASTCALL *zend_rc_dtor_func_t)(zend_refcounted *p);
 
++// Note: zend_list_free_wrapper function is required because active streams
++// would otherwise cause a function signature mismatch. zend_list_free
++// returns an int, while zend_rc_dtor_func_t expects a void return type.
 +static void zend_list_free_wrapper(zend_refcounted *p) {
-+    zend_resource *res = (zend_resource*)p;
-+    zval zv;
-+    ZVAL_RES(&zv, res);
-+    zend_list_free(&zv);
++	zend_resource *res = (zend_resource*)p;
++	zval zv;
++	ZVAL_RES(&zv, res);
++	zend_list_free(&zv);
 +}
 +
  static const zend_rc_dtor_func_t zend_rc_dtor_func[] = {
  	/* IS_UNDEF        */ (zend_rc_dtor_func_t)zend_empty_destroy,
  	/* IS_NULL         */ (zend_rc_dtor_func_t)zend_empty_destroy,
-@@ -46,7 +53,7 @@ static const zend_rc_dtor_func_t zend_rc_dtor_func[] = {
+@@ -46,7 +56,7 @@ static const zend_rc_dtor_func_t zend_rc_dtor_func[] = {
  	/* IS_STRING       */ (zend_rc_dtor_func_t)zend_string_destroy,
  	/* IS_ARRAY        */ (zend_rc_dtor_func_t)zend_array_destroy,
  	/* IS_OBJECT       */ (zend_rc_dtor_func_t)zend_objects_store_del,

packages/php-wasm/compile/project.json

@@ -9,27 +9,52 @@
 				"parallel": false
 			}
 		},
-		"xdebug": {
+		"xdebug:asyncify": {
 			"executor": "nx:run-commands",
 			"options": {
 				"commands": [
-					"node packages/php-wasm/compile/xdebug/build.js --output-dir=packages/php-wasm/node/jspi"
+					"node packages/php-wasm/compile/xdebug/build.js --output-dir=packages/php-wasm/node/asyncify"
 				],
 				"parallel": false
 			}
 		},
-		"xdebug:all": {
+		"xdebug:asyncify:all": {
 			"executor": "nx:run-commands",
 			"options": {
 				"commands": [
-					"nx run php-wasm-compile:xdebug --PHP_VERSION=8.4",
-					"nx run php-wasm-compile:xdebug --PHP_VERSION=8.3",
-					"nx run php-wasm-compile:xdebug --PHP_VERSION=8.2",
-					"nx run php-wasm-compile:xdebug --PHP_VERSION=8.1",
-					"nx run php-wasm-compile:xdebug --PHP_VERSION=8.0",
-					"nx run php-wasm-compile:xdebug --PHP_VERSION=7.4",
-					"nx run php-wasm-compile:xdebug --PHP_VERSION=7.3",
-					"nx run php-wasm-compile:xdebug --PHP_VERSION=7.2"
+					"nx run php-wasm-compile:xdebug:asyncify --PHP_VERSION=8.4",
+					"nx run php-wasm-compile:xdebug:asyncify --PHP_VERSION=8.3",
+					"nx run php-wasm-compile:xdebug:asyncify --PHP_VERSION=8.2",
+					"nx run php-wasm-compile:xdebug:asyncify --PHP_VERSION=8.1",
+					"nx run php-wasm-compile:xdebug:asyncify --PHP_VERSION=8.0",
+					"nx run php-wasm-compile:xdebug:asyncify --PHP_VERSION=7.4",
+					"nx run php-wasm-compile:xdebug:asyncify --PHP_VERSION=7.3",
+					"nx run php-wasm-compile:xdebug:asyncify --PHP_VERSION=7.2"
+				],
+				"parallel": false
+			}
+		},
+		"xdebug:jspi": {
+			"executor": "nx:run-commands",
+			"options": {
+				"commands": [
+					"node packages/php-wasm/compile/xdebug/build.js --output-dir=packages/php-wasm/node/jspi --WITH_JSPI=yes"
+				],
+				"parallel": false
+			}
+		},
+		"xdebug:jspi:all": {
+			"executor": "nx:run-commands",
+			"options": {
+				"commands": [
+					"nx run php-wasm-compile:xdebug:jspi --PHP_VERSION=8.4",
+					"nx run php-wasm-compile:xdebug:jspi --PHP_VERSION=8.3",
+					"nx run php-wasm-compile:xdebug:jspi --PHP_VERSION=8.2",
+					"nx run php-wasm-compile:xdebug:jspi --PHP_VERSION=8.1",
+					"nx run php-wasm-compile:xdebug:jspi --PHP_VERSION=8.0",
+					"nx run php-wasm-compile:xdebug:jspi --PHP_VERSION=7.4",
+					"nx run php-wasm-compile:xdebug:jspi --PHP_VERSION=7.3",
+					"nx run php-wasm-compile:xdebug:jspi --PHP_VERSION=7.2"
 				],
 				"parallel": false
 			}

packages/php-wasm/compile/xdebug/Dockerfile

@@ -6,6 +6,10 @@ FROM playground-php-wasm:base
 # compatible with a particular Zend Engine API version.
 ARG PHP_VERSION
 
+ARG WITH_JSPI
+
+ARG WITH_DEBUG
+
 # Install Bison, required to build PHP
 RUN mkdir -p /libs
 COPY ./bison2.7/dist/ /libs/bison2.7
@@ -115,8 +119,18 @@ RUN set -euxo pipefail; \
 	# with the main module.
 	/root/replace.sh 's/^(XDEBUG_SHARED_LIBADD\s*=.*\s*)-lm\b/$1/' Makefile; \
 
-	export EMCC_FLAGS="-sSIDE_MODULE -D__x86_64__ -sWASM_BIGINT -Dsetsockopt=wasm_setsockopt -Drecv=wasm_recv -O3"; \
+	export EMCC_FLAGS="-sSIDE_MODULE -D__x86_64__ -sWASM_BIGINT -Dsetsockopt=wasm_setsockopt -Drecv=wasm_recv"; \
 
-	export EMCC_FLAGS="${EMCC_FLAGS} -sJSPI -sJSPI_IMPORTS=wasm_recv -sJSPI_EXPORTS=wasm_recv"; \
+	if [ "$WITH_DEBUG" = "yes" ]; then \
+		export EMCC_FLAGS="${EMCC_FLAGS} -O0 -g3"; \
+	else \
+		export EMCC_FLAGS="${EMCC_FLAGS} -O3"; \
+	fi; \
+
+	if [ "$WITH_JSPI" = "yes" ]; then \
+		export EMCC_FLAGS="${EMCC_FLAGS} -sJSPI -sJSPI_IMPORTS=wasm_recv -sJSPI_EXPORTS=wasm_recv"; \
+	else \
+		export EMCC_FLAGS="${EMCC_FLAGS} -sASYNCIFY -sASYNCIFY_ADVISE -sASYNCIFY_IMPORTS=wasm_recv -sASYNCIFY_EXPORTS=wasm_recv"; \
+	fi; \
 
 	emmake make -j1

packages/php-wasm/compile/xdebug/build.js

@@ -17,13 +17,25 @@ const argParser = yargs(process.argv.slice(2))
 			description: 'The output directory',
 			required: true,
 		},
+		WITH_DEBUG: {
+			type: 'string',
+			choices: ['yes', 'no'],
+			description: 'Build with DWARF debug information.',
+		},
+		WITH_JSPI: {
+			type: 'boolean',
+			default: false,
+			description: 'Build with JSPI support',
+		},
 	});
 
 const args = argParser.argv;
 
 const platformDefaults = {
 	all: {
 		PHP_VERSION: '8.0.24',
+		WITH_DEBUG: 'no',
+		WITH_JSPI: 'no',
 	},
 };
 
@@ -68,6 +80,10 @@ await asyncSpawn(
 		'--progress=plain',
 		'--build-arg',
 		getArg('PHP_VERSION'),
+		'--build-arg',
+		getArg('WITH_DEBUG'),
+		'--build-arg',
+		getArg('WITH_JSPI'),
 	],
 	{ cwd: path.dirname(sourceDir), stdio: 'inherit' }
 );