Skip to content

[CLI] Load custom PHP.wasm extensions#3616

Merged
adamziel merged 3 commits into
trunkfrom
add-cli-php-extension-loading
May 14, 2026
Merged

[CLI] Load custom PHP.wasm extensions#3616
adamziel merged 3 commits into
trunkfrom
add-cli-php-extension-loading

Conversation

@adamziel
Copy link
Copy Markdown
Collaborator

@adamziel adamziel commented May 11, 2026

What it does

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

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:

{
	"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

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

@adamziel adamziel marked this pull request as ready for review May 14, 2026 13:04
@adamziel adamziel requested review from a team, JanJakes and Copilot May 14, 2026 13:04
@adamziel adamziel merged commit 5c43ef8 into trunk May 14, 2026
54 of 55 checks passed
@adamziel adamziel deleted the add-cli-php-extension-loading branch May 14, 2026 13:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant