php-parser-py 1.1.0__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.0 → php_parser_py-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "php-parser-py"
-version = "1.1.0"
+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",
 ]
 
@@ -25,5 +25,8 @@ source-include = ["resources/*.zip"]
 
 [dependency-groups]
 dev = [
+    "black>=26.1.0",
+    "isort>=7.0.0",
+    "pylint>=4.0.4",
     "pytest>=9.0.2",
 ]

{php_parser_py-1.1.0 → php_parser_py-1.2.0}/src/php_parser_py/__init__.py

@@ -5,6 +5,12 @@ 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 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
@@ -14,9 +20,9 @@ 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
+from php_parser_py._exceptions import ParseError, RunnerError
+from php_parser_py._node import Node
 
 
 class Parser(_Parser):
@@ -53,35 +59,6 @@ def parse_code(code: str) -> list[Node]:
     return parser.parse_code(code)
 
 
-def parse(code: str) -> AST:
-    """Parse PHP code string into an AST (backward compatibility).
-
-    This is a convenience function that creates a temporary project/file structure.
-    For code-only parsing without project structure, use parse_code() instead.
-
-    Args:
-        code: PHP source code string.
-
-    Returns:
-        AST instance with project -> file -> statements hierarchy.
-
-    Raises:
-        ParseError: If PHP-Parser reports syntax error.
-    """
-    # Create a temporary file-like structure for backward compatibility
-    import tempfile
-    from pathlib import Path
-    
-    with tempfile.NamedTemporaryFile(mode='w', suffix='.php', delete=False) as f:
-        f.write(code)
-        temp_path = f.name
-    
-    try:
-        return parse_file(temp_path)
-    finally:
-        Path(temp_path).unlink()
-
-
 def parse_file(path: str) -> AST:
     """Read and parse a single PHP file into an AST.
 
@@ -102,25 +79,30 @@ def parse_file(path: str) -> AST:
     return parser.parse_file(path)
 
 
-def parse_project(paths: list[str], project_path: str | None = None) -> AST:
-    """Parse multiple PHP files into an AST.
+def parse_project(
+    project_path: str,
+    file_filter: "Callable[[Path], bool]" = lambda p: p.suffix == ".php",  # type: ignore
+) -> AST:
+    """Parse all PHP files in a project directory into an AST.
 
-    Creates a project node and multiple file nodes. Each file node
-    contains statements from its corresponding file.
+    Recursively traverses the project directory to find all PHP files,
+    then parses them into a single AST with project and file nodes.
 
     Args:
-        paths: List of file path strings.
-        project_path: Optional project root path. If not provided, computed as common parent.
+        project_path: Project root directory path.
+        file_filter: Function to filter files. Takes a Path and returns
+            True if the file should be parsed. Defaults to checking for `.php` suffix.
 
     Returns:
         AST instance with project -> files -> statements hierarchy.
 
     Raises:
         ParseError: If any file has syntax errors.
-        FileNotFoundError: If any file does not exist.
+        FileNotFoundError: If project directory does not exist.
+        ValueError: If project_path is not a directory.
     """
     parser = Parser()
-    return parser.parse_project(paths, project_path=project_path)
+    return parser.parse_project(project_path, file_filter=file_filter)
 
 
 __version__ = "0.1.0"

{php_parser_py-1.1.0 → 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 = []
@@ -119,7 +109,9 @@ class AST(AbcGraphQuerier[Node, Edge]):
         # Sort by file path for consistent ordering
         return sorted(file_nodes, key=lambda n: n.get_property("filePath", ""))
 
-    def get_file(self, node_id: str) -> Optional[Node]:
+    def get_file(
+        self, node_id: str
+    ) -> Optional[Node]:  # pylint: disable=too-many-return-statements
         """Get the file node that contains the given node.
 
         Traverses upward from the given node via PARENT_OF edges until
@@ -202,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 = []
@@ -215,7 +207,7 @@ class AST(AbcGraphQuerier[Node, Edge]):
                 nodes_with_parents = set()
 
                 for edge_id in self._storage.get_edges():
-                    from_id, to_id, edge_type = edge_id
+                    _, to_id, edge_type = edge_id
                     if edge_type == "PARENT_OF":
                         nodes_with_parents.add(to_id)
 
@@ -253,10 +245,20 @@ class AST(AbcGraphQuerier[Node, Edge]):
 
         return sorted(statement_nodes, key=get_index)
 
-    def _reconstruct_node(self, nid: str) -> dict[str, Any]:
-        """Recursively reconstruct JSON object for a node."""
+    def _reconstruct_node(  # pylint: disable=too-many-locals,too-many-branches,too-many-statements
+        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.
+        """
         props = self._storage.get_node_props(nid)
         if props is None:
+            logger.warning("Node %s not found in storage, returning empty dict", nid)
             return {}
 
         result: dict[str, Any] = {}
@@ -348,10 +350,12 @@ class AST(AbcGraphQuerier[Node, Edge]):
 
         # Add default values for common optional fields that PHP-Parser expects
         if node_type and ("attrGroups" not in result):
-            if (node_type.startswith("Stmt_") or 
-                node_type == "Param" or
-                node_type.startswith("Expr_Closure") or
-                node_type.startswith("Expr_ArrowFunction")):
+            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-1.1.0 → php_parser_py-1.2.0}/src/php_parser_py/_edge.py

