[Docs] how to use @php-wasm/compile-extension from a downstream repo - #3595
Merged
Conversation
github-actions
Bot
added
the
[Type] Documentation
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Documents how to use @php-wasm/compile-extension from a downstream repository (since it’s not published to npm yet), and clarifies PHP version support and Rust (ext-php-rs) constraints.
Changes:
- Add downstream (sparse-checkout) GitHub Actions guidance for running the helper from another repo.
- Clarify supported
--php-versionsmatrix (PHP 7.4, 8.0–8.5) and provide a full-matrix example. - Document
ext-php-rs 0.15incompatibility with PHP 7.4 headers and the resulting matrix restriction.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| packages/php-wasm/compile-extension/README.md | Adds downstream sparse-checkout instructions and documents PHP version + Rust support caveats. |
| packages/docs/site/docs/developers/06-apis/javascript-api/08-build-php-extensions.md | Adds PHP version matrix guidance and downstream usage steps for CI. |
| packages/docs/site/docs/developers/06-apis/javascript-api/09-php-extension-dependencies.md | Adds a dedicated section on ext-php-rs PHP version limitations with an example command. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The compile-extension helper isn't on npm yet, so external CI jobs need to sparse-checkout WordPress/wordpress-playground to run it. Document the sparse-checkout list, why packages/php-wasm/compile has to come along, and the apt-mirror flake that justifies max-parallel: 1. Also call out the supported PHP matrix (7.4, 8.0–8.5) and note that Rust extensions built on ext-php-rs 0.15 can't include PHP 7.4 because the crate depends on PHP 8 Zend APIs.
- Show how to actually invoke the CLI from a downstream sparse-checkout (npm ci --ignore-scripts skips the build, so the npx form does not work there; document the type-stripping invocation PR #395 used). - Note that PHP 7.4 needs its own node-builds/7-4 entry in the sparse-checkout list. - Reformat the YAML examples to conventional 2-space indentation under with:. - Name the GitHub Actions field as strategy.max-parallel instead of bare max-parallel.
@php-wasm/compile-extension is published, so downstream repos can run the helper through npx without a wordpress-playground checkout. The new "Running in CI" section is a small GitHub Actions job that does just that. The strategy.max-parallel: 1 note stays since it's about Docker on hosted runners, not about the helper itself.
After #3596 the helper emits manifests in the PHPExtensionManifest shape: artifacts use sourcePath instead of file, sha256 was removed because the loader stopped verifying hashes, and there is a new --extra-files flag for staging sidecar assets. The README on trunk already reflects this; bring the public docs page in line and document --extra-files alongside the matrix example.
adamziel
force-pushed
the
adamziel/doc-compile-ext
branch
from
May 3, 2026 22:30
a6d2f96 to
3b2d30f
Compare
adamziel
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The
@php-wasm/compile-extensionhelper isn't on npm yet, so projects that want to build a PHP.wasm side module from their own repo (thewp_mysql_parserwork inWordPress/sqlite-database-integration#395was the trigger) have to pull it out of this monorepo. The path that worked in that PR is a sparse checkout ofWordPress/wordpress-playgroundplusnpm ci --ignore-scripts. This change writes that pattern down so the next person doesn't have to rediscover the package list.While I was in there, two more things needed clearer docs:
--php-versionsmatrix (7.4and8.0–8.5) is now stated where readers actually look, with an example invocation that builds the whole matrix.ext-php-rs 0.15can't include PHP7.4— the crate depends on PHP 8 Zend APIs and won't compile against PHP 7.4 headers. The helper itself still supports 7.4 for non-Rust extensions and for Rust extensions that bind Zend directly viabindgen. The note lives in the Rust-build-systems section so it shows up next to the rest of the Rust gotchas.Edits land in three places that all describe the same toolkit:
packages/docs/site/docs/developers/06-apis/javascript-api/08-build-php-extensions.mdpackages/docs/site/docs/developers/06-apis/javascript-api/09-php-extension-dependencies.mdpackages/php-wasm/compile-extension/README.mdDocs only — no source or binary changes.
Test plan
npm run build:docsbuilds without warnings