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

php_parser_py/_parser.py

@@ -0,0 +1,207 @@
+"""Parser class for PHP code parsing."""
+
+import hashlib
+import logging
+from pathlib import Path
+from typing import Any, Optional
+
+from cpg2py import Storage
+
+from php_parser_py._ast import AST
+from php_parser_py._runner import Runner
+from php_parser_py.exceptions import ParseError, RunnerError
+
+logger = logging.getLogger(__name__)
+
+
+class 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.
+
+    Attributes:
+        _runner: Runner instance for PHP-Parser invocation.
+    """
+
+    def __init__(
+        self,
+        php_binary_path: Optional[Path] = None,
+        php_binary_url: Optional[str] = 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,
+        )
+        self._node_counter = 0
+
+    def parse(self, code: str, prefix: str = "") -> AST:
+        """Parse PHP code into an AST.
+
+        Args:
+            code: PHP source code to parse.
+            prefix: Optional prefix for node IDs. Useful for distinguishing
+                   nodes from different files when merging multiple ASTs.
+
+        Returns:
+            AST instance containing parsed code.
+
+        Raises:
+            ParseError: If code has syntax errors.
+            RunnerError: If PHP execution fails.
+        """
+        # Reset node counter for each parse
+        self._node_counter = 0
+        self._node_id_prefix = prefix
+        
+        try:
+            json_data = self._runner.parse(code)
+        except RunnerError as e:
+            # Check if it's a parse error
+            if "Syntax error" in str(e):
+                raise ParseError("Syntax error in PHP code", line=1) from e
+            raise
+        
+        storage = self._json_to_storage(json_data)
+        return AST(storage)
+
+    def parse_file(self, path: str, prefix: str | None = None) -> AST:
+        """Read and parse PHP file.
+
+        Args:
+            path: File path string.
+            prefix: Optional prefix for node IDs. If not provided,
+                   uses a hash of the file path (first 6 chars).
+
+        Returns:
+            AST instance containing parsed code structure.
+
+        Raises:
+            ParseError: If PHP-Parser reports syntax error.
+            FileNotFoundError: If file does not exist.
+        """
+        file_path = Path(path)
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        # Use file path hash as default prefix if none provided
+        if prefix is None:
+            # Generate a short hash from the file path
+            path_hash = hashlib.md5(str(file_path).encode()).hexdigest()[:6]
+            prefix = path_hash
+
+        code = file_path.read_text(encoding="utf-8")
+        return self.parse(code, prefix=prefix)
+
+    def _json_to_storage(self, json_data: Any) -> Storage:
+        """Convert PHP-Parser JSON to cpg2py Storage.
+
+        Args:
+            json_data: JSON data from PHP-Parser.
+
+        Returns:
+            Storage instance containing the AST graph.
+        """
+        storage = Storage()
+
+        # Handle both single node and array of nodes
+        if isinstance(json_data, list):
+            for item in json_data:
+                self._process_node(storage, item, None, None, None)
+        else:
+            self._process_node(storage, json_data, None, None, None)
+
+        return storage
+
+    def _process_node(
+        self,
+        storage: Storage,
+        node_data: Any,
+        parent_id: str | None,
+        field_name: str | None,
+        index: int | None,
+    ) -> str | None:
+        """Process a single node and its children recursively.
+
+        Args:
+            storage: Storage to populate.
+            node_data: JSON node data.
+            parent_id: Parent node ID if this is a child.
+            field_name: Field name in parent if this is a child.
+            index: Array index if this is an array element.
+
+        Returns:
+            Node ID if a node was created, None otherwise.
+        """
+        if node_data is None:
+            return None
+
+        if not isinstance(node_data, dict):
+            return None
+
+        # Only create nodes for objects with nodeType
+        if "nodeType" not in node_data:
+            return None
+
+        # Generate unique node ID
+        node_id = f"node_{self._node_counter}"
+        self._node_counter += 1
+
+        # Collect node properties
+        properties: dict[str, Any] = {}
+        child_fields: list[tuple[str, Any]] = []
+
+        for key, value in node_data.items():
+            if key == "attributes":
+                # Flatten attributes to node properties
+                if isinstance(value, dict):
+                    properties.update(value)
+            elif isinstance(value, dict):
+                # Nested object - will create child node
+                child_fields.append((key, value))
+            elif isinstance(value, list):
+                # Check if it's an array of objects or scalars
+                if value and isinstance(value[0], dict):
+                    # Array of objects - create child nodes
+                    child_fields.append((key, value))
+                else:
+                    # Array of scalars (strings, numbers, etc.) - save as property
+                    properties[key] = value
+            else:
+                # Scalar property
+                properties[key] = value
+
+        # Add node to storage (cpg2py API: add_node takes only nid)
+        storage.add_node(node_id)
+        # Set properties separately
+        if properties:
+            storage.set_node_props(node_id, properties)
+
+        # Create edge from parent if applicable
+        if parent_id is not None and field_name is not None:
+            edge_props = {"field": field_name}
+            if index is not None:
+                edge_props["index"] = index
+            # add_edge takes edge_id as a tuple
+            edge_id = (parent_id, node_id, "PARENT_OF")
+            storage.add_edge(edge_id)
+            if edge_props:
+                storage.set_edge_props(edge_id, edge_props)
+
+        # Process child fields (only object arrays now)
+        for field_name, field_value in child_fields:
+            if isinstance(field_value, list):
+                # Array of child objects
+                for idx, item in enumerate(field_value):
+                    self._process_node(storage, item, node_id, field_name, idx)
+            else:
+                # Single child object
+                self._process_node(storage, field_value, node_id, field_name, None)
+
+        return node_id

php_parser_py/_printer.py

@@ -0,0 +1,52 @@
+"""PrettyPrinter class for PHP code generation."""
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from php_parser_py._ast import AST
+from php_parser_py._runner import Runner
+
+logger = logging.getLogger(__name__)
+
+
+class 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.
+
+    Attributes:
+        _runner: Runner instance for PHP-Parser invocation.
+    """
+
+    def __init__(
+        self,
+        php_binary_path: Optional[Path] = None,
+        php_binary_url: Optional[str] = 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.
+        """
+        self._runner = Runner(
+            php_binary_path=php_binary_path,
+            php_binary_url=php_binary_url,
+        )
+
+    def print(self, ast: AST) -> str:
+        """Generate PHP code from AST.
+
+        Args:
+            ast: AST instance to convert to code.
+
+        Returns:
+            Generated PHP source code string.
+
+        Raises:
+            RunnerError: If PHP-Parser execution fails.
+        """
+        json_str = ast.to_json()
+        return self._runner.print(json_str)

php_parser_py/_resources.py

@@ -0,0 +1,157 @@
+"""
+Resource management for php-parser-py.
+
+Handles extraction of bundled PHP-Parser zip file on first import.
+"""
+
+import hashlib
+import threading
+import zipfile
+from pathlib import Path
+from typing import Optional
+
+# Global lock for thread-safe extraction
+_extraction_lock = threading.Lock()
+_extraction_done = False
+
+
+def get_vendor_path() -> Path:
+    """Get the path where PHP-Parser should be extracted."""
+    return Path(__file__).parent / "vendor"
+
+
+def get_resources_path() -> Path:
+    """Get the path to the resources directory."""
+    # Resources are inside the package directory
+    return Path(__file__).parent / "resources"
+
+
+def get_marker_file() -> Path:
+    """Get the path to the extraction marker file."""
+    return get_vendor_path() / ".extracted"
+
+
+def calculate_zip_hash(zip_path: Path) -> str:
+    """Calculate SHA256 hash of the zip file."""
+    sha256_hash = hashlib.sha256()
+    with open(zip_path, "rb") as f:
+        for byte_block in iter(lambda: f.read(4096), b""):
+            sha256_hash.update(byte_block)
+    return sha256_hash.hexdigest()
+
+
+def is_already_extracted(zip_path: Path) -> bool:
+    """
+    Check if PHP-Parser has already been extracted.
+
+    Returns True if the marker file exists and the zip hash matches.
+    """
+    marker_file = get_marker_file()
+    if not marker_file.exists():
+        return False
+
+    # Check if hash matches
+    try:
+        stored_hash = marker_file.read_text().strip()
+        current_hash = calculate_zip_hash(zip_path)
+        return stored_hash == current_hash
+    except Exception:
+        # If we can't read the marker or calculate hash, re-extract
+        return False
+
+
+def extract_php_parser(zip_path: Path, vendor_path: Path) -> None:
+    """
+    Extract PHP-Parser zip file to vendor directory.
+
+    Args:
+        zip_path: Path to the php-parser zip file
+        vendor_path: Path where files should be extracted
+    """
+    # Create vendor directory if it doesn't exist
+    vendor_path.mkdir(parents=True, exist_ok=True)
+
+    # Extract the zip file
+    with zipfile.ZipFile(zip_path, "r") as zip_ref:
+        zip_ref.extractall(vendor_path)
+
+    # Create marker file with zip hash
+    zip_hash = calculate_zip_hash(zip_path)
+    marker_file = get_marker_file()
+    marker_file.write_text(zip_hash)
+
+
+def ensure_php_parser_extracted() -> Path:
+    """
+    Ensure PHP-Parser is extracted and ready to use.
+
+    This function is called on package import. It checks if PHP-Parser
+    has already been extracted, and if not, extracts it in a thread-safe manner.
+
+    Returns:
+        Path to the vendor directory containing PHP-Parser
+
+    Raises:
+        FileNotFoundError: If the php-parser zip file is not found
+        RuntimeError: If extraction fails
+    """
+    global _extraction_done
+
+    # Fast path: already extracted in this process
+    if _extraction_done:
+        return get_vendor_path()
+
+    vendor_path = get_vendor_path()
+    resources_path = get_resources_path()
+
+    # Find the php-parser zip file
+    zip_files = list(resources_path.glob("php-parser-*.zip"))
+    if not zip_files:
+        raise FileNotFoundError(
+            f"PHP-Parser zip file not found in {resources_path}. "
+            f"Expected a file matching pattern 'php-parser-*.zip'"
+        )
+
+    zip_path = zip_files[0]
+
+    # Check if already extracted (with marker file)
+    if is_already_extracted(zip_path):
+        _extraction_done = True
+        return vendor_path
+
+    # Thread-safe extraction
+    with _extraction_lock:
+        # Double-check after acquiring lock (another thread might have extracted)
+        if is_already_extracted(zip_path):
+            _extraction_done = True
+            return vendor_path
+
+        try:
+            # Extract PHP-Parser
+            extract_php_parser(zip_path, vendor_path)
+            _extraction_done = True
+            return vendor_path
+
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to extract PHP-Parser from {zip_path}: {e}"
+            ) from e
+
+
+def get_php_parser_path() -> Optional[Path]:
+    """
+    Get the path to the extracted PHP-Parser directory.
+
+    Returns:
+        Path to PHP-Parser, or None if not yet extracted
+    """
+    vendor_path = get_vendor_path()
+    if not vendor_path.exists():
+        return None
+
+    # Look for the php-parser directory inside vendor
+    php_parser_dirs = list(vendor_path.glob("php-parser-*"))
+    if php_parser_dirs:
+        return php_parser_dirs[0]
+
+    return None

php_parser_py/_runner.py

@@ -0,0 +1,239 @@
+"""Runner class for PHP-Parser invocation."""
+
+import json
+import logging
+import subprocess
+from pathlib import Path
+from typing import Any, Optional
+
+from static_php_py import PHP
+from static_php_py.exceptions import BinaryNotFoundError, DownloadError
+
+from php_parser_py._resources import ensure_php_parser_extracted
+from php_parser_py.exceptions import ParseError, RunnerError
+
+logger = logging.getLogger(__name__)
+
+
+class Runner:
+    """Manages PHP-Parser invocation via PHP binary.
+
+    Handles execution of PHP scripts for parsing and code generation,
+    communicating with PHP-Parser through subprocess stdin/stdout.
+
+    Attributes:
+        _php_binary: Path to PHP binary.
+        _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.
+
+        Args:
+            php_binary_path: Optional path to local PHP binary.
+            php_binary_url: Optional URL to download PHP binary from.
+
+        Raises:
+            RunnerError: If PHP binary or PHP-Parser 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()
+
+        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.",
+                exit_code=1,
+            ) from e
+        except DownloadError as e:
+            raise RunnerError(
+                f"Failed to download PHP binary: {e}",
+                exit_code=1,
+            ) from e
+
+        if not self._php_binary.exists():
+            raise RunnerError(
+                f"PHP binary not found at {self._php_binary}", exit_code=1
+            )
+
+    def execute(self, script: str, stdin: str = "") -> str:
+        """Execute PHP script with optional stdin.
+
+        Args:
+            script: PHP script code to execute.
+            stdin: Optional input to pass to script's stdin.
+
+        Returns:
+            Script's stdout output.
+
+        Raises:
+            RunnerError: If PHP execution fails.
+        """
+        try:
+            result = subprocess.run(
+                [str(self._php_binary), "-r", script],
+                input=stdin,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            if result.returncode != 0:
+                # Log complete error information
+                error_msg = f"PHP execution failed with exit code {result.returncode}"
+                if result.stderr:
+                    logger.error(f"PHP stderr: {result.stderr}")
+                    error_msg += f"\nStderr: {result.stderr}"
+                if result.stdout:
+                    logger.error(f"PHP stdout: {result.stdout}")
+                    error_msg += f"\nStdout: {result.stdout}"
+                
+                raise RunnerError(
+                    error_msg,
+                    stderr=result.stderr,
+                    exit_code=result.returncode,
+                )
+
+            return result.stdout
+
+        except FileNotFoundError as e:
+            error_msg = f"PHP binary not found: {self._php_binary}"
+            logger.error(error_msg)
+            raise RunnerError(
+                error_msg, stderr=str(e), exit_code=1
+            ) from e
+        except Exception as e:
+            error_msg = f"Failed to execute PHP script: {e}"
+            logger.error(error_msg)
+            # Don't wrap the error if it's already a RunnerError
+            if isinstance(e, RunnerError):
+                raise
+            raise RunnerError(
+                error_msg, stderr=str(e), exit_code=1
+            ) from e
+
+    def parse(self, code: str) -> dict[str, Any]:
+        """Invoke PHP-Parser parse + JsonSerializer.
+
+        Args:
+            code: PHP source code to parse.
+
+        Returns:
+            Parsed JSON as dict.
+
+        Raises:
+            ParseError: If PHP-Parser reports syntax error.
+            RunnerError: If PHP execution fails.
+        """
+        parse_script = self._build_parse_script()
+
+        try:
+            output = self.execute(parse_script, code)
+            result = json.loads(output)
+
+            # Check for parse errors
+            if isinstance(result, dict) and "errors" in result:
+                errors = result["errors"]
+                if errors:
+                    first_error = errors[0]
+                    raise ParseError(
+                        first_error.get("message", "Unknown parse error"),
+                        first_error.get("line"),
+                    )
+
+            return result
+
+        except json.JSONDecodeError as e:
+            raise RunnerError(
+                f"Failed to decode PHP-Parser JSON output: {e}",
+                stderr=str(e),
+                exit_code=1,
+            ) from e
+
+    def print(self, ast_json: str) -> str:
+        """Invoke PHP-Parser JsonDecoder + PrettyPrinter.
+
+        Args:
+            ast_json: AST JSON string from PHP-Parser format.
+
+        Returns:
+            Generated PHP source code.
+
+        Raises:
+            RunnerError: If PHP execution fails.
+        """
+        print_script = self._build_print_script()
+        return self.execute(print_script, ast_json)
+
+    def _build_parse_script(self) -> str:
+        """Build PHP script for parsing."""
+        phar_path = self._vendor_dir / "php-parser.phar"
+        return f"""
+error_reporting(E_ALL & ~E_DEPRECATED);
+require_once 'phar://{phar_path}/vendor/autoload.php';
+
+use PhpParser\\ParserFactory;
+use PhpParser\\ErrorHandler\\Collecting;
+
+$code = file_get_contents('php://stdin');
+$errorHandler = new Collecting();
+$parser = (new ParserFactory())->createForNewestSupportedVersion();
+
+try {{
+    $stmts = $parser->parse($code, $errorHandler);
+    if ($errorHandler->hasErrors()) {{
+        $errors = array_map(fn($e) => [
+            'message' => $e->getMessage(),
+            'line' => $e->getStartLine()
+        ], $errorHandler->getErrors());
+        echo json_encode(['errors' => $errors]);
+        exit(1);
+    }}
+    // PHP-Parser nodes implement JsonSerializable, so we can encode them directly
+    echo json_encode($stmts);
+}} catch (Exception $e) {{
+    echo json_encode(['error' => $e->getMessage()]);
+    exit(1);
+}}
+"""
+
+    def _build_print_script(self) -> str:
+        """Build PHP script for code generation."""
+        phar_path = self._vendor_dir / "php-parser.phar"
+        return f"""
+error_reporting(E_ALL & ~E_DEPRECATED);
+require_once 'phar://{phar_path}/vendor/autoload.php';
+
+use PhpParser\\JsonDecoder;
+use PhpParser\\PrettyPrinter\\Standard;
+
+$json = file_get_contents('php://stdin');
+
+try {{
+    $decoder = new JsonDecoder();
+    $stmts = $decoder->decode($json);
+    $printer = new Standard();
+    echo $printer->prettyPrintFile($stmts);
+}} catch (Exception $e) {{
+    echo json_encode(['error' => $e->getMessage()]);
+    exit(1);
+}}
+"""

php_parser_py/exceptions.py

@@ -0,0 +1,44 @@
+"""Exception classes for php-parser-py."""
+
+
+class ParseError(Exception):
+    """Raised when PHP-Parser reports a syntax error.
+
+    Attributes:
+        message: Error message from PHP-Parser.
+        line: Line number where the error occurred, if available.
+    """
+
+    def __init__(self, message: str, line: int | None = None) -> None:
+        """Initialize ParseError.
+
+        Args:
+            message: Error message from PHP-Parser.
+            line: Line number where the error occurred, if available.
+        """
+        super().__init__(message)
+        self.message = message
+        self.line = line
+
+
+class RunnerError(Exception):
+    """Raised when PHP process execution fails.
+
+    Attributes:
+        message: Error message describing the failure.
+        stderr: Standard error output from the PHP process.
+        exit_code: Exit code returned by the PHP process.
+    """
+
+    def __init__(self, message: str, stderr: str = "", exit_code: int = 1) -> None:
+        """Initialize RunnerError.
+
+        Args:
+            message: Error message describing the failure.
+            stderr: Standard error output from the PHP process.
+            exit_code: Exit code returned by the PHP process.
+        """
+        super().__init__(message)
+        self.message = message
+        self.stderr = stderr
+        self.exit_code = exit_code

php_parser_py/vendor/.extracted

@@ -0,0 +1 @@
+343eb3b32948b6de28c0ca109eafb789dfd270c01711f5721f3cd18b4c0ab614