[ xdebug ] Add --xdebug option in php-wasm CLI and wp-playground CLI

CHANGELOG.md

@@ -4,44 +4,42 @@ All notable changes to this project are documented in this file by a CI job
 that runs on every NPM release. The file follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 format.
 
-## [v1.2.2] (2025-07-14) 
+## [v1.2.2] (2025-07-14)
 
 ### Enhancements
 
-- Add --internal-cookie-store option for Playground CLI. ([#2323](https://github.com/WordPress/wordpress-playground/pull/2323))
+-   Add --internal-cookie-store option for Playground CLI. ([#2323](https://github.com/WordPress/wordpress-playground/pull/2323))
 
 ### Tools
 
-
 #### PHP WebAssembly
 
-- [ php-wasm ] Add `xdebug` shared extension to @php-wasm/node ASYNCIFY. ([#2326](https://github.com/WordPress/wordpress-playground/pull/2326))
+-   [ php-wasm ] Add `xdebug` shared extension to @php-wasm/node ASYNCIFY. ([#2326](https://github.com/WordPress/wordpress-playground/pull/2326))
 
 ### Documentation
 
-- Add Japanese translations to  Using Blueprints. ([#2330](https://github.com/WordPress/wordpress-playground/pull/2330))
-- Add Japanese translations to Blueprint data Format. ([#2340](https://github.com/WordPress/wordpress-playground/pull/2340))
-- Adding new videos about WordPress Playground. ([#2348](https://github.com/WordPress/wordpress-playground/pull/2348))
-- Translate How to contribute pages to Brazilian Portuguese. ([#2329](https://github.com/WordPress/wordpress-playground/pull/2329))
-- Updating Translation Guide. ([#2342](https://github.com/WordPress/wordpress-playground/pull/2342))
-- Updating slack channel from #meta-playground to #playground. ([#2345](https://github.com/WordPress/wordpress-playground/pull/2345))
+-   Add Japanese translations to Using Blueprints. ([#2330](https://github.com/WordPress/wordpress-playground/pull/2330))
+-   Add Japanese translations to Blueprint data Format. ([#2340](https://github.com/WordPress/wordpress-playground/pull/2340))
+-   Adding new videos about WordPress Playground. ([#2348](https://github.com/WordPress/wordpress-playground/pull/2348))
+-   Translate How to contribute pages to Brazilian Portuguese. ([#2329](https://github.com/WordPress/wordpress-playground/pull/2329))
+-   Updating Translation Guide. ([#2342](https://github.com/WordPress/wordpress-playground/pull/2342))
+-   Updating slack channel from #meta-playground to #playground. ([#2345](https://github.com/WordPress/wordpress-playground/pull/2345))
 
 ### PHP WebAssembly
 
-- Support multiple workers for NODEFS /wordpress mounts – Asyncify. ([#2317](https://github.com/WordPress/wordpress-playground/pull/2317))
-- [PHP] Support non-blocking read streams. ([#2339](https://github.com/WordPress/wordpress-playground/pull/2339))
+-   Support multiple workers for NODEFS /wordpress mounts – Asyncify. ([#2317](https://github.com/WordPress/wordpress-playground/pull/2317))
+-   [PHP] Support non-blocking read streams. ([#2339](https://github.com/WordPress/wordpress-playground/pull/2339))
 
 ### Bug Fixes
 
-- Fix: Set an explicit path for docsaurus.config.js. ([#2335](https://github.com/WordPress/wordpress-playground/pull/2335))
+-   Fix: Set an explicit path for docsaurus.config.js. ([#2335](https://github.com/WordPress/wordpress-playground/pull/2335))
 
 ### Contributors
 
 The following contributors merged PRs in this release:
 
 @adamziel @brandonpayton @fellyph @mho22 @rollybueno @shimotmk
 
-
 ## [v1.0.38] (2025-05-22)
 
 ### Various

packages/docs/site/docs/main/changelog.md

@@ -9,44 +9,42 @@ All notable changes to this project are documented in this file by a CI job
 that runs on every NPM release. The file follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 format.
 
-## [v1.2.2] (2025-07-14) 
+## [v1.2.2] (2025-07-14)
 
 ### Enhancements
 
-- Add --internal-cookie-store option for Playground CLI. ([#2323](https://github.com/WordPress/wordpress-playground/pull/2323))
+-   Add --internal-cookie-store option for Playground CLI. ([#2323](https://github.com/WordPress/wordpress-playground/pull/2323))
 
 ### Tools
 
-
 #### PHP WebAssembly
 
-- [ php-wasm ] Add `xdebug` shared extension to @php-wasm/node ASYNCIFY. ([#2326](https://github.com/WordPress/wordpress-playground/pull/2326))
+-   [ php-wasm ] Add `xdebug` shared extension to @php-wasm/node ASYNCIFY. ([#2326](https://github.com/WordPress/wordpress-playground/pull/2326))
 
 ### Documentation
 
-- Add Japanese translations to  Using Blueprints. ([#2330](https://github.com/WordPress/wordpress-playground/pull/2330))
-- Add Japanese translations to Blueprint data Format. ([#2340](https://github.com/WordPress/wordpress-playground/pull/2340))
-- Adding new videos about WordPress Playground. ([#2348](https://github.com/WordPress/wordpress-playground/pull/2348))
-- Translate How to contribute pages to Brazilian Portuguese. ([#2329](https://github.com/WordPress/wordpress-playground/pull/2329))
-- Updating Translation Guide. ([#2342](https://github.com/WordPress/wordpress-playground/pull/2342))
-- Updating slack channel from #meta-playground to #playground. ([#2345](https://github.com/WordPress/wordpress-playground/pull/2345))
+-   Add Japanese translations to Using Blueprints. ([#2330](https://github.com/WordPress/wordpress-playground/pull/2330))
+-   Add Japanese translations to Blueprint data Format. ([#2340](https://github.com/WordPress/wordpress-playground/pull/2340))
+-   Adding new videos about WordPress Playground. ([#2348](https://github.com/WordPress/wordpress-playground/pull/2348))
+-   Translate How to contribute pages to Brazilian Portuguese. ([#2329](https://github.com/WordPress/wordpress-playground/pull/2329))
+-   Updating Translation Guide. ([#2342](https://github.com/WordPress/wordpress-playground/pull/2342))
+-   Updating slack channel from #meta-playground to #playground. ([#2345](https://github.com/WordPress/wordpress-playground/pull/2345))
 
 ### PHP WebAssembly
 
-- Support multiple workers for NODEFS /wordpress mounts – Asyncify. ([#2317](https://github.com/WordPress/wordpress-playground/pull/2317))
-- [PHP] Support non-blocking read streams. ([#2339](https://github.com/WordPress/wordpress-playground/pull/2339))
+-   Support multiple workers for NODEFS /wordpress mounts – Asyncify. ([#2317](https://github.com/WordPress/wordpress-playground/pull/2317))
+-   [PHP] Support non-blocking read streams. ([#2339](https://github.com/WordPress/wordpress-playground/pull/2339))
 
 ### Bug Fixes
 
-- Fix: Set an explicit path for docsaurus.config.js. ([#2335](https://github.com/WordPress/wordpress-playground/pull/2335))
+-   Fix: Set an explicit path for docsaurus.config.js. ([#2335](https://github.com/WordPress/wordpress-playground/pull/2335))
 
 ### Contributors
 
 The following contributors merged PRs in this release:
 
 @adamziel @brandonpayton @fellyph @mho22 @rollybueno @shimotmk
 
-
 ## [v1.0.38] (2025-05-22)
 
 ### Various

packages/php-wasm/cli/src/main.ts

@@ -38,6 +38,11 @@ async function run() {
 		throw new Error(`Unsupported PHP version ${phpVersion}`);
 	}
 
+	const hasXdebugOption = args.some((arg) => arg.startsWith('--xdebug'));
+	if (hasXdebugOption) {
+		args = args.filter((arg) => arg !== '--xdebug');
+	}
+
 	// npm scripts set the TMPDIR env variable
 	// PHP accepts a TMPDIR env variable and expects it to
 	// be a writable directory within the PHP filesystem.
@@ -86,6 +91,7 @@ ${process.argv[0]} ${process.execArgv.join(' ')} ${process.argv[1]}
 					PATH: `${tempDir}:${envVariables['PATH']}`,
 				},
 			},
+			withXdebug: hasXdebugOption,
 		})
 	);
 

packages/php-wasm/cli/vite.config.ts

@@ -27,6 +27,7 @@ export default defineConfig({
 				'util',
 				'dns',
 				'ws',
+				'os',
 			],
 			input: 'packages/php-wasm/cli/src/main.ts',
 			output: {
@@ -45,4 +46,8 @@ export default defineConfig({
 		include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
 		reporters: ['default'],
 	},
+
+	define: {
+		'process.env': 'process.env',
+	},
 });

packages/php-wasm/compile/php/Dockerfile

@@ -745,6 +745,7 @@ RUN export ASYNCIFY_IMPORTS=$'[\n\
 "Curl_is_connected",\
 "curl_multi_perform",\
 "curl_multi_poll",\
+"curl_multi_wait",\
 "Curl_multi_wait",\
 "Curl_ossl_connect_nonblocking",\
 "Curl_ossl_seed",\
@@ -966,6 +967,7 @@ RUN export ASYNCIFY_IMPORTS=$'[\n\
 "wasm_php_exec",\
 "wasm_sapi_handle_request",\
 "wasm_sapi_request_shutdown",\
+"execute_internal",\
 "_call_user_function_ex",\
 "_call_user_function_impl",\
 "_mysqlnd_run_command",\
@@ -1627,6 +1629,7 @@ RUN export ASYNCIFY_IMPORTS=$'[\n\
 "ZEND_DO_ICALL_SPEC_HANDLER",\
 "ZEND_DO_ICALL_SPEC_RETVAL_UNUSED_HANDLER",\
 "ZEND_DO_ICALL_SPEC_RETVAL_USED_HANDLER",\
+"ZEND_DO_ICALL_SPEC_OBSERVER_HANDLER",\
 "ZEND_DO_UCALL_SPEC_OBSERVER_HANDLER",\
 "zend_emit_op_tmp",\
 "zend_emit_op",\
@@ -1682,6 +1685,7 @@ RUN export ASYNCIFY_IMPORTS=$'[\n\
 "zend_hash_graceful_reverse_destroy",\
 "zend_hash_reverse_apply",\
 "ZEND_INCLUDE_OR_EVAL_SPEC_CV_HANDLER",\
+"ZEND_INCLUDE_OR_EVAL_SPEC_OBSERVER_HANDLER",\
 "zend_include_or_eval",\
 "compile_filename",\
 "zend_internal_type_error",\
@@ -1824,6 +1828,9 @@ RUN export ASYNCIFY_IMPORTS=$'[\n\
 "zend_use_undef_in_read_context_helper_SPEC",\
 "zend_user_it_get_current_data",\
 "zend_user_it_get_new_iterator",\
+"ZEND_USER_OPCODE_SPEC_HANDLER",\
+"ZEND_INCLUDE_OR_EVAL_SPEC_CONST_HANDLER",\
+"ZEND_INCLUDE_OR_EVAL_SPEC_TMPVAR_HANDLER",\
 "zend_value_error",\
 "zend_verify_ref_array_assignable",\
 "zend_vm_stack_extend",\

packages/php-wasm/compile/xdebug/Dockerfile

@@ -130,7 +130,9 @@ RUN set -euxo pipefail; \
 	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"; \
+		# execute_internal must be in ASYNCIFY_IMPORTS for Xdebug to trace internal PHP functions.
+		# This enables async unwinding during breakpoints or stepping inside internal calls.
+		export EMCC_FLAGS="${EMCC_FLAGS} -sASYNCIFY -sASYNCIFY_ADVISE -sASYNCIFY_IMPORTS=wasm_recv,execute_internal -sASYNCIFY_EXPORTS=wasm_recv"; \
 	fi; \
 
 	emmake make -j1