php-parser-py 0.1.1__tar.gz

php_parser_py-0.1.1/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.3
+Name: php-parser-py
+Version: 0.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
+
+```python
+from php_parser_py import parse
+
+# Parse PHP code
+code = """<?php
+function greet($name) {
+    echo "Hello, $name!";
+}
+"""
+
+ast = parse(code)
+
+# Query nodes by type
+for func in ast.nodes(lambda n: n.label == "Stmt_Function"):
+    name = func.get_property("name")
+    print(f"Found function: {name}")
+```
+
+### Parse PHP File
+
+```python
+from php_parser_py import parse_file
+
+ast = parse_file("example.php")
+```
+
+### Traverse AST
+
+```python
+# Find all echo statements
+for echo in ast.nodes(lambda n: n.label == "Stmt_Echo"):
+    print(f"Echo at line {echo.get_property('startLine')}")
+
+# Get children of a node
+for child in ast.children(some_node):
+    print(f"Child type: {child.label}")
+
+# Get all descendants
+for descendant in ast.descendants(some_node):
+    print(f"Descendant: {descendant.label}")
+```
+
+### Generate PHP Code
+
+```python
+from php_parser_py import parse, PrettyPrinter
+
+# Parse code
+ast = parse("<?php echo 'hello';")
+
+# Modify AST (example: change properties)
+# ... modify nodes as needed ...
+
+# Generate code
+printer = PrettyPrinter()
+generated_code = printer.print(ast)
+print(generated_code)
+```
+
+## 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: str) -> AST`**: Parse PHP code string and return AST
+- **`parse_file(path: str) -> AST`**: Parse PHP file and return AST
+
+### 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
+  - `children(node)`: Get child nodes
+  - `descendants(node)`: Get all descendants
+  - `to_json()`: Reconstruct PHP-Parser JSON
+
+- **`Node`**: Wraps a single AST node
+  - `id`: Node identifier
+  - `label`: Node type (e.g., "Stmt_Function")
+  - `properties`: All node properties
+  - `get_property(*names)`: Get property 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, prefix="")`: Parse code string
+    - `prefix`: Optional prefix for node IDs (useful for multi-file parsing)
+  - `parse_file(path, prefix=None)`: Parse file
+    - `prefix`: Optional prefix (auto-generated from file path if not provided)
+
+- **`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)`: Generate code from AST
+
+### Exceptions
+
+- **`ParseError`**: Raised when PHP-Parser reports syntax error
+- **`RunnerError`**: Raised when PHP execution fails
+
+## 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
+
+## 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-0.1.1/README.md

@@ -0,0 +1,179 @@
+# 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
+
+```python
+from php_parser_py import parse
+
+# Parse PHP code
+code = """<?php
+function greet($name) {
+    echo "Hello, $name!";
+}
+"""
+
+ast = parse(code)
+
+# Query nodes by type
+for func in ast.nodes(lambda n: n.label == "Stmt_Function"):
+    name = func.get_property("name")
+    print(f"Found function: {name}")
+```
+
+### Parse PHP File
+
+```python
+from php_parser_py import parse_file
+
+ast = parse_file("example.php")
+```
+
+### Traverse AST
+
+```python
+# Find all echo statements
+for echo in ast.nodes(lambda n: n.label == "Stmt_Echo"):
+    print(f"Echo at line {echo.get_property('startLine')}")
+
+# Get children of a node
+for child in ast.children(some_node):
+    print(f"Child type: {child.label}")
+
+# Get all descendants
+for descendant in ast.descendants(some_node):
+    print(f"Descendant: {descendant.label}")
+```
+
+### Generate PHP Code
+
+```python
+from php_parser_py import parse, PrettyPrinter
+
+# Parse code
+ast = parse("<?php echo 'hello';")
+
+# Modify AST (example: change properties)
+# ... modify nodes as needed ...
+
+# Generate code
+printer = PrettyPrinter()
+generated_code = printer.print(ast)
+print(generated_code)
+```
+
+## 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: str) -> AST`**: Parse PHP code string and return AST
+- **`parse_file(path: str) -> AST`**: Parse PHP file and return AST
+
+### 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
+  - `children(node)`: Get child nodes
+  - `descendants(node)`: Get all descendants
+  - `to_json()`: Reconstruct PHP-Parser JSON
+
+- **`Node`**: Wraps a single AST node
+  - `id`: Node identifier
+  - `label`: Node type (e.g., "Stmt_Function")
+  - `properties`: All node properties
+  - `get_property(*names)`: Get property 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, prefix="")`: Parse code string
+    - `prefix`: Optional prefix for node IDs (useful for multi-file parsing)
+  - `parse_file(path, prefix=None)`: Parse file
+    - `prefix`: Optional prefix (auto-generated from file path if not provided)
+
+- **`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)`: Generate code from AST
+
+### Exceptions
+
+- **`ParseError`**: Raised when PHP-Parser reports syntax error
+- **`RunnerError`**: Raised when PHP execution fails
+
+## 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
+
+## 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-0.1.1/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "php-parser-py"
+version = "0.1.1"
+description = "Python wrapper for PHP-Parser using cpg2py"
+readme = "README.md"
+authors = [
+    { name = "samhsu-dev", email = "yxu166@jh.edu" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "cpg2py>=1.1.0",
+    "static-php-py",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv]
+package = true
+
+[tool.uv.build-backend]
+# Include resources directory in package data
+source-include = ["resources/*.zip"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

php_parser_py-0.1.1/src/php_parser_py/__init__.py

@@ -0,0 +1,86 @@
+"""
+php-parser-py: Python wrapper for PHP-Parser using cpg2py.
+
+This package provides a Python interface to PHP-Parser, enabling AST parsing
+and manipulation of PHP code.
+"""
+
+from php_parser_py._parser import Parser as _Parser
+from php_parser_py._printer import PrettyPrinter as _PrettyPrinter
+from php_parser_py._resources import ensure_php_parser_extracted
+
+# Ensure PHP-Parser is extracted on first import
+ensure_php_parser_extracted()
+
+# Import and expose public classes directly
+from php_parser_py._ast import AST
+from php_parser_py._node import Node
+from php_parser_py._edge import Edge
+from php_parser_py.exceptions import ParseError, RunnerError
+
+
+class Parser(_Parser):
+    """Parses PHP source code using PHP-Parser.
+
+    Invokes PHP-Parser to parse PHP code and converts the resulting JSON
+    to cpg2py Storage format for graph-based analysis.
+    """
+
+
+class PrettyPrinter(_PrettyPrinter):
+    """Converts AST to PHP code using PHP-Parser's PrettyPrinter.
+
+    Reconstructs JSON from AST graph and invokes PHP-Parser to generate
+    formatted PHP source code.
+    """
+
+
+def parse(code: str) -> AST:
+    """Parse PHP code and return AST.
+
+    Convenience function that creates a Parser instance and parses the code.
+
+    Args:
+        code: PHP source code string.
+
+    Returns:
+        AST instance containing parsed code structure.
+
+    Raises:
+        ParseError: If PHP-Parser reports syntax error.
+    """
+    parser = Parser()
+    return parser.parse(code)
+
+
+def parse_file(path: str) -> AST:
+    """Read and parse PHP file.
+
+    Convenience function that creates a Parser instance and parses the file.
+
+    Args:
+        path: File path string.
+
+    Returns:
+        AST instance containing parsed code structure.
+
+    Raises:
+        ParseError: If PHP-Parser reports syntax error.
+        FileNotFoundError: If file does not exist.
+    """
+    parser = Parser()
+    return parser.parse_file(path)
+
+
+__version__ = "0.1.0"
+__all__ = [
+    "AST",
+    "Node",
+    "Edge",
+    "Parser",
+    "PrettyPrinter",
+    "ParseError",
+    "RunnerError",
+    "parse",
+    "parse_file",
+]

php_parser_py-0.1.1/src/php_parser_py/_ast.py

@@ -0,0 +1,190 @@
+"""AST representation for PHP code using cpg2py's graph framework."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Callable, Iterable, Optional
+
+from cpg2py import AbcGraphQuerier, Storage
+
+from php_parser_py._edge import Edge
+from php_parser_py._node import Node
+
+logger = logging.getLogger(__name__)
+
+
+class AST(AbcGraphQuerier[Node, Edge]):
+    """Represents a PHP Abstract Syntax Tree.
+
+    This class extends cpg2py's AbcGraphQuerier with generic type parameters
+    specifying that it works with Node and Edge types.
+
+    The AST is stored as a graph in cpg2py Storage, where:
+    - Nodes represent PHP-Parser AST nodes (statements, expressions, etc.)
+    - Edges represent parent-child relationships with field names
+
+    Type Parameters:
+        Node: The concrete node type for PHP AST nodes
+        Edge: The concrete edge type for parent-child relationships
+
+    Provides graph traversal methods and JSON reconstruction
+    for code generation.
+
+    Attributes:
+        _storage: cpg2py Storage containing AST nodes and edges.
+    """
+
+    def __init__(self, storage: Storage) -> None:
+        """Initialize AST with populated storage.
+
+        Args:
+            storage: cpg2py Storage containing AST nodes and edges.
+        """
+        super().__init__(storage)
+        self._storage = storage
+
+    def node(self, whose_id_is: str) -> Optional[Node]:
+        """Return node wrapper by ID.
+
+        Args:
+            whose_id_is: Node ID string.
+
+        Returns:
+            Node instance or None if not found.
+        """
+        if not self._storage.contains_node(whose_id_is):
+            return None
+        return Node(self._storage, whose_id_is)
+
+    def edge(self, fid: str, tid: str, eid: str) -> Optional[Edge]:
+        """Return edge wrapper by IDs.
+
+        Args:
+            fid: From node ID.
+            tid: To node ID.
+            eid: Edge type.
+
+        Returns:
+            Edge instance or None if not found.
+        """
+        edge_id = (fid, tid, eid)
+        if not self._storage.contains_edge(edge_id):
+            return None
+        return Edge(self._storage, fid, tid, eid)
+
+    def to_json(self) -> str:
+        """Reconstruct PHP-Parser JSON from Storage for code generation.
+
+        Traverses the graph to rebuild the nested JSON structure that matches
+        PHP-Parser's original output format. This enables lossless round-trip
+        from parsing to code generation.
+
+        Returns:
+            JSON string compatible with PHP-Parser's JsonDecoder.
+        """
+        root_nodes = self._find_root_nodes()
+        result = [self._reconstruct_node(nid) for nid in root_nodes]
+        return json.dumps(result)
+
+    def _find_root_nodes(self) -> list[str]:
+        """Find nodes with no incoming PARENT_OF edges."""
+        all_nodes = set(self._storage.get_nodes())
+        child_nodes = set()
+
+        for edge_id in self._storage.get_edges():
+            _, to_id, edge_type = edge_id
+            if edge_type == "PARENT_OF":
+                child_nodes.add(to_id)
+
+        root_nodes = all_nodes - child_nodes
+        return sorted(root_nodes)
+
+    def _reconstruct_node(self, nid: str) -> dict[str, Any]:
+        """Recursively reconstruct JSON object for a node."""
+        props = self._storage.get_node_props(nid)
+        if props is None:
+            return {}
+
+        result: dict[str, Any] = {}
+        node_type = props.get("nodeType")
+        if node_type:
+            result["nodeType"] = node_type
+
+        # Collect attribute fields
+        attributes = {}
+        child_fields: dict[str, Any] = {}
+
+        for key, value in props.items():
+            if key == "nodeType":
+                continue
+            # Attributes are typically line numbers and metadata
+            if key in (
+                "startLine",
+                "endLine",
+                "startFilePos",
+                "endFilePos",
+                "startTokenPos",
+                "endTokenPos",
+                "kind",
+                "comments",
+            ):
+                attributes[key] = value
+            else:
+                # All other fields (scalars, arrays, etc.) go directly in result
+                # Child nodes will be added separately via edges
+                result[key] = value
+
+        if attributes:
+            result["attributes"] = attributes
+
+        # Reconstruct child nodes from PARENT_OF edges
+        outgoing_edges = [
+            eid
+            for eid in self._storage.get_edges()
+            if eid[0] == nid and eid[2] == "PARENT_OF"
+        ]
+
+        for from_id, to_id, edge_type in outgoing_edges:
+            edge_props = self._storage.get_edge_props((from_id, to_id, edge_type))
+            if edge_props is None:
+                continue
+
+            field_name = edge_props.get("field")
+            if field_name is None:
+                continue
+
+            child_json = self._reconstruct_node(to_id)
+            index = edge_props.get("index")
+
+            if index is not None:
+                # Array field
+                if field_name not in child_fields:
+                    child_fields[field_name] = {}
+                child_fields[field_name][index] = child_json
+            else:
+                # Single object field
+                result[field_name] = child_json
+
+        # Convert indexed dictionaries to arrays
+        for field_name, indexed_children in child_fields.items():
+            if isinstance(indexed_children, dict):
+                # Sort by index and create array
+                max_index = max(indexed_children.keys())
+                array = [None] * (max_index + 1)
+                for idx, child in indexed_children.items():
+                    array[idx] = child
+                result[field_name] = array
+
+        # Add default values for common optional fields that PHP-Parser expects
+        # These prevent "null given, array expected" errors in PrettyPrinter
+        # attrGroups is required for many node types in PHP 8+
+        if node_type and ("attrGroups" not in result):
+            # Most node types that can have attributes need attrGroups
+            if (node_type.startswith("Stmt_") or 
+                node_type == "Param" or
+                node_type.startswith("Expr_Closure") or
+                node_type.startswith("Expr_ArrowFunction")):
+                result["attrGroups"] = []
+        
+        return result