php-parser-py 0.1.1__py3-none-any.whl

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/_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

php_parser_py/_edge.py

@@ -0,0 +1,130 @@
+"""Edge class for AST relationships."""
+
+from typing import Any
+
+from cpg2py import AbcEdgeQuerier, Storage
+
+
+class Edge(AbcEdgeQuerier):
+    """Represents an edge between AST nodes.
+
+    Extends cpg2py's AbcEdgeQuerier to represent parent-child relationships
+    in the PHP AST. Edges store the relationship type and optional metadata
+    like field names and array indices for ordered children.
+
+    Note: PHP-Parser doesn't have explicit Edge objects. This is our abstraction
+    for representing the graph structure in cpg2py Storage.
+
+    Attributes:
+        _storage: cpg2py Storage instance containing edge data.
+        _edge_id: Tuple of (from_id, to_id, edge_type).
+    """
+
+    def __init__(self, graph: Storage, f_nid: str, t_nid: str, e_type: str = "PARENT_OF") -> None:
+        """Initialize Edge with storage and edge identifiers.
+
+        Args:
+            graph: cpg2py Storage containing the graph.
+            f_nid: From node ID.
+            t_nid: To node ID.
+            e_type: Edge type (default: "PARENT_OF").
+        """
+        super().__init__(graph, f_nid, t_nid, e_type)
+        self._storage = graph
+        self._edge_id = (str(f_nid), str(t_nid), str(e_type))
+
+    # Core properties
+
+    @property
+    def type(self) -> str:
+        """Return the edge type.
+
+        Returns:
+            Edge type string (e.g., "PARENT_OF").
+        """
+        return self._edge_id[2]
+
+    @property
+    def field(self) -> str | None:
+        """Return the field name for this edge.
+
+        The field name indicates which subnode property this edge represents
+        (e.g., "name", "params", "stmts").
+
+        Returns:
+            Field name string or None.
+        """
+        props = self._storage.get_edge_props(self._edge_id)
+        if props is None:
+            return None
+        return props.get("field")
+
+    @property
+    def index(self) -> int | None:
+        """Return the array index for ordered child relationships.
+
+        For edges representing array elements in PHP-Parser JSON, this property
+        contains the index position to maintain ordering.
+
+        Returns:
+            Integer index or None if not an array element.
+        """
+        props = self._storage.get_edge_props(self._edge_id)
+        if props is None:
+            return None
+        return props.get("index")
+
+    @property
+    def all_properties(self) -> dict:
+        """Return all edge properties.
+
+        Returns:
+            Dictionary of edge properties.
+        """
+        return self._storage.get_edge_props(self._edge_id) or {}
+
+    # Dict-like access methods
+
+    def __getitem__(self, key: str) -> Any:
+        """Access edge properties using dict-like syntax.
+
+        Enables edge["field"], edge["index"], etc.
+
+        Args:
+            key: Property name to access.
+
+        Returns:
+            Property value.
+
+        Raises:
+            KeyError: If property doesn't exist.
+        """
+        props = self.all_properties
+        if key not in props:
+            raise KeyError(f"Property '{key}' not found in edge {self._edge_id}")
+        return props[key]
+
+    def __contains__(self, key: str) -> bool:
+        """Check if property exists using 'in' operator.
+
+        Enables: if "index" in edge: ...
+
+        Args:
+            key: Property name to check.
+
+        Returns:
+            True if property exists, False otherwise.
+        """
+        return key in self.all_properties
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get property value with default fallback.
+
+        Args:
+            key: Property name to access.
+            default: Default value if property doesn't exist.
+
+        Returns:
+            Property value or default.
+        """
+        return self.all_properties.get(key, default)

php_parser_py/_node.py

@@ -0,0 +1,208 @@
+"""Node class for PHP AST nodes."""
+
+from typing import Any
+
+from cpg2py import AbcNodeQuerier, Storage
+
+
+class Node(AbcNodeQuerier):
+    """Wraps a single AST node with dynamic property access to PHP-Parser JSON fields.
+
+    Extends cpg2py's AbcNodeQuerier to provide access to PHP-Parser node data
+    stored in cpg2py Storage. All node properties come from PHP-Parser's JSON
+    output and are accessed dynamically without hardcoded field definitions.
+
+    PHP-Parser nodes have two types of data:
+    - **Subnodes**: Structural properties like name, params, stmts, byRef, etc.
+    - **Attributes**: Metadata like startLine, endLine, comments, etc.
+
+    Both are accessible through this class using dict-like syntax or properties.
+
+    Attributes:
+        _storage: cpg2py Storage instance containing node data.
+        _nid: Unique identifier for this node.
+    """
+
+    def __init__(self, storage: Storage, nid: str) -> None:
+        """Initialize Node with storage reference and node ID.
+
+        Args:
+            storage: cpg2py Storage instance containing node data.
+            nid: Unique identifier for this node.
+
+        Raises:
+            Exception: If node ID is not found in storage.
+        """
+        super().__init__(storage, nid)
+        self._storage = storage
+        self._nid = nid
+
+    # Core properties
+
+    @property
+    def id(self) -> str:
+        """Return the node identifier.
+
+        Returns:
+            Node ID string.
+        """
+        return self._nid
+
+    @property
+    def node_type(self) -> str | None:
+        """Return the node type from PHP-Parser.
+
+        Returns the `nodeType` field from the stored JSON, which contains
+        the PHP-Parser class name (e.g., "Stmt_Function", "Expr_Variable").
+
+        Returns:
+            Node type string or None if not set.
+        """
+        return self.get_property("nodeType")
+
+    @property
+    def all_properties(self) -> dict:
+        """Return all stored properties for this node.
+
+        Includes both subnodes (structural properties) and attributes (metadata).
+
+        Returns:
+            Dictionary containing all properties from PHP-Parser JSON.
+        """
+        return self.properties or {}
+
+    # Dict-like access methods
+
+    def __getitem__(self, key: str) -> Any:
+        """Access node properties using dict-like syntax.
+
+        Enables node["nodeType"], node["name"], node["startLine"], etc.
+
+        Args:
+            key: Property name to access.
+
+        Returns:
+            Property value.
+
+        Raises:
+            KeyError: If property doesn't exist.
+        """
+        props = self.all_properties
+        if key not in props:
+            raise KeyError(f"Property '{key}' not found in node {self._nid}")
+        return props[key]
+
+    def __contains__(self, key: str) -> bool:
+        """Check if property exists using 'in' operator.
+
+        Enables: if "name" in node: ...
+
+        Args:
+            key: Property name to check.
+
+        Returns:
+            True if property exists, False otherwise.
+        """
+        return key in self.all_properties
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get property value with default fallback.
+
+        Args:
+            key: Property name to access.
+            default: Default value if property doesn't exist.
+
+        Returns:
+            Property value or default.
+        """
+        return self.all_properties.get(key, default)
+
+    # PHP-Parser standard attributes (metadata properties)
+
+    @property
+    def start_line(self) -> int | None:
+        """Get starting line number.
+
+        Returns:
+            Starting line number or None.
+        """
+        return self.get_property("startLine")
+
+    @property
+    def end_line(self) -> int | None:
+        """Get ending line number.
+
+        Returns:
+            Ending line number or None.
+        """
+        return self.get_property("endLine")
+
+    @property
+    def start_file_pos(self) -> int | None:
+        """Get starting file position (byte offset).
+
+        Returns:
+            Starting byte offset or None.
+        """
+        return self.get_property("startFilePos")
+
+    @property
+    def end_file_pos(self) -> int | None:
+        """Get ending file position (byte offset).
+
+        Returns:
+            Ending byte offset or None.
+        """
+        return self.get_property("endFilePos")
+
+    @property
+    def start_token_pos(self) -> int | None:
+        """Get starting token position.
+
+        Returns:
+            Starting token index or None.
+        """
+        return self.get_property("startTokenPos")
+
+    @property
+    def end_token_pos(self) -> int | None:
+        """Get ending token position.
+
+        Returns:
+            Ending token index or None.
+        """
+        return self.get_property("endTokenPos")
+
+    @property
+    def comments(self) -> list | None:
+        """Get comments associated with this node.
+
+        Returns:
+            List of Comment objects or None.
+        """
+        return self.get_property("comments")
+
+    # Attribute helper methods
+
+    def has_attribute(self, name: str) -> bool:
+        """Check if attribute exists.
+
+        Args:
+            name: Attribute name to check.
+
+        Returns:
+            True if attribute exists, False otherwise.
+        """
+        return name in self
+
+    def get_attribute(self, name: str, default: Any = None) -> Any:
+        """Get attribute value with default.
+
+        Args:
+            name: Attribute name.
+            default: Default value if attribute doesn't exist.
+
+        Returns:
+            Attribute value or default.
+        """
+        return self.get(name, default)