Install & Compatibility
Where this runs
tested against v0.24.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.054s · 20.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.052s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
language
✓ import tree_sitter_php
The 'language' function is typically accessed via the top-level package import to get the Language object.
Language, Parser
✓ from tree_sitter import Language, Parser
These are the core classes from the main tree-sitter Python bindings used to load and utilize the grammar.
This quickstart demonstrates how to load the PHP grammar, initialize a parser, and parse a sample PHP code snippet. It then shows how to access the root node of the generated syntax tree and perform a simple query to extract class and method names.
from tree_sitter import Language, Parser
import tree_sitter_php
# Load the PHP grammar
PHP_LANGUAGE = Language(tree_sitter_php.language())
parser = Parser(PHP_LANGUAGE)
php_code = b'''
<?php
class MyClass {
public function __construct(private string $name) {}
public function greet(): string {
return "Hello, " . $this->name . "!";
}
}
$obj = new MyClass("World");
echo $obj->greet();
?>
'''
# Parse the code
tree = parser.parse(php_code)
# Get the root node of the syntax tree
root_node = tree.root_node
print(f"Root node type: {root_node.type}")
print(f"Number of children: {len(root_node.children)}")
# Example: Find a class_declaration node
for child in root_node.children:
if child.type == 'declaration_list': # often wrappers around class/function
for decl in child.children:
if decl.type == 'class_declaration':
print(f"Found class: {decl.child_by_field_name('name').text.decode('utf8')}")
break
# You can also use queries for more specific pattern matching
query = PHP_LANGUAGE.query("""
(class_declaration name: (name) @class-name)
(method_declaration name: (name) @method-name)
""")
captures = query.captures(root_node)
for node, name in captures:
print(f"Captured: {name.replace('-', '_')}: {node.text.decode('utf8')}")
Debug
Known issues
gotchaTree-sitter grammars are C libraries and typically require compilation. While `tree-sitter-php` provides pre-compiled binary wheels for common platforms, environments without a suitable C compiler or for non-standard architectures might encounter installation failures, requiring manual compilation.fixEnsure a C compiler (e.g., GCC or Clang) is installed and available in your PATH. For specific issues, consult the `py-tree-sitter` documentation or GitHub issues. Consider using `tree-sitter-languages` for a bundled solution if facing repeated compilation issues.
affects: All versions
breakingThe PHP grammar is continuously updated to support new language features (e.g., PHP 8.1+, 8.4, 8.5). Older versions of the `tree-sitter-php` grammar might fail to correctly parse newer PHP syntax, leading to incomplete or incorrect syntax trees.fixRegularly update `tree-sitter-php` to the latest version to ensure compatibility with modern PHP syntax. Check release notes for specific PHP version support.
affects: <0.24.0 (for PHP 8.5 pipe operator), <0.23.3 (for PHP 8.4 asymmetric property visibility), <0.22.x (for PHP 8.1+ features like `readonly`)
gotchaParsing `.php` files containing a mix of PHP and HTML can sometimes lead to issues or unexpected parsing behavior, especially when integrating with editor plugins that use multiple tree-sitter parsers (e.g., HTML and PHP). Historically, this led to a split into `php` and `php_only` parsers.fixBe aware of the distinction between the full PHP grammar (which handles HTML) and `php_only` variants if your toolchain offers them. Ensure proper language injection strategies in editors or tools. Consult `nvim-treesitter` or similar editor integration documentation for specific configurations related to mixed PHP/HTML files.
affects: All versions, particularly when used in environments that auto-inject grammars for mixed content.
Upgrade
Version history
0.24.1latest on PyPI · released Aug 16, 2025
Audit
Dependencies
tree-sitterrequiredProvides the core Python bindings and parsing engine for tree-sitter grammars.