@@ -20,7 +20,9 @@ class Edge(AbcEdgeQuerier):
         _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:
+    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:

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

@@ -3,14 +3,15 @@
 import hashlib
 import logging
 from pathlib import Path
-from typing import Any, Optional
+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
 from php_parser_py._node import Node
 from php_parser_py._runner import Runner
-from php_parser_py.exceptions import ParseError, RunnerError
 
 logger = logging.getLogger(__name__)
 
@@ -21,56 +22,19 @@ class Parser:
     Provides three parsing methods:
     - parse_code: Parse code string, returns list of top-level statement nodes
     - parse_file: Parse single file, returns AST with project and file nodes
-    - parse_project: Parse multiple files, returns AST with project and multiple file nodes
+    - parse_project: Parse project directory, returns AST with project and all PHP files
 
     Attributes:
         _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.
-        """
-        self._runner = Runner(
-            php_binary_path=php_binary_path,
-            php_binary_url=php_binary_url,
-        )
-
-    def parse(self, code: str) -> AST:
-        """Parse PHP code string into an AST (backward compatibility).
-
-        Creates a temporary project/file structure. For code-only parsing
-        without project structure, use parse_code() instead.
 
         Args:
-            code: PHP source code string.
-
-        Returns:
-            AST instance with project -> file -> statements hierarchy.
-
-        Raises:
-            ParseError: If code has syntax errors.
-            RunnerError: If PHP execution fails.
+            php: Optional PHP instance. If not provided, uses builtin PHP.
         """
-        import tempfile
-        from pathlib import Path
-        
-        # Create temporary file
-        with tempfile.NamedTemporaryFile(mode='w', suffix='.php', delete=False) as f:
-            f.write(code)
-            temp_path = f.name
-        
-        try:
-            return self.parse_file(temp_path)
-        finally:
-            Path(temp_path).unlink()
+        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.
@@ -94,7 +58,7 @@ class Parser:
             if "Syntax error" in str(e):
                 raise ParseError("Syntax error in PHP code", line=1) from e
             raise
-        
+
         # Normalize to list
         if not isinstance(json_data, list):
             json_data = [json_data]
@@ -105,7 +69,9 @@ class Parser:
         node_counter = [1]  # Use list to allow mutation in recursive calls
 
         for item in json_data:
-            node_id = self._process_node(storage, item, None, None, None, node_counter, "")
+            node_id = self._process_node(
+                storage, item, None, None, None, node_counter, ""
+            )
             if node_id:
                 node_ids.append(node_id)
 
@@ -140,7 +106,7 @@ class Parser:
         file_hash = hashlib.md5(str(file_path).encode()).hexdigest()[:8]
 
         code = file_path.read_text(encoding="utf-8")
-        
+
         try:
             json_data = self._runner.parse(code)
         except RunnerError as e:
@@ -153,63 +119,69 @@ class Parser:
             json_data = [json_data]
 
         storage = self._create_project_structure(
-            [(file_path, json_data)], 
+            [(file_path, json_data)],
             [(file_path, file_hash)],
-            project_path=project_path
+            project_path=project_path,
         )
         return AST(storage, root_node_id="project")
 
-    def parse_project(self, paths: list[str], project_path: str | None = None) -> AST:
-        """Parse multiple PHP files into an AST with project and file nodes.
+    def parse_project(
+        self,
+        project_path: str,
+        file_filter: Callable[[Path], bool] = lambda p: p.suffix == ".php",
+    ) -> AST:
+        """Parse all PHP files in a project directory into an AST.
 
-        Creates a project node (ID: "project") and multiple file nodes.
+        Recursively traverses the project directory to find all PHP files,
+        then parses them into a single AST with project and file nodes.
         Each file node has ID based on its path hash.
-        Project path is the common parent directory of all files, or the provided project_path.
 
         Args:
-            paths: List of file path strings.
-            project_path: Optional project root path. If not provided, computed as common parent.
+            project_path: Project root directory path.
+            file_filter: Function to filter files. Takes a Path and returns
+                True if the file should be parsed. Defaults to checking for `.php` suffix.
 
         Returns:
             AST instance with project -> files -> statements hierarchy.
 
         Raises:
             ParseError: If any file has syntax errors.
-            FileNotFoundError: If any file does not exist.
+            FileNotFoundError: If project directory does not exist.
+            ValueError: If project_path is not a directory.
         """
