[CLI] Support staged PHP.wasm side modules

[adamziel]

What it does

Allows a PHP.wasm extension manifest to stage an artifact before PHP starts without adding a php.ini load directive.

{
  "name": "sqlite_markdown",
  "loadWithIniDirective": false,
  "artifacts": []
}

The extension bytes and sidecar files are still fetched and written into the PHP virtual filesystem, but PHP does not receive an extension= or zend_extension= entry for that artifact.

Rationale

Some Wasm side modules are consumed by another runtime component instead of PHP's extension loader. They need the startup-time fetch/staging path from custom PHP.wasm extensions, but registering them through php.ini makes PHP try to load them as native PHP extensions.

Implementation

Adds PHPExtensionLoadDirective = 'extension' | 'zend_extension' | false and threads it through manifest resolution, @php-wasm/node, and the generated manifest schema.

When loadWithIniDirective is false:

• the .so is staged in extensionDir
• manifest and caller-provided sidecar files are staged normally
• no per-extension .ini file is generated
• withResolvedPHPExtensions() omits that extension from PHP_INI_SCAN_DIR

The @php-wasm/compile-extension manifest type now accepts the same value, so generated extension manifests can use the single manifest object format.

Testing instructions

npm exec -- nx run php-wasm-universal:test:vite --testFile=load-extension.spec.ts
npm exec -- nx run php-wasm-node:test-group-1-jspi --testFiles=with-php-extensions.spec.ts
npm exec -- nx run php-wasm-universal:typecheck
npm exec -- nx run php-wasm-node:typecheck
npm exec -- nx run php-wasm-compile-extension:typecheck
npm exec -- nx run php-wasm-universal:lint
npm exec -- nx run php-wasm-node:lint
npm exec -- nx run php-wasm-compile-extension:lint
git diff --check origin/trunk...HEAD

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds support for staging PHP.wasm side modules without registering them via php.ini, by allowing loadWithIniDirective: false in extension manifests.

Changes:

• Introduces PHPExtensionLoadDirective = PHPExtensionIniDirective | false type and threads it through manifest resolution, install options, and withResolvedPHPExtensions().
• Refactors ini-file generation into createPHPExtensionIniFile() and skips ini generation/PHP_INI_SCAN_DIR entries when the directive is false.
• Updates the generated extension manifest JSON schema/validator and @php-wasm/compile-extension manifest type to accept the new false value.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/playground/cli/README.md	Docs example for loadWithIniDirective: false.
packages/php-wasm/universal/src/lib/load-extension.ts	Adds new type, refactors ini generation, skips ini staging when directive is false.
packages/php-wasm/universal/src/lib/load-extension.spec.ts	Tests for side-module behavior in resolver.
packages/php-wasm/universal/src/lib/index.ts	Exports new PHPExtensionLoadDirective type.
packages/php-wasm/universal/public/php-extension-manifest-schema.json	Schema updated with new directive variant.
packages/php-wasm/universal/public/php-extension-manifest-schema-validator.js	Regenerated validator supporting false.
packages/php-wasm/universal/README.md	Docs updated for new behavior and sourcePath field.
packages/php-wasm/node/src/test/with-php-extensions.spec.ts	Test ensuring no PHP_INI_SCAN_DIR entry is created.
packages/php-wasm/node/README.md	Docs note for loadWithIniDirective: false.
packages/php-wasm/compile-extension/src/manifest.ts	Adds false variant in compile-extension manifest type.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mho22]

LGTM!