php-parser-py 1.1.1__tar.gz → 1.2.0__tar.gz

php_parser_py-1.2.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.3
+Name: php-parser-py
+Version: 1.2.0
+Summary: Python wrapper for PHP-Parser using cpg2py
+Author: samhsu-dev
+Author-email: samhsu-dev <yxu166@jh.edu>
+Requires-Dist: cpg2py>=1.2.0
+Requires-Dist: static-php-py
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# php-parser-py
+
+Python wrapper for [nikic/PHP-Parser](https://github.com/nikic/PHP-Parser) built on the [cpg2py](https://github.com/jhu-seclab/cpg2py) graph framework.
+
+- **Automated**: Uses [static-php-cli](https://github.com/static-php-cli/static-php-cli) binaries (no local PHP required).
+- **Graph-Based**: AST nodes are stored in a queryable graph database.
+- **Accurate**: Full support for PHP-Parser 4.19.4 AST structure.
+
+## Quick Start
+```bash
+pip install php-parser-py
+```
+
+```python
+from php_parser_py import parse_file, parse_project
+
+# 1. Parse
+ast = parse_file("src/User.php")
+# ast = parse_project("src/")
+
+# 2. Traverse
+files = ast.file_nodes()
+
+# Find specific nodes
+functions = ast.nodes(lambda n: n.node_type == "Stmt_Function")
+
+# Get properties (scalars)
+for func in functions:
+    print(f"Function: {func['namespacedName']}")
+
+# Get child nodes (structure)
+for func in functions:
+    # Use helper method or traverse edges
+    params = [c for c in ast.succ(func) if c.node_type == "Param"]
+```
+
+## Documentation
+
+- **[Architecture & Design](docs/design.md)**
+  Detailed design documentation covering internal architecture, class specifications, and design rationale.
+
+- **[AST Structure Reference](docs/libs/php_parser_ast.md)**  
+  Complete table of all node types, subnodes (children), and properties. Verified against PHP-Parser source.
+
+- **[Graph Traversal Guide](docs/libs/cpg2py_traversal.md)**  
+  How to navigate the graph (`succ`, `prev`), access properties, and modify the graph (`set_property`).
+
+## Requirements
+- Python ≥ 3.11
+- (Optional) Custom PHP binary can be configured via `Parser` constructor.

php_parser_py-1.2.0/README.md

@@ -0,0 +1,50 @@
+# php-parser-py
+
+Python wrapper for [nikic/PHP-Parser](https://github.com/nikic/PHP-Parser) built on the [cpg2py](https://github.com/jhu-seclab/cpg2py) graph framework.
+
+- **Automated**: Uses [static-php-cli](https://github.com/static-php-cli/static-php-cli) binaries (no local PHP required).
+- **Graph-Based**: AST nodes are stored in a queryable graph database.
+- **Accurate**: Full support for PHP-Parser 4.19.4 AST structure.
+
+## Quick Start
+```bash
+pip install php-parser-py
+```
+
+```python
+from php_parser_py import parse_file, parse_project
+
+# 1. Parse
+ast = parse_file("src/User.php")
+# ast = parse_project("src/")
+
+# 2. Traverse
+files = ast.file_nodes()
+
+# Find specific nodes
+functions = ast.nodes(lambda n: n.node_type == "Stmt_Function")
+
+# Get properties (scalars)
+for func in functions:
+    print(f"Function: {func['namespacedName']}")
+
+# Get child nodes (structure)
+for func in functions:
+    # Use helper method or traverse edges
+    params = [c for c in ast.succ(func) if c.node_type == "Param"]
+```
+
+## Documentation
+
+- **[Architecture & Design](docs/design.md)**
+  Detailed design documentation covering internal architecture, class specifications, and design rationale.
+
+- **[AST Structure Reference](docs/libs/php_parser_ast.md)**  
+  Complete table of all node types, subnodes (children), and properties. Verified against PHP-Parser source.
+
+- **[Graph Traversal Guide](docs/libs/cpg2py_traversal.md)**  
+  How to navigate the graph (`succ`, `prev`), access properties, and modify the graph (`set_property`).
+
+## Requirements
+- Python ≥ 3.11
+- (Optional) Custom PHP binary can be configured via `Parser` constructor.

{php_parser_py-1.1.1 → php_parser_py-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "php-parser-py"
-version = "1.1.1"
+version = "1.2.0"
 description = "Python wrapper for PHP-Parser using cpg2py"
 readme = "README.md"
 authors = [
@@ -8,7 +8,7 @@ authors = [
 ]
 requires-python = ">=3.11"
 dependencies = [
-    "cpg2py>=1.1.0",
+    "cpg2py>=1.2.0",
     "static-php-py",
 ]
 

{php_parser_py-1.1.1 → php_parser_py-1.2.0}/src/php_parser_py/_ast.py

@@ -77,35 +77,25 @@ class AST(AbcGraphQuerier[Node, Edge]):
             return None
         return Edge(self._storage, fid, tid, eid)
 
-    @property
-    def root_node(self) -> Optional[Node]:
-        """Return the root project node of the AST.
+    def project_node(self) -> Optional[Node]:
+        """Return the project node.
 
-        The root node is always the project node with ID "project".
+        The project node is the root of the AST with ID "project".
 
         Returns:
-            Root Node instance or None if root node doesn't exist.
+            Project Node instance or None if not found.
         """
         if not self._storage.contains_node(self._root_node_id):
             return None
         return Node(self._storage, self._root_node_id)
 
-    @property
-    def project_node(self) -> Optional[Node]:
-        """Return the project node (alias for root_node).
-
-        Returns:
-            Project Node instance or None if not found.
-        """
-        return self.root_node
-
-    def files(self) -> list[Node]:
+    def file_nodes(self) -> list[Node]:
         """Return all file nodes in the project.
 
         Returns:
             List of File Node instances.
         """
-        if not self.root_node:
+        if not self.project_node():
             return []
 
         file_nodes = []
@@ -204,7 +194,7 @@ class AST(AbcGraphQuerier[Node, Edge]):
             top_level_nodes = self._get_file_statements(file_hash)
         else:
             # Try to export from file structure first
-            file_nodes = self.files()
+            file_nodes = self.file_nodes()
             if file_nodes:
                 # Export all files (flattened)
                 top_level_nodes = []

{php_parser_py-1.1.1 → php_parser_py-1.2.0}/src/php_parser_py/_parser.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Any, Callable, Optional
 
 from cpg2py import Storage
+from static_php_py import PHP
 
 from php_parser_py._ast import AST
 from php_parser_py._exceptions import ParseError, RunnerError
@@ -27,21 +28,13 @@ class Parser:
         _runner: Runner instance for PHP-Parser invocation.
     """
 
-    def __init__(
-        self,
-        php_binary_path: Optional[Path] = None,
-        php_binary_url: Optional[str] = None,
-    ) -> None:
+    def __init__(self, php: Optional[PHP] = None) -> None:
         """Initialize Parser with Runner.
 
         Args:
-            php_binary_path: Optional path to local PHP binary.
-            php_binary_url: Optional URL to download PHP binary from.
+            php: Optional PHP instance. If not provided, uses builtin PHP.
         """
-        self._runner = Runner(
-            php_binary_path=php_binary_path,
-            php_binary_url=php_binary_url,
-        )
+        self._runner = Runner(php=php)
 
     def parse_code(self, code: str) -> list[Node]:
         """Parse PHP code string into a list of top-level statement nodes.

{php_parser_py-1.1.1 → php_parser_py-1.2.0}/src/php_parser_py/_printer.py

@@ -1,9 +1,10 @@
 """PrettyPrinter class for PHP code generation."""
 
 import logging
-from pathlib import Path
 from typing import Optional
 
+from static_php_py import PHP
+
 from php_parser_py._ast import AST
 from php_parser_py._runner import Runner
 
@@ -22,18 +23,15 @@ class PrettyPrinter:
 
     def __init__(
         self,
-        php_binary_path: Optional[Path] = None,
-        php_binary_url: Optional[str] = None,
+        php: Optional[PHP] = None,
     ) -> None:
         """Initialize PrettyPrinter with Runner.
 
         Args:
-            php_binary_path: Optional path to local PHP binary.
-            php_binary_url: Optional URL to download PHP binary from.
+           php: Optional PHP instance. If not provided, uses builtin PHP.
         """
         self._runner = Runner(
-            php_binary_path=php_binary_path,
-            php_binary_url=php_binary_url,
+            php=php,
         )
 
     def print(self, ast: AST) -> dict[str, str]:
@@ -50,7 +48,7 @@ class PrettyPrinter:
         Raises:
             RunnerError: If PHP-Parser execution fails.
         """
-        file_nodes = ast.files()
+        file_nodes = ast.file_nodes()
 
         if not file_nodes:
             # No file structure - export all statements as a single code block
@@ -98,7 +96,7 @@ class PrettyPrinter:
             RunnerError: If PHP-Parser execution fails.
         """
         # Find file node by its relative path property
-        for file_node in ast.files():
+        for file_node in ast.file_nodes():
             if file_node.get_property("path") == relative_path:
                 file_hash = file_node.id
                 json_str = ast.to_json(file_hash=file_hash)

{php_parser_py-1.1.1 → php_parser_py-1.2.0}/src/php_parser_py/_runner.py

@@ -3,7 +3,6 @@
 import json
 import logging
 import subprocess
-from pathlib import Path
 from typing import Any, Optional
 
 from static_php_py import PHP
@@ -26,41 +25,26 @@ class Runner:
         _vendor_dir: Path to directory containing PHP-Parser PHAR.
     """
 
-    def __init__(
-        self,
-        php_binary_path: Optional[Path] = None,
-        php_binary_url: Optional[str] = None,
-    ) -> None:
-        """Initialize Runner with PHP binary and PHP-Parser paths.
+    def __init__(self, php: Optional[PHP] = None) -> None:
+        """Initialize Runner with PHP binary wrapper.
 
         Args:
-            php_binary_path: Optional path to local PHP binary.
-            php_binary_url: Optional URL to download PHP binary from.
+            php: Optional PHP instance. If not provided, uses builtin PHP.
 
         Raises:
-            RunnerError: If PHP binary or PHP-Parser cannot be located.
+            RunnerError: If PHP binary cannot be located.
         """
         self._vendor_dir = ensure_php_parser_extracted()
 
-        # Determine PHP binary source with priority: custom path > custom URL > built-in
         try:
-            if php_binary_path is not None:
-                # Use custom local PHP binary
-                php = PHP.local(php_binary_path)
-            elif php_binary_url is not None:
-                # Download PHP binary from custom URL
-                php = PHP.remote(php_binary_url)
-            else:
-                # Use built-in PHP binary from static-php-py
-                php = PHP.builtin()
-
-            self._php_binary = php.path()
-
+            self._php = php if php is not None else PHP.builtin()
+            self._php_binary = self._php.path()
+            
         except BinaryNotFoundError as e:
             raise RunnerError(
                 f"PHP binary not found: {e}. "
                 "The built-in PHP binary may not be available for your platform. "
-                "Please provide a custom PHP binary path or URL.",
+                "Please provide a custom PHP instance.",
                 exit_code=1,
             ) from e
         except DownloadError as e:

php_parser_py-1.1.1/PKG-INFO

@@ -1,285 +0,0 @@
-Metadata-Version: 2.3
-Name: php-parser-py
-Version: 1.1.1
-Summary: Python wrapper for PHP-Parser using cpg2py
-Author: samhsu-dev
-Author-email: samhsu-dev <yxu166@jh.edu>
-Requires-Dist: cpg2py>=1.1.0
-Requires-Dist: static-php-py
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# php-parser-py
-
-Python wrapper for PHP-Parser using cpg2py's graph framework.
-
-## Overview
-
-`php-parser-py` provides a Python interface to [PHP-Parser](https://github.com/nikic/PHP-Parser), enabling Abstract Syntax Tree (AST) parsing and manipulation of PHP code. The library integrates with [cpg2py](https://github.com/jhu-seclab/cpg2py)'s graph framework for powerful graph-based code analysis.
-
-## Features
-
-- **Native PHP-Parser Integration**: Delegates all parsing and code generation to PHP-Parser for maximum compatibility
-- **Zero-Configuration PHP**: Bundled PHP binaries via static-php-py - no system PHP installation required
-- **Graph-Based Analysis**: Uses cpg2py's graph framework for AST traversal and querying
-- **Dynamic Node Types**: No hardcoded PHP node types - all types come from PHP-Parser's JSON output
-- **Lossless Round-Trip**: Parse → Modify → Generate code with full fidelity
-- **Cross-Platform Support**: Pre-built PHP 8.4 binaries for Linux (x86_64/aarch64), macOS (x86_64/arm64), and Windows (x64)
-
-## Installation
-
-```bash
-pip install php-parser-py
-```
-
-**Note**: Platform-specific wheels include pre-built PHP 8.4 binaries. No separate PHP installation required!
-
-## Quick Start
-
-### Parse PHP Code (Without Project Structure)
-
-```python
-from php_parser_py import parse_code
-
-# Parse PHP code into raw statement nodes
-code = """<?php
-function greet($name) {
-    echo "Hello, $name!";
-}
-"""
-
-nodes = parse_code(code)
-# Returns list of Node instances (no project/file structure)
-
-for node in nodes:
-    print(f"Node type: {node.node_type}")
-```
-
-### Parse PHP File (With Project Structure)
-
-```python
-from php_parser_py import parse_file
-
-# Parse a single file with project/file structure
-ast = parse_file("example.php")
-
-# Access project and file nodes
-project = ast.project_node
-files = ast.files()
-print(f"Project has {len(files)} file(s)")
-
-# Get file containing a specific node
-stmt_node = ast.first_node(lambda n: n.node_type == "Stmt_Function")
-file_node = ast.get_file(stmt_node.id)
-print(f"Function is in file: {file_node.get_property('filePath')}")
-```
-
-### Parse Project Directory
-
-```python
-from php_parser_py import parse_project
-from pathlib import Path
-
-# Parse all PHP files in a project directory (recursively)
-ast = parse_project("/path/to/project")
-
-# Access all files
-for file_node in ast.files():
-    print(f"File: {file_node.get_property('filePath')}")
-    # Get statements in this file
-    for stmt in ast.succ(file_node):
-        print(f"  Statement: {stmt.node_type}")
-
-# Access project and file paths
-project = ast.project_node
-print(f"Project root: {project.get_property('path')}")
-
-for file_node in ast.files():
-    print(f"File relative path: {file_node.get_property('path')}")
-    print(f"File absolute path: {file_node.get_property('filePath')}")
-
-# Use custom file filter (e.g., include .php and .phtml files)
-ast = parse_project(
-    "/path/to/project",
-    file_filter=lambda p: p.suffix in ['.php', '.phtml']
-)
-```
-
-### Traverse AST
-
-```python
-from php_parser_py import parse_file
-
-ast = parse_file("example.php")
-
-# Find all echo statements
-for echo in ast.nodes(lambda n: n.node_type == "Stmt_Echo"):
-    print(f"Echo at line {echo.start_line}")
-
-# Get children of a node (via PARENT_OF edges)
-for child in ast.succ(some_node):
-    print(f"Child type: {child.node_type}")
-
-# Get all descendants
-for descendant in ast.descendants(some_node):
-    print(f"Descendant: {descendant.node_type}")
-
-# Get file containing a node
-stmt_node = ast.first_node(lambda n: n.node_type == "Stmt_Function")
-file_node = ast.get_file(stmt_node.id)
-if file_node:
-    print(f"Function is in: {file_node.get_property('filePath')}")
-
-# Access project structure
-project = ast.project_node
-files = ast.files()
-for file_node in files:
-    print(f"File: {file_node.get_property('filePath')}")
-```
-
-### Generate PHP Code
-
-```python
-from php_parser_py import parse_file, parse_project, PrettyPrinter
-
-# Parse single file
-ast = parse_file("example.php")
-
-# Generate code (returns dict mapping file paths to code)
-printer = PrettyPrinter()
-generated = printer.print(ast)
-for file_path, code in generated.items():
-    print(f"File: {file_path}")
-    print(code)
-
-# Parse project directory (recursively finds all PHP files)
-ast = parse_project("/path/to/project")
-
-# Generate code for all files
-generated = printer.print(ast)
-# Returns: {"src/file1.php": "...", "src/file2.php": "..."}
-```
-
-## Advanced Usage
-
-### Custom PHP Binary
-
-If you need to use a specific PHP version or custom binary:
-
-```python
-from php_parser_py import Parser
-from pathlib import Path
-
-# Use local PHP binary
-parser = Parser(php_binary_path=Path("/usr/local/bin/php"))
-ast = parser.parse("<?php echo 'hello';")
-
-# Or download from remote URL
-parser = Parser(php_binary_url="https://example.com/php-8.4.zip")
-ast = parser.parse("<?php echo 'hello';")
-```
-
-## API Reference
-
-### Main Functions
-
-- **`parse_code(code: str) -> list[Node]`**: Parse PHP code string into raw statement nodes (no project/file structure)
-- **`parse(code: str) -> AST`**: Parse PHP code string and return AST with project/file structure (backward compatibility)
-- **`parse_file(path: str) -> AST`**: Parse a single PHP file and return AST with project/file structure
-- **`parse_project(project_path: str, file_filter: Callable[[Path], bool] = lambda p: p.suffix == '.php') -> AST`**: Parse all PHP files in a project directory into a single AST with project structure. `file_filter` function to customize which files are included (defaults to `.php` suffix check)
-
-### Classes
-
-- **`AST`**: Represents the complete AST as a graph
-  - `node(id)`: Get node by ID
-  - `nodes(predicate)`: Iterate nodes matching predicate
-  - `first_node(predicate)`: Get first matching node
-  - `succ(node, predicate)`: Get successor nodes (children via PARENT_OF edges)
-  - `prev(node, predicate)`: Get predecessor nodes (parents via PARENT_OF edges)
-  - `descendants(node, predicate)`: Get all descendants via BFS
-  - `ancestors(node, predicate)`: Get all ancestors via BFS
-  - `root_node`: Property returning the root/project node
-  - `project_node`: Property returning the project node (alias for root_node)
-  - `files()`: Get all file nodes in the project
-  - `get_file(node_id)`: Get the file node containing the given node
-  - `to_json()`: Reconstruct PHP-Parser JSON
-
-- **`Node`**: Wraps a single AST node
-  - `id`: Node identifier
-  - `node_type`: Node type (e.g., "Stmt_Function") - returns `nodeType` property
-  - `all_properties`: All node properties as dict
-  - `get_property(*names)`: Get property value
-  - `start_line`, `end_line`: Line number properties
-  - `__getitem__(key)`: Dict-like access (e.g., `node["name"]`)
-  - `get(key, default)`: Get property with default value
-
-- **`Parser`**: Parses PHP code
-  - `__init__(php_binary_path=None, php_binary_url=None)`: Initialize parser
-    - `php_binary_path`: Optional path to local PHP binary
-    - `php_binary_url`: Optional URL to download PHP binary from
-  - `parse_code(code)`: Parse code string into list of nodes
-  - `parse(code)`: Parse code string into AST (backward compatibility)
-  - `parse_file(path)`: Parse file into AST with project/file structure
-  - `parse_project(project_path)`: Parse project directory into AST with project structure
-
-- **`PrettyPrinter`**: Generates PHP code
-  - `__init__(php_binary_path=None, php_binary_url=None)`: Initialize printer
-    - `php_binary_path`: Optional path to local PHP binary
-    - `php_binary_url`: Optional URL to download PHP binary from
-  - `print(ast) -> dict[str, str]`: Generate code from AST, returns dictionary mapping file paths to generated code
-    - Returns: `{file_path: code_string, ...}` for each file in the AST
-    - If AST has no file structure, returns `{"": code_string}`
-
-### Exceptions
-
-- **`ParseError`**: Raised when PHP-Parser reports syntax error
-- **`RunnerError`**: Raised when PHP execution fails
-
-## AST Structure
-
-The library supports three parsing modes:
-
-1. **Code Parsing** (`parse_code`): Returns flat list of statement nodes
-   - Node IDs: `node_1`, `node_2`, ...
-   - No project/file structure
-
-2. **File Parsing** (`parse_file`): Creates project → file → statements hierarchy
-   - Project node: `"project"` (fixed ID)
-   - File node: 8-character hex hash (e.g., `"a1b2c3d4"`)
-   - Statement nodes: `{hex}_1`, `{hex}_2`, ...
-
-3. **Project Parsing** (`parse_project`): Creates project → multiple files → statements hierarchy
-   - Single project node: `"project"` (fixed ID)
-   - Multiple file nodes: Each with unique hex hash
-   - Statement nodes: Prefixed with their file's hash
-
-## Architecture
-
-The library follows a delegation-based architecture:
-
-1. **PHP-Parser** handles all parsing and code generation
-2. **cpg2py Storage** stores the AST as a graph
-3. **Python classes** provide convenient access to the graph
-
-This design ensures:
-- No need to maintain PHP node type definitions in Python
-- Automatic compatibility with PHP-Parser updates
-- Full access to PHP-Parser's features
-- Support for multi-file project analysis with merge capabilities
-
-## Requirements
-
-- Python >= 3.11
-- cpg2py
-- static-php-py (bundled PHP binaries)
-
-## License
-
-MIT License - see LICENSE file for details.
-
-## Documentation
-
-For detailed design documentation, see:
-- [Design Document](docs/design.md)
-- [Idea Document](docs/idea.md)
-- [API Demo](docs/api_demo.ipynb)

php_parser_py-1.1.1/README.md

@@ -1,274 +0,0 @@
-# php-parser-py
-
-Python wrapper for PHP-Parser using cpg2py's graph framework.
-
-## Overview
-
-`php-parser-py` provides a Python interface to [PHP-Parser](https://github.com/nikic/PHP-Parser), enabling Abstract Syntax Tree (AST) parsing and manipulation of PHP code. The library integrates with [cpg2py](https://github.com/jhu-seclab/cpg2py)'s graph framework for powerful graph-based code analysis.
-
-## Features
-
-- **Native PHP-Parser Integration**: Delegates all parsing and code generation to PHP-Parser for maximum compatibility
-- **Zero-Configuration PHP**: Bundled PHP binaries via static-php-py - no system PHP installation required
-- **Graph-Based Analysis**: Uses cpg2py's graph framework for AST traversal and querying
-- **Dynamic Node Types**: No hardcoded PHP node types - all types come from PHP-Parser's JSON output
-- **Lossless Round-Trip**: Parse → Modify → Generate code with full fidelity
-- **Cross-Platform Support**: Pre-built PHP 8.4 binaries for Linux (x86_64/aarch64), macOS (x86_64/arm64), and Windows (x64)
-
-## Installation
-
-```bash
-pip install php-parser-py
-```
-
-**Note**: Platform-specific wheels include pre-built PHP 8.4 binaries. No separate PHP installation required!
-
-## Quick Start
-
-### Parse PHP Code (Without Project Structure)
-
-```python
-from php_parser_py import parse_code
-
-# Parse PHP code into raw statement nodes
-code = """<?php
-function greet($name) {
-    echo "Hello, $name!";
-}
-"""
-
-nodes = parse_code(code)
-# Returns list of Node instances (no project/file structure)
-
-for node in nodes:
-    print(f"Node type: {node.node_type}")
-```
-
-### Parse PHP File (With Project Structure)
-
-```python
-from php_parser_py import parse_file
-
-# Parse a single file with project/file structure
-ast = parse_file("example.php")
-
-# Access project and file nodes
-project = ast.project_node
-files = ast.files()
-print(f"Project has {len(files)} file(s)")
-
-# Get file containing a specific node
-stmt_node = ast.first_node(lambda n: n.node_type == "Stmt_Function")
-file_node = ast.get_file(stmt_node.id)
-print(f"Function is in file: {file_node.get_property('filePath')}")
-```
-
-### Parse Project Directory
-
-```python
-from php_parser_py import parse_project
-from pathlib import Path
-
-# Parse all PHP files in a project directory (recursively)
-ast = parse_project("/path/to/project")
-
-# Access all files
-for file_node in ast.files():
-    print(f"File: {file_node.get_property('filePath')}")
-    # Get statements in this file
-    for stmt in ast.succ(file_node):
-        print(f"  Statement: {stmt.node_type}")
-
-# Access project and file paths
-project = ast.project_node
-print(f"Project root: {project.get_property('path')}")
-
-for file_node in ast.files():
-    print(f"File relative path: {file_node.get_property('path')}")
-    print(f"File absolute path: {file_node.get_property('filePath')}")
-
-# Use custom file filter (e.g., include .php and .phtml files)
-ast = parse_project(
-    "/path/to/project",
-    file_filter=lambda p: p.suffix in ['.php', '.phtml']
-)
-```
-
-### Traverse AST
-
-```python
-from php_parser_py import parse_file
-
-ast = parse_file("example.php")
-
-# Find all echo statements
-for echo in ast.nodes(lambda n: n.node_type == "Stmt_Echo"):
-    print(f"Echo at line {echo.start_line}")
-
-# Get children of a node (via PARENT_OF edges)
-for child in ast.succ(some_node):
-    print(f"Child type: {child.node_type}")
-
-# Get all descendants
-for descendant in ast.descendants(some_node):
-    print(f"Descendant: {descendant.node_type}")
-
-# Get file containing a node
-stmt_node = ast.first_node(lambda n: n.node_type == "Stmt_Function")
-file_node = ast.get_file(stmt_node.id)
-if file_node:
-    print(f"Function is in: {file_node.get_property('filePath')}")
-
-# Access project structure
-project = ast.project_node
-files = ast.files()
-for file_node in files:
-    print(f"File: {file_node.get_property('filePath')}")
-```
-
-### Generate PHP Code
-
-```python
-from php_parser_py import parse_file, parse_project, PrettyPrinter
-
-# Parse single file
-ast = parse_file("example.php")
-
-# Generate code (returns dict mapping file paths to code)
-printer = PrettyPrinter()
-generated = printer.print(ast)
-for file_path, code in generated.items():
-    print(f"File: {file_path}")
-    print(code)
-
-# Parse project directory (recursively finds all PHP files)
-ast = parse_project("/path/to/project")
-
-# Generate code for all files
-generated = printer.print(ast)
-# Returns: {"src/file1.php": "...", "src/file2.php": "..."}
-```
-
-## Advanced Usage
-
-### Custom PHP Binary
-
-If you need to use a specific PHP version or custom binary:
-
-```python
-from php_parser_py import Parser
-from pathlib import Path
-
-# Use local PHP binary
-parser = Parser(php_binary_path=Path("/usr/local/bin/php"))
-ast = parser.parse("<?php echo 'hello';")
-
-# Or download from remote URL
-parser = Parser(php_binary_url="https://example.com/php-8.4.zip")
-ast = parser.parse("<?php echo 'hello';")
-```
-
-## API Reference
-
-### Main Functions
-
-- **`parse_code(code: str) -> list[Node]`**: Parse PHP code string into raw statement nodes (no project/file structure)
-- **`parse(code: str) -> AST`**: Parse PHP code string and return AST with project/file structure (backward compatibility)
-- **`parse_file(path: str) -> AST`**: Parse a single PHP file and return AST with project/file structure
-- **`parse_project(project_path: str, file_filter: Callable[[Path], bool] = lambda p: p.suffix == '.php') -> AST`**: Parse all PHP files in a project directory into a single AST with project structure. `file_filter` function to customize which files are included (defaults to `.php` suffix check)
-
-### Classes
-
-- **`AST`**: Represents the complete AST as a graph
-  - `node(id)`: Get node by ID
-  - `nodes(predicate)`: Iterate nodes matching predicate
-  - `first_node(predicate)`: Get first matching node
-  - `succ(node, predicate)`: Get successor nodes (children via PARENT_OF edges)
-  - `prev(node, predicate)`: Get predecessor nodes (parents via PARENT_OF edges)
-  - `descendants(node, predicate)`: Get all descendants via BFS
-  - `ancestors(node, predicate)`: Get all ancestors via BFS
-  - `root_node`: Property returning the root/project node
-  - `project_node`: Property returning the project node (alias for root_node)
-  - `files()`: Get all file nodes in the project
-  - `get_file(node_id)`: Get the file node containing the given node
-  - `to_json()`: Reconstruct PHP-Parser JSON
-
-- **`Node`**: Wraps a single AST node
-  - `id`: Node identifier
-  - `node_type`: Node type (e.g., "Stmt_Function") - returns `nodeType` property
-  - `all_properties`: All node properties as dict
-  - `get_property(*names)`: Get property value
-  - `start_line`, `end_line`: Line number properties
-  - `__getitem__(key)`: Dict-like access (e.g., `node["name"]`)
-  - `get(key, default)`: Get property with default value
-
-- **`Parser`**: Parses PHP code
-  - `__init__(php_binary_path=None, php_binary_url=None)`: Initialize parser
-    - `php_binary_path`: Optional path to local PHP binary
-    - `php_binary_url`: Optional URL to download PHP binary from
-  - `parse_code(code)`: Parse code string into list of nodes
-  - `parse(code)`: Parse code string into AST (backward compatibility)
-  - `parse_file(path)`: Parse file into AST with project/file structure
-  - `parse_project(project_path)`: Parse project directory into AST with project structure
-
-- **`PrettyPrinter`**: Generates PHP code
-  - `__init__(php_binary_path=None, php_binary_url=None)`: Initialize printer
-    - `php_binary_path`: Optional path to local PHP binary
-    - `php_binary_url`: Optional URL to download PHP binary from
-  - `print(ast) -> dict[str, str]`: Generate code from AST, returns dictionary mapping file paths to generated code
-    - Returns: `{file_path: code_string, ...}` for each file in the AST
-    - If AST has no file structure, returns `{"": code_string}`
-
-### Exceptions
-
-- **`ParseError`**: Raised when PHP-Parser reports syntax error
-- **`RunnerError`**: Raised when PHP execution fails
-
-## AST Structure
-
-The library supports three parsing modes:
-
-1. **Code Parsing** (`parse_code`): Returns flat list of statement nodes
-   - Node IDs: `node_1`, `node_2`, ...
-   - No project/file structure
-
-2. **File Parsing** (`parse_file`): Creates project → file → statements hierarchy
-   - Project node: `"project"` (fixed ID)
-   - File node: 8-character hex hash (e.g., `"a1b2c3d4"`)
-   - Statement nodes: `{hex}_1`, `{hex}_2`, ...
-
-3. **Project Parsing** (`parse_project`): Creates project → multiple files → statements hierarchy
-   - Single project node: `"project"` (fixed ID)
-   - Multiple file nodes: Each with unique hex hash
-   - Statement nodes: Prefixed with their file's hash
-
-## Architecture
-
-The library follows a delegation-based architecture:
-
-1. **PHP-Parser** handles all parsing and code generation
-2. **cpg2py Storage** stores the AST as a graph
-3. **Python classes** provide convenient access to the graph
-
-This design ensures:
-- No need to maintain PHP node type definitions in Python
-- Automatic compatibility with PHP-Parser updates
-- Full access to PHP-Parser's features
-- Support for multi-file project analysis with merge capabilities
-
-## Requirements
-
-- Python >= 3.11
-- cpg2py
-- static-php-py (bundled PHP binaries)
-
-## License
-
-MIT License - see LICENSE file for details.
-
-## Documentation
-
-For detailed design documentation, see:
-- [Design Document](docs/design.md)
-- [Idea Document](docs/idea.md)
-- [API Demo](docs/api_demo.ipynb)