+        project_path_obj = Path(project_path).resolve()
+
+        if not project_path_obj.exists():
+            raise FileNotFoundError(f"Project directory not found: {project_path}")
+
+        if not project_path_obj.is_dir():
+            raise ValueError(f"Project path is not a directory: {project_path}")
+
+        # Find all files recursively and filter
+        all_files = project_path_obj.rglob("*")
+        php_files = [f for f in all_files if f.is_file() and file_filter(f)]
+
+        if not php_files:
+            logger.warning(f"No PHP files found in project directory: {project_path}")
+            # Create empty project structure
+            storage = Storage()
+            project_id = "project"
+            storage.add_node(project_id)
+            storage.set_node_props(
+                project_id,
+                {
+                    "nodeType": "Project",
+                    "label": "Project",
+                    "path": str(project_path_obj),
+                },
+            )
+            return AST(storage, root_node_id="project")
+
+        # Prepare file information
         file_infos = []
-        resolved_paths = []
-        for path in paths:
-            file_path = Path(path).resolve()
-            if not file_path.exists():
-                raise FileNotFoundError(f"File not found: {path}")
+        for file_path in php_files:
             file_hash = hashlib.md5(str(file_path).encode()).hexdigest()[:8]
             file_infos.append((file_path, file_hash))
-            resolved_paths.append(file_path)
-
-        # Determine project path
-        if project_path:
-            project_path = Path(project_path).resolve()
-        else:
-            # Compute common parent directory
-            if len(resolved_paths) == 1:
-                project_path = resolved_paths[0].parent
-            else:
-                # Find common parent
-                common_parts = None
-                for file_path in resolved_paths:
-                    parts = file_path.parts
-                    if common_parts is None:
-                        common_parts = parts
-                    else:
-                        # Find common prefix
-                        min_len = min(len(common_parts), len(parts))
-                        common_parts = [p for i, p in enumerate(common_parts[:min_len]) if parts[i] == p]
-                if common_parts:
-                    project_path = Path(*common_parts)
-                else:
-                    # Fallback to first file's parent
-                    project_path = resolved_paths[0].parent
 
         # Parse all files
         all_json_data = []
@@ -225,14 +197,16 @@ class Parser:
                     raise ParseError(f"Syntax error in {file_path}", line=1) from e
                 raise
 
-        storage = self._create_project_structure(all_json_data, file_infos, project_path=project_path)
+        storage = self._create_project_structure(
+            all_json_data, file_infos, project_path=project_path_obj
+        )
         return AST(storage, root_node_id="project")
 
     def _create_project_structure(
         self,
         files_data: list[tuple[Path, Any]],
         file_infos: list[tuple[Path, str]],
-        project_path: Path
+        project_path: Path,
     ) -> Storage:
         """Create AST structure with project -> files -> statements hierarchy.
 
@@ -249,11 +223,10 @@ class Parser:
         # Create project node (fixed ID: "project")
         project_id = "project"
         storage.add_node(project_id)
-        storage.set_node_props(project_id, {
-            "nodeType": "Project",
-            "label": "Project",
-            "path": str(project_path)
-        })
+        storage.set_node_props(
+            project_id,
+            {"nodeType": "Project", "label": "Project", "path": str(project_path)},
+        )
 
         # Create file nodes and process their statements
         for (file_path, file_hash), (_, json_data) in zip(file_infos, files_data):
@@ -267,12 +240,15 @@ class Parser:
             # Create file node (ID: hex hash)
             file_id = file_hash
             storage.add_node(file_id)
-            storage.set_node_props(file_id, {
-                "nodeType": "File",
-                "label": "File",
-                "filePath": str(file_path),  # Absolute path
-                "path": str(relative_path)   # Relative path from project root
-            })
+            storage.set_node_props(
+                file_id,
+                {
+                    "nodeType": "File",
+                    "label": "File",
+                    "filePath": str(file_path),  # Absolute path
+                    "path": str(relative_path),  # Relative path from project root
+                },
+            )
 
             # Link file to project
             edge_id = (project_id, file_id, "PARENT_OF")
@@ -291,7 +267,7 @@ class Parser:
 
         return storage
 
-    def _process_node(
+    def _process_node(  # pylint: disable=too-many-arguments,too-many-locals,too-many-branches
         self,
         storage: Storage,
         node_data: Any,
@@ -299,7 +275,7 @@ class Parser:
         field_name: str | None,
         index: int | None,
         node_counter: list[int],
-        prefix: str
+        prefix: str,
     ) -> str | None:
         """Process a single node and its children recursively.
 
@@ -383,7 +359,13 @@ class Parser:
             else:
                 # Single child object
                 self._process_node(
-                    storage, field_value, node_id, field_name, None, node_counter, prefix
+                    storage,
+                    field_value,
+                    node_id,
+                    field_name,
+                    None,
+                    node_counter,
+                    prefix,
                 )
 
         return node_id