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

php_parser_py-1.2.1/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.3
+Name: php-parser-py
+Version: 1.2.1
+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
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jhu-seclab-beluga/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.1/README.md

@@ -0,0 +1,52 @@
+# php-parser-py
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jhu-seclab-beluga/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.1/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "php-parser-py"
+version = "1.2.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.2.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 = [
+    "black>=26.1.0",
+    "isort>=7.0.0",
+    "mypy>=1.13.0",
+    "pylint>=4.0.4",
+    "pytest>=9.0.2",
+]
+
+[tool.pylint.messages_control]
+disable = [
+    "wrong-import-position",
+    "too-many-arguments",
+    "too-many-positional-arguments",
+    "too-many-locals",
+    "too-many-branches",
+    "too-many-statements",
+    "invalid-name",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+allow_subclassing_any = true
+
+[[tool.mypy.overrides]]
+module = ["cpg2py", "cpg2py.*", "static_php_py", "static_php_py.*"]
+ignore_missing_imports = true
+
+[tool.black]
+line-length = 88
+target-version = ["py311"]
+
+[tool.isort]
+profile = "black"
+line_length = 88

{php_parser_py-1.1.1 → php_parser_py-1.2.1}/src/php_parser_py/__init__.py

@@ -5,11 +5,8 @@ This package provides a Python interface to PHP-Parser, enabling AST parsing
 and manipulation of PHP code.
 """
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from pathlib import Path
-    from typing import Callable
+from pathlib import Path
+from typing import Callable
 
 from php_parser_py._parser import Parser as _Parser
 from php_parser_py._printer import PrettyPrinter as _PrettyPrinter
@@ -21,7 +18,7 @@ ensure_php_parser_extracted()
 # Import and expose public classes directly
 from php_parser_py._ast import AST
 from php_parser_py._edge import Edge
-from php_parser_py._exceptions import ParseError, RunnerError
+from php_parser_py._exceptions import NodeNotInFileError, ParseError, RunnerError
 from php_parser_py._node import Node
 
 
@@ -79,9 +76,13 @@ def parse_file(path: str) -> AST:
     return parser.parse_file(path)
 
 
+def _default_file_filter(path: Path) -> bool:
+    return path.suffix == ".php"
+
+
 def parse_project(
     project_path: str,
-    file_filter: "Callable[[Path], bool]" = lambda p: p.suffix == ".php",  # type: ignore
+    file_filter: Callable[[Path], bool] | None = None,
 ) -> AST:
     """Parse all PHP files in a project directory into an AST.
 
@@ -101,6 +102,8 @@ def parse_project(
         FileNotFoundError: If project directory does not exist.
         ValueError: If project_path is not a directory.
     """
+    if file_filter is None:
+        file_filter = _default_file_filter
     parser = Parser()
     return parser.parse_project(project_path, file_filter=file_filter)
 
@@ -114,6 +117,7 @@ __all__ = [
     "PrettyPrinter",
     "ParseError",
     "RunnerError",
+    "NodeNotInFileError",
     "parse_code",
     "parse_file",
     "parse_project",

php_parser_py-1.2.1/src/php_parser_py/_ast.py

@@ -0,0 +1,341 @@
+"""AST representation for PHP code using cpg2py's graph framework."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from cpg2py import AbcGraphQuerier, Storage
+
+from php_parser_py._edge import Edge
+from php_parser_py._exceptions import NodeNotInFileError
+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 structure follows a hierarchy:
+    - Project node (ID: "project") - root of the AST
+    - File nodes (ID: hex hash) - children of project
+    - Statement nodes (ID: {hex}_{counter}) - children of files
+
+    Type Parameters:
+        Node: The concrete node type for PHP AST nodes
+        Edge: The concrete edge type for parent-child relationships
+
+    Provides graph traversal methods, JSON reconstruction for code generation,
+    and AST merging capabilities. Uses cpg2py graph API (nodes, edges, succ,
+    prev, ancestors, descendants); storage is only used where the graph API
+    does not provide an alternative (node/edge existence and Node/Edge construction).
+
+    Attributes:
+        _root_node_id: ID of the root project node (always "project").
+    """
+
+    def __init__(self, storage: Storage, root_node_id: str = "project") -> None:
+        """Initialize AST with populated storage.
+
+        Args:
+            storage: cpg2py Storage containing AST nodes and edges.
+            root_node_id: ID of the root node. Defaults to "project".
+        """
+        super().__init__(storage)
+        self._root_node_id = root_node_id
+
+    def node(self, whose_id_is: str) -> Node:
+        """Return node wrapper by ID.
+
+        Args:
+            whose_id_is: Node ID string.
+
+        Returns:
+            Node instance for the given ID.
+
+        Raises:
+            KeyError: If the node ID is not in the graph.
+        """
+        if not self.storage.contains_node(whose_id_is):
+            raise KeyError(f"Node not found: {whose_id_is!r}")
+        return Node(self.storage, whose_id_is)
+
+    def edge(self, fid: str, tid: str, eid: str) -> Edge:
+        """Return edge wrapper by IDs.
+
+        Args:
+            fid: From node ID.
+            tid: To node ID.
+            eid: Edge type.
+
+        Returns:
+            Edge instance for the given (from, to, type).
+
+        Raises:
+            KeyError: If the edge is not in the graph.
+        """
+        edge_id = (fid, tid, eid)
+        if not self.storage.contains_edge(edge_id):
+            raise KeyError(f"Edge not found: {edge_id!r}")
+        return Edge(self.storage, fid, tid, eid)
+
+    def project_node(self) -> Node:
+        """Return the project node (root of the AST).
+
+        The project node has ID "project" and is always present when the AST
+        was created by parse_file or parse_project.
+
+        Returns:
+            Project Node instance.
+
+        Raises:
+            KeyError: If the root node is not in the graph.
+        """
+        if not self.storage.contains_node(self._root_node_id):
+            raise KeyError(f"Project node not found: {self._root_node_id!r}")
+        return Node(self.storage, self._root_node_id)
+
+    def file_nodes(self) -> list[Node]:
+        """Return all file nodes in the project.
+
+        Returns:
+            List of File Node instances.
+        """
+        try:
+            project = self.project_node()
+        except KeyError:
+            return []
+
+        file_nodes = [n for n in self.succ(project) if n.node_type == "File"]
+        return sorted(file_nodes, key=lambda n: n.get("absolutePath", ""))
+
+    def get_file_node(self, node_id: str) -> Node:
+        """Get the file node that contains the given node.
+
+        Uses the AST ID convention: file node ID is the file hash (e.g. 8-char hex);
+        nodes inside that file have ID ``file_hash + "_" + increment`` (e.g. ``a1b2c3d4_1``).
+        Resolves by structure first, then falls back to ancestors() traversal.
+
+        Args:
+            node_id: ID of any node in the AST.
+
+        Returns:
+            File Node instance containing the given node.
+
+        Raises:
+            KeyError: If the node ID is not in the graph.
+            NodeNotInFileError: If the node is not under any file (e.g. project node).
+        """
+        node = self.node(node_id)
+        if node.node_type == "File":
+            return node
+
+        if node_id == self._root_node_id:
+            raise NodeNotInFileError(node_id, "Project node has no containing file.")
+
+        result = self._try_file_by_id_prefix(node_id)
+        if result is not None:
+            return result
+
+        return self._find_file_ancestor(node)
+
+    def _try_file_by_id_prefix(self, node_id: str) -> Node | None:
+        """Try to find file node by ID prefix convention.
+
+        If node_id is like "hash_123", attempts to get file node with ID "hash".
+        Returns None if ID doesn't match convention or file not found.
+        """
+        if "_" not in node_id:
+            return None
+
+        prefix, rest = node_id.split("_", 1)
+        if not rest.isdigit():
+            return None
+
+        try:
+            candidate = self.node(prefix)
+            if candidate.node_type == "File":
+                return candidate
+        except KeyError:
+            pass
+
+        return None
+
+    def _find_file_ancestor(self, node: Node) -> Node:
+        """Find first File ancestor of a node via traversal.
+
+        Raises NodeNotInFileError if no File ancestor exists.
+        """
+        for ancestor in self.ancestors(node):
+            if ancestor.node_type == "File":
+                result: Node = ancestor
+                return result
+
+        raise NodeNotInFileError(node.id, "No File node among ancestors.")
+
+    def to_json(self, file_hash: str | None = None) -> str:
+        """Reconstruct PHP-Parser JSON from Storage for code generation.
+
+        If file_hash is provided, exports only that file's statements.
+        Otherwise, exports all statements from all files, or root nodes if no file structure exists.
+
+        Args:
+            file_hash: Optional file hash to export only that file.
+
+        Returns:
+            JSON string compatible with PHP-Parser's JsonDecoder.
+        """
+        if file_hash:
+            # Export single file (node() raises KeyError if file_hash not in graph)
+            self.node(file_hash)
+            top_level_nodes = self._get_file_statements(file_hash)
+        else:
+            # Try to export from file structure first
+            file_nodes = self.file_nodes()
+            if file_nodes:
+                # Export all files (flattened)
+                top_level_nodes = []
+                for file_node in file_nodes:
+                    top_level_nodes.extend(self._get_file_statements(file_node.id))
+            else:
+                # No file structure - find root nodes via graph API (no incoming PARENT_OF)
+                all_nodes = {n.id for n in self.nodes()}
+                nodes_with_parents = {
+                    e.to_nid for e in self.edges() if e.type == "PARENT_OF"
+                }
+                root_nodes = all_nodes - nodes_with_parents
+                root_nodes.discard(self._root_node_id)
+                top_level_nodes = sorted(root_nodes)
+
+        result = [self._reconstruct_node(nid) for nid in top_level_nodes]
+        return json.dumps(result)
+
+    def _get_file_statements(self, file_hash: str) -> list[str]:
+        """Get top-level statement node IDs for a file (direct children with edge field \"stmts\").
+
+        Uses succ() traversal; statement IDs follow the convention file_hash_1, file_hash_2, ...
+        """
+        file_node = self.node(file_hash)
+        stmts_with_index = []
+        for child in self.succ(file_node):
+            edge = self.edge(file_hash, child.id, "PARENT_OF")
+            if edge.get("field") == "stmts":
+                idx = edge.get("index")
+                stmts_with_index.append((999999 if idx is None else idx, child.id))
+        stmts_with_index.sort(key=lambda t: t[0])
+        return [nid for _, nid in stmts_with_index]
+
+    def _reconstruct_node(self, nid: str) -> dict[str, Any]:
+        """Recursively reconstruct JSON object for a node.
+
+        Args:
+            nid: Node ID to reconstruct.
+
+        Returns:
+            Dictionary representing the node in PHP-Parser JSON format.
+        """
+        node = self.node(nid)
+        props = node.all_properties
+        result: dict[str, Any] = {"nodeType": node.node_type}
+
+        attributes = self._extract_attributes(props)
+        if attributes:
+            result["attributes"] = attributes
+
+        self._add_non_attribute_props(result, props)
+        self._reconstruct_child_fields(result, nid)
+        self._add_default_attrs(result, node.node_type)
+
+        return result
+
+    def _extract_attributes(self, props: dict[str, Any]) -> dict[str, Any]:
+        """Extract metadata attributes from node properties.
+
+        Returns dict with position and comment metadata.
+        """
+        attr_keys = {
+            "startLine",
+            "endLine",
+            "startFilePos",
+            "endFilePos",
+            "startTokenPos",
+            "endTokenPos",
+            "kind",
+            "comments",
+        }
+        return {k: v for k, v in props.items() if k in attr_keys}
+
+    def _add_non_attribute_props(
+        self, result: dict[str, Any], props: dict[str, Any]
+    ) -> None:
+        """Add non-attribute, non-nodeType properties to result."""
+        attr_keys = {
+            "nodeType",
+            "startLine",
+            "endLine",
+            "startFilePos",
+            "endFilePos",
+            "startTokenPos",
+            "endTokenPos",
+            "kind",
+            "comments",
+        }
+        for key, value in props.items():
+            if key not in attr_keys:
+                result[key] = value
+
+    def _reconstruct_child_fields(self, result: dict[str, Any], nid: str) -> None:
+        """Reconstruct and add child fields to result.
+
+        Child nodes are fetched via succ() and indexed by edge properties.
+        """
+        node = self.node(nid)
+        child_fields: dict[str, dict[int, Any]] = {}
+
+        for child in self.succ(node):
+            try:
+                edge = self.edge(nid, child.id, "PARENT_OF")
+            except KeyError:
+                continue
+
+            field_name = edge.get("field")
+            if field_name is None:
+                continue
+
+            child_json = self._reconstruct_node(child.id)
+            index = edge.get("index")
+
+            if field_name not in child_fields:
+                child_fields[field_name] = {}
+
+            if index is not None:
+                child_fields[field_name][index] = child_json
+            else:
+                result[field_name] = child_json
+
+        for field_name, indexed_children in child_fields.items():
+            if indexed_children:
+                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
+
+    def _add_default_attrs(self, result: dict[str, Any], node_type: str) -> None:
+        """Add default attrGroups if not already present.
+
+        PHP-Parser expects attrGroups on certain node types.
+        """
+        if "attrGroups" in result:
+            return
+
+        if any(
+            node_type.startswith(prefix)
+            for prefix in ("Stmt_", "Expr_Closure", "Expr_ArrowFunction")
+        ) or node_type == "Param":
+            result["attrGroups"] = []

{php_parser_py-1.1.1 → php_parser_py-1.2.1}/src/php_parser_py/_edge.py

@@ -6,14 +6,14 @@ from cpg2py import AbcEdgeQuerier, Storage
 
 
 class Edge(AbcEdgeQuerier):
-    """Represents an edge between AST nodes.
+    """Represents an edge between AST nodes with generic property access.
 
-    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.
+    Extends cpg2py's AbcEdgeQuerier. Edge type is fixed (e.g. "PARENT_OF");
+    other data is stored as arbitrary properties via Storage. For PARENT_OF
+    edges in our PHP AST mapping, we use properties "field" and "index" to
+    represent the PHP-Parser subnode key and array position—access them via
+    edge.get("field"), edge.get("index") or edge["field"], edge["index"];
+    they are not special-cased on this class.
 
     Attributes:
         _storage: cpg2py Storage instance containing edge data.
@@ -39,45 +39,11 @@ class Edge(AbcEdgeQuerier):
 
     @property
     def type(self) -> str:
-        """Return the edge type.
-
-        Returns:
-            Edge type string (e.g., "PARENT_OF").
-        """
+        """Return the edge type (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:
+    def all_properties(self) -> dict[str, Any]:
         """Return all edge properties.
 
         Returns:

{php_parser_py-1.1.1 → php_parser_py-1.2.1}/src/php_parser_py/_exceptions.py

@@ -21,6 +21,18 @@ class ParseError(Exception):
         self.line = line
 
 
+class NodeNotInFileError(Exception):
+    """Raised when a node has no containing file (e.g. project node or orphan).
+
+    Use when get_file(node_id) is called and the node is not under any file node.
+    """
+
+    def __init__(self, node_id: str, message: str | None = None) -> None:
+        self.node_id = node_id
+        self.message = message or f"Node {node_id!r} is not under any file node."
+        super().__init__(self.message)
+
+
 class RunnerError(Exception):
     """Raised when PHP process execution fails.