@willbooster/tree-sitter-php

PHP grammars for tree-sitter, forked from tree-sitter/tree-sitter-php. We are grateful to its authors and contributors. This is not an official release of that project.

This fork builds on upstream's version 0.24.2 grammars with support for absolute grouped namespace imports and asymmetric visibility in constructor property promotion. Its external scanner adapts to the generated array API and fixes incremental heredoc parsing. It generates the parsers with the WillBooster/tree-sitter generator. The parsers carry that fork's own ABI number 0x5742000b, so they load only with its 15.x runtime (willbooster-tree-sitter, @willbooster/web-tree-sitter), version 15.0.0 or later within 15.x. That runtime loads no parser that upstream's generator wrote.

It holds two grammars, as upstream does: php parses PHP embedded in text, which starts in text mode and enters PHP at an opening tag such as <?php, and php_only parses PHP code on its own, where the opening tag is optional.

Support Scope

This fork maintains only full parsing: valid input yields a correct tree, and invalid input yields ERROR or MISSING nodes without crashing, hanging, or taking more than linear time. Incremental parsing works as in upstream tree-sitter but is not tested here, and no queries (highlights, locals, injections, tags) are shipped. Node types, field names, and the trees that error recovery produces may change; such changes are released as new major versions.

Usage

The npm package ships tree-sitter-php.wasm and tree-sitter-php_only.wasm for @willbooster/web-tree-sitter version 15.0.0 or later in the 15.x series, which runs in Node.js, Bun, browsers, and Cloudflare Workers. In Node.js and Bun, load the grammar from its path:

import { fileURLToPath } from 'node:url';

import { Language, Parser } from '@willbooster/web-tree-sitter';

await Parser.init();
const parser = new Parser();
const wasmPath = fileURLToPath(import.meta.resolve('@willbooster/tree-sitter-php/tree-sitter-php.wasm'));
parser.setLanguage(await Language.load(wasmPath));
const tree = parser.parse('<?php\necho "Hello, World!";\n');

In browsers, serve both .wasm files and load them by URL (the example uses Vite's ?url imports):

import phpUrl from '@willbooster/tree-sitter-php/tree-sitter-php.wasm?url';
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtimeUrl from '@willbooster/web-tree-sitter/web-tree-sitter.wasm?url';

await Parser.init({ locateFile: () => runtimeUrl });
const parser = new Parser();
parser.setLanguage(await Language.load(phpUrl));

Cloudflare Workers do not allow compiling Wasm at run time, so import both .wasm files as modules, with or without Node.js compatibility:

import php from '@willbooster/tree-sitter-php/tree-sitter-php.wasm';
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtime from '@willbooster/web-tree-sitter/web-tree-sitter.wasm';

await Parser.init({ wasmModule: runtime });
const parser = new Parser();
parser.setLanguage(await Language.load(php));

The package also ships the grammar definitions (common/define-grammar.js, php/grammar.js, and php_only/grammar.js) and the node types in php/src/node-types.json and php_only/src/node-types.json.

In Rust, depend on the crate and on willbooster-tree-sitter, the runtime this package is tested and fuzzed with:

cargo add willbooster-tree-sitter@15.0.0 --rename tree-sitter
cargo add willbooster-tree-sitter-php --rename tree-sitter-php

let mut parser = tree_sitter::Parser::new();
parser.set_language(&tree_sitter_php::LANGUAGE_PHP.into())?;

tree_sitter_php::LANGUAGE_PHP_ONLY is the php_only grammar.

Development

mise install
bun install --frozen-lockfile
bun run test/ci-setup # installs Chromium for the browser test
bun run build/ci
bun run test
script/parse-examples
cargo test

The scripts and tests generate, build, test, and parse with script/tree-sitter, the tree-sitter CLI of the WillBooster/tree-sitter runtime version locked in Cargo.lock, since the generator and the runtime of upstream's CLI are not the ones this package ships with. Its first run downloads that CLI from the runtime's GitHub Release, or builds it with cargo (whose build runs the CMake that mise.toml pins) when the download fails or the release has no binary that runs here. Run other CLI commands through it as well (e.g. script/tree-sitter parse --grammar-path php file.php).

bun run generate records a fresh generation profile from the applicable test/corpus cases and Git-tracked files in examples/ for each grammar, then generates compact parser tables. The parsers also embed metadata from tree-sitter.json. After changing a grammar, tree-sitter.json, a corpus case, or a tracked example, regenerate and commit php/src/ and php_only/src/. Stage added or removed examples with git add -A examples before generation so the profile uses the intended file list. Profiles in .tmp/generation-profiles/ are temporary and must not be committed. bun run build-wasm, bun run build/ci, and the release build regenerate the parsers before compiling them.

bun run test runs:

• the corpus in test/corpus, with the native build and with the Wasm build (the first run downloads the WASI SDK). Its cases belong to the php grammar unless they are marked :language(php_only);
• a check that the real-world PHP files in examples/, those of the cloned repositories, fail to parse with the php grammar exactly as listed in script/known-failures.txt. The first run clones the repositories. The example repositories are pinned to commits in script/parse-examples. After a grammar change or a moved pin alters that list, script/parse-examples rewrites it; review its diff before committing;
• a performance check (test/unit/performance.test.ts) that recovering from an error on each line takes linear time with both grammars, since consumers parse files while they are being edited. It loads the Wasm builds through @willbooster/web-tree-sitter, which bun run build/ci rebuilds after regenerating the parsers;
• a check (test/unit/runtimeVersion.test.ts) that @willbooster/web-tree-sitter in package.json and willbooster-tree-sitter in Cargo.lock are the same version, since the Wasm tests run on the former and the Rust tests, the fuzzer, and the CLI on the latter;
• tests that load the Wasm builds with @willbooster/web-tree-sitter in Chromium (test/e2e/browser.test.ts) and in Cloudflare Workers with and without Node.js compatibility (test/e2e/workers.test.ts).

The tests compile the parsers into .tmp/tree-sitter-lib rather than the CLI's cache shared by every checkout; script/parse-examples builds a parser of its own in .tmp/ for each run and deletes it afterwards.

CI also runs these tests on Linux arm64 and macOS, where the CLI compiles the parsers and the scanner natively, and fuzzes both parsers with libFuzzer and sanitizers (.github/workflows/robustness.yml).

References

• PHP Language Reference