[PHP] Support extraFiles for custom PHP extensions

[adamziel]

What it does

Adds manifest-declared sidecar files to the PHP extension loading API introduced in #3566, and folds in #3590's generated AJV validator for extension manifests.

A manifest can now describe files and directories that must be staged before PHP starts, alongside the selected .so artifact. Each node's final VFS path is vfsRoot + vfsPath:

{
  "name": "spx",
  "artifacts": [
    {
      "phpVersion": "8.4",
      "sourcePath": "spx.so",
      "extraFiles": {
        "vfsRoot": "/internal/shared/spx",
        "nodes": [
          { "vfsPath": "data", "type": "directory" },
          { "vfsPath": "ui/index.html", "sourcePath": "ui/index.html" }
        ]
      }
    }
  ]
}

Rationale

#3255 needs SPX to load more than a WASM side module. The extension also expects a writable data directory and web UI assets such as HTML, CSS, and JS files.

This PR keeps that work focused on the loader contract. It does not rebuild PHP 8.2, ship SPX artifacts, or claim that SPX loads today. A follow-up can use this manifest shape when adding or rebuilding SPX artifacts.

Integration

For most consumers nothing changes structurally — manifest sources slot into the same extensions array as bundled extension names:

await loadNodeRuntime('8.4', {
  extensions: [
    'intl',
    'xdebug',
    { source: { format: 'manifest', manifestUrl: 'https://example.com/spx/manifest.json' } },
  ],
});

For hand-rolled Emscripten setups, resolvePHPExtension + withResolvedPHPExtensions in @php-wasm/universal are the lower-level pair.

Implementation

PHPExtensionManifest accepts extraFiles at two levels:

• manifest-level extraFiles for files shared by every artifact
• artifact-level extraFiles for PHP-version-specific files

Each group has a vfsRoot (the absolute VFS prefix) and an array of nodes with a vfsPath, an optional type: 'file' | 'directory', and a sourcePath (the URL to fetch, only required for files). The resolver joins vfsRoot + vfsPath into absolute VFS paths and returns:

{
  files: { '/internal/shared/spx/ui/index.html': bytes },
  directories: ['/internal/shared/spx/data'],
}

The resolver validates untrusted manifest JSON with a standalone AJV validator generated from the public PHPExtensionManifest TypeScript type. Sidecar files are fetched relative to the manifest URL or inline manifest baseUrl, with manifest-level and selected artifact-level nodes fetched in parallel through a shared concurrency limit.

Caller-supplied extraFiles on PHPExtensionInstallOptions use the same absolute-path shape ({ files, directories? }) — no targetPath indirection.

External extension manifests remain JSPI-only.

Breaking changes

• Manifest field renames: artifact.file → artifact.sourcePath; extraFiles.targetPath → vfsRoot; extraFiles.files/extraFiles.directories → unified nodes array with vfsPath/type/sourcePath.
• PHPExtensionExtraFiles (caller-supplied sidecar files) is now flat absolute VFS paths under files and directories. The previous targetPath + relative paths shape is gone.
• sha256 fields removed from sources and artifacts.
• ResolvePHPExtensionOptions is no longer exported (use PHPExtensionInstallOptions & { phpVersion: string }).

Testing instructions

```bash
npm exec nx -- test php-wasm-universal --testFile=load-extension.spec.ts
npm exec nx -- typecheck php-wasm-universal
npm exec nx -- lint php-wasm-universal
npm exec nx -- build php-wasm-universal
cd packages/php-wasm/node && npx vitest run src/test/with-php-extensions.spec.ts --config vite.jspi.config.ts
npm exec nx -- typecheck php-wasm-node
npm exec nx -- lint php-wasm-node
npm exec nx -- typecheck php-wasm-web
```

[Copilot]

Pull request overview

Note

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

Adds support for manifest-declared “sidecar” files/directories when resolving PHP extensions from external manifests, enabling assets (e.g., writable data dir, UI files) to be staged alongside the .so.

Changes:

• Extend PHPExtensionManifest / PHPExtensionManifestArtifact to declare extraFiles and resolve+fetch those assets relative to manifestUrl/baseUrl.
• Merge manifest-provided extraFiles with caller-provided extraFiles and expose them on the resolved extension for staging.
• Add/adjust tests (universal + node) and improve WordPress legacy boot test resiliency (retry on known console error, admin indicator predicate).

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
packages/playground/wordpress/tests/test-legacy-wp-version-boot.mjs	Refactors admin indicators and adds a targeted retry path when the front page boot fails due to a known console error.
packages/php-wasm/universal/src/lib/load-extension.ts	Adds manifest extraFiles types, validation, fetch/merge logic, and plumbs resolved sidecar assets through extension resolution.
packages/php-wasm/universal/src/lib/load-extension.spec.ts	Adds coverage for resolving sidecar files and rejecting escaping paths.
packages/php-wasm/universal/src/lib/index.ts	Re-exports new manifest sidecar types.
packages/php-wasm/node/src/test/with-php-extensions.spec.ts	Extends node integration test to ensure sidecar directories/files are staged into the VFS.

---

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

[adamziel]

Leaving this one open for now. A protocol allowlist should be decided consistently for extension artifact URLs and sidecar URLs, while preserving the Node wrapper behavior for local manifests / file: URLs.

[adamziel]

I'll go ahead and merge