[CLI] Load custom PHP.wasm extensions (#3616)

## What it does

Adds Playground CLI support for loading custom PHP.wasm extensions
before PHP
starts:

```bash
wp-playground server \
	--php=8.4 \
	--php-extension=./dist/wp_mysql_parser/manifest.json
```

`--php-extension` is repeatable and accepts a local path, `file:` URL,
or
`http(s):` URL to a PHP extension manifest.

Manifests can now describe both the artifact matrix and startup settings
in one
JSON file:

```json
{
	"name": "spx",
	"version": "0.1.0",
	"artifacts": [
		{
			"phpVersion": "8.4",
			"sourcePath": "spx-php8.4-jspi.so"
		}
	],
	"iniEntries": {
		"spx.http_enabled": "1"
	},
	"env": {
		"SPX_DATA_DIR": "/internal/shared/spx/data"
	}
}
```

## Rationale

The PHP.wasm runtime can load externally built JSPI side modules, and
`@php-wasm/compile-extension` emits manifests for those builds. CLI
users still
had no direct way to pass those manifests through to the Node runtime.

Custom extensions must be declared at startup because PHP reads
extension
`.ini` files while booting. Passing manifests through the existing
runtime
`extensions` array keeps CLI behavior aligned with `loadNodeRuntime()`.

The user-facing format is intentionally one manifest file rather than
separate
manifest and loader-config files. Runtime settings such as `iniEntries`,
`env`,
`loadWithIniDirective`, and `extensionDir` live directly in the
manifest.

## Implementation

- Renames the CLI extension adapter to
`cliExtensionArgsToExtensionsArray()`.
- Combines built-in extension flags (`intl`, `redis`, `memcached`,
`xdebug`)
  with custom `--php-extension=<manifest>` entries.
- Threads the combined `PHPExtension[]` into both Blueprint v1 and v2
CLI
  workers.
- Extends the PHP extension manifest type and generated schema/validator
to
  allow runtime startup settings.
- Applies manifest-declared runtime settings in `resolvePHPExtension()`.
- Documents the single manifest-based CLI path in the CLI and
  `@php-wasm/compile-extension` READMEs.

## Testing instructions

```bash
npm exec -- nx run playground-cli:test-playground-cli --testFiles=tests/php-extensions.spec.ts
npm exec -- nx run php-wasm-universal:test:vite --testFile=load-extension.spec.ts
npm exec -- nx run playground-cli:typecheck
npm exec -- nx run php-wasm-universal:typecheck
npm exec -- nx run playground-cli:lint
npm exec -- nx run php-wasm-universal:lint
npm exec -- nx run php-wasm-compile-extension:typecheck
npm exec -- nx run php-wasm-compile-extension:lint
git diff --check
```

Author: adamziel

packages/php-wasm/compile-extension/README.md

@@ -44,6 +44,27 @@ npx @php-wasm/compile-extension \
 Empty directories are recorded as `type: "directory"` nodes so the loader
 creates them before PHP starts.
 
+If an extension needs startup settings, add them to the manifest:
+
+```json
+{
+	"name": "spx",
+	"version": "0.1.0",
+	"artifacts": [
+		{
+			"phpVersion": "8.4",
+			"sourcePath": "spx-php8.4-jspi.so"
+		}
+	],
+	"iniEntries": {
+		"spx.http_enabled": "1"
+	},
+	"env": {
+		"SPX_DATA_DIR": "/internal/shared/spx/data"
+	}
+}
+```
+
 The supported `--php-versions` are `7.4` and `8.0` through `8.5`.
 
 Docker is required. The CLI lazily fetches the small PHP.wasm Docker asset set
@@ -60,14 +81,14 @@ The package only needs Docker and Node. It does not require a checkout of
 
 - uses: actions/setup-node@v4
   with:
-    node-version: '24'
+      node-version: '24'
 
 - run: |
-    npx --yes @php-wasm/compile-extension \
-      --source ./my-extension \
-      --name my_extension \
-      --php-versions 8.0,8.1,8.2,8.3,8.4,8.5 \
-      --out ./dist/my-extension
+      npx --yes @php-wasm/compile-extension \
+        --source ./my-extension \
+        --name my_extension \
+        --php-versions 8.0,8.1,8.2,8.3,8.4,8.5 \
+        --out ./dist/my-extension
 ```
 
 In a matrix workflow, set `strategy.max-parallel: 1` on the WASM job —

packages/php-wasm/compile-extension/src/manifest.ts

@@ -35,6 +35,20 @@ export interface ExtensionArtifact {
 export interface ExtensionManifest {
 	name: string;
 	version: string;
+	/**
+	 * The first directive of the generated startup `.ini` file. Defaults to
+	 * `extension`; use `zend_extension` for Zend extensions like Xdebug.
+	 */
+	loadWithIniDirective?: 'extension' | 'zend_extension';
+	/** Additional `key=value` lines for the generated startup `.ini` file. */
+	iniEntries?: Record<string, string>;
+	/** Environment variables added before the extension is loaded. */
+	env?: Record<string, string>;
+	/**
+	 * VFS directory where PHP.wasm writes the extension `.so` file and its
+	 * per-extension ini file.
+	 */
+	extensionDir?: string;
 	artifacts: ExtensionArtifact[];
 	/** URL-backed files shared by every artifact in this manifest. */
 	extraFiles?: ExtensionManifestExtraFiles;