[compile-extension] Emit the new PHPExtensionManifest shape, add --extra-files

[adamziel]

What it does

Updates @php-wasm/compile-extension to emit manifests in the shape the loader merged in #3580 expects, and adds a --extra-files <hostDir>:<vfsRoot> CLI flag for staging sidecar assets (web UIs, data dirs, etc.) alongside the .so files.

The package's manifest output now matches PHPExtensionManifest from @php-wasm/universal exactly:

• artifacts[i].file → artifacts[i].sourcePath
• sha256 removed (the loader dropped verification in [PHP] Support extraFiles for custom PHP extensions #3580)
• extraFiles with vfsRoot + nodes is supported at both the top-level and per-artifact

Why

The loader merged in #3580 validates manifests against a strict schema generated from PHPExtensionManifest, and rejects the old shape. Without this update, anything built with the published 3.1.25 fails at runtime with "Invalid PHP extension manifest". This is the prerequisite for stacking an SPX build PR that uses @php-wasm/compile-extension to produce the .so and the new manifest API to stage SPX's web UI files.

How to use --extra-files

npx @php-wasm/compile-extension \
  --source ./spx-src \
  --name spx \
  --php-versions 8.2 \
  --extra-files ./web-ui:/internal/shared/spx \
  --out ./dist

./web-ui is copied next to the manifest. Each file becomes one node under extraFiles.nodes with vfsPath relative to vfsRoot and sourcePath relative to the manifest URL. Empty directories are recorded as type: "directory" nodes so the loader creates them before PHP starts.

Multiple --extra-files entries are allowed; they must agree on vfsRoot because the manifest format stores a single root per group.

Testing instructions

npm exec nx -- test php-wasm-compile-extension
npm exec nx -- typecheck php-wasm-compile-extension
npm exec nx -- lint php-wasm-compile-extension

The existing integration suite (tests/run-integration-tests.sh) keeps working because the loader-side tests already pass manifestUrl straight through and use the new manifest shape.

[Copilot]

Pull request overview

Note

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

Updates @php-wasm/compile-extension to emit a loader-compatible PHPExtensionManifest shape and adds support for staging sidecar assets via a new --extra-files <hostDir>:<vfsRoot> CLI flag.

Changes:

• Update manifest schema: file → sourcePath, remove sha256, add extraFiles at manifest/artifact level.
• Add extra-files staging implementation + tests (copy into outDir, emit extraFiles.nodes, record empty dirs).
• Wire the new flag into the CLI, and document the new manifest shape and flag usage.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/php-wasm/compile-extension/src/manifest.ts	Adjusts manifest types/output to match PHPExtensionManifest and adds extraFiles support.
packages/php-wasm/compile-extension/src/manifest.spec.ts	Updates artifact assertions and adds coverage for createManifest output + extraFiles.
packages/php-wasm/compile-extension/src/extra-files.ts	Implements --extra-files parsing and staging into outDir with manifest node generation.
packages/php-wasm/compile-extension/src/extra-files.spec.ts	Adds tests for parsing and staging behavior, including empty directories and mixed roots.
packages/php-wasm/compile-extension/src/compile.ts	Plumbs extraFiles through compile options into the written manifest.
packages/php-wasm/compile-extension/src/cli.ts	Adds --extra-files flag, stages assets, and passes extraFiles into compilation.
packages/php-wasm/compile-extension/README.md	Documents the new manifest schema and --extra-files usage.

---

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