php-parser-py 1.2.4__py3-none-win_amd64.whl

php_parser_py/_runtime/_binary.py

@@ -0,0 +1,113 @@
+"""Resolve the platform PHP binary php-parser-py carries.
+
+The binary is locked to php-parser's supported PHP version and built with
+the tokenizer, json, ctype, and phar extensions. A platform-tagged wheel
+ships the matching host binary pre-extracted under ``_resources``; a source
+or editable install instead carries the platform tar.gz archives, resolved
+through ``static_php_py.PackagedBinary`` on first use.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+from static_php_py import PHP, BinaryNotFoundError, PackagedBinary, Requirements
+
+from .._exceptions import RunnerError
+from ._bundle import get_resources_path
+
+logger = logging.getLogger(__name__)
+
+_PHP_BINARY_NAME = "php.exe" if sys.platform == "win32" else "php"
+# Wheel members are archived with 0o644 permissions, so the pre-extracted
+# binary lands non-executable and needs the bit restored on first resolve.
+_EXECUTABLE_MODE = 0o755
+# Every carried php-cli archive is a PHP 8.5 build (tools/make_wheels.py).
+_PHP_SERIES = "8.5"
+
+# php-parser 5.x requires PHP >= 7.4; the phar runs on the tokenizer,
+# json, and ctype extensions and is loaded through the phar extension.
+# Applied via PHP.require and read by `static-php-build --manifest`.
+REQUIREMENTS = Requirements(
+    version=">=7.4",
+    extensions=frozenset({"tokenizer", "json", "ctype", "phar"}),
+)
+
+# Source and editable installs carry the platform archives as package data;
+# PackagedBinary selects the host's archive and extracts its binary lazily.
+_PACKAGED = PackagedBinary("php_parser_py", series=_PHP_SERIES)
+
+
+def resolve_php() -> PHP:
+    """Resolve php-parser's own carried PHP binary, falling back to PATH.
+
+    When the carried binary is unavailable -- an unbuilt platform or a
+    source install missing the host archive -- falls back to a ``php`` on
+    the system PATH and warns. Both paths run the requirement check, so an
+    unsuitable PHP fails fast rather than silently misparsing.
+
+    Returns:
+        A validated PHP wrapper.
+
+    Raises:
+        RunnerError: When neither the carried binary nor a system PHP can
+            be located.
+        VersionUnsatisfiedError: When the located PHP is older than 7.4.
+        ExtensionUnsatisfiedError: When the located PHP lacks a required
+            extension.
+    """
+    try:
+        php = PHP.local(_carried_binary())
+    except BinaryNotFoundError as carried_error:
+        logger.warning(
+            "Carried PHP binary unavailable (%s); falling back to system PHP",
+            carried_error,
+        )
+        php = _system_php(carried_error)
+    return php.require(REQUIREMENTS)
+
+
+def _carried_binary() -> Path:
+    """Return the binary the package carries as a real filesystem path.
+
+    A platform wheel ships the binary pre-extracted (and archive-free), so
+    it is returned directly with its execute bit restored; a source or
+    editable install resolves through the packaged archives instead.
+
+    Raises:
+        BinaryNotFoundError: When neither the pre-extracted binary nor a
+            matching archive exists, or the platform is unsupported.
+        InvalidArchiveError: When the matching archive holds no PHP member.
+    """
+    pre_extracted = get_resources_path() / _PHP_BINARY_NAME
+    if pre_extracted.exists():
+        if not os.access(pre_extracted, os.X_OK):
+            pre_extracted.chmod(_EXECUTABLE_MODE)
+        return pre_extracted
+    return _PACKAGED.resolve()
+
+
+def _system_php(carried_error: BinaryNotFoundError) -> PHP:
+    """Wrap a ``php`` discovered on the system PATH.
+
+    Args:
+        carried_error: The failure that triggered the fallback, surfaced
+            in the error message when no system PHP exists.
+
+    Returns:
+        A PHP wrapper around the PATH binary.
+
+    Raises:
+        RunnerError: When no php is on PATH.
+    """
+    try:
+        return PHP.system()
+    except BinaryNotFoundError as path_error:
+        raise RunnerError(
+            f"No bundled PHP binary for this platform ({carried_error}) "
+            "and no php on PATH. Install PHP or pass a custom PHP instance.",
+            exit_code=1,
+        ) from path_error

php_parser_py/_runtime/_bundle.py

@@ -0,0 +1,164 @@
+"""Bundled archive location and extraction for php-parser-py.
+
+Handles extraction of the bundled PHP-Parser archive on first use.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import tarfile
+import threading
+from importlib import resources
+from pathlib import Path
+
+# Read granularity for archive hashing; keeps memory flat for large files.
+_HASH_BLOCK_SIZE = 4096
+
+# Root package holding the _resources/ data directory and the vendor
+# extraction target; this module lives in a subpackage, so __package__
+# is not the data anchor.
+_DATA_PACKAGE = "php_parser_py"
+
+# Global lock for thread-safe extraction
+_extraction_lock = threading.Lock()
+_extraction_state: dict[str, bool] = {"done": False}
+
+
+def _package_dir() -> Path:
+    # Anchor package data via importlib.resources, not __file__ arithmetic.
+    return Path(str(resources.files(_DATA_PACKAGE)))
+
+
+def get_vendor_path() -> Path:
+    """Get the path where PHP-Parser should be extracted."""
+    return _package_dir() / "vendor"
+
+
+def get_resources_path() -> Path:
+    """Get the path to the resources directory."""
+    return _package_dir() / "_resources"
+
+
+def get_marker_file() -> Path:
+    """Get the path to the extraction marker file."""
+    return get_vendor_path() / ".extracted"
+
+
+def calculate_archive_hash(archive_path: Path) -> str:
+    """Calculate SHA256 hash of the archive file."""
+    sha256_hash = hashlib.sha256()
+    with open(archive_path, "rb") as f:
+        for byte_block in iter(lambda: f.read(_HASH_BLOCK_SIZE), b""):
+            sha256_hash.update(byte_block)
+    return sha256_hash.hexdigest()
+
+
+def is_already_extracted(archive_path: Path) -> bool:
+    """Check if PHP-Parser has already been extracted.
+
+    Returns:
+        True if the marker file exists and the archive 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(encoding="utf-8").strip()
+        current_hash = calculate_archive_hash(archive_path)
+        return stored_hash == current_hash
+    except OSError:
+        # If we can't read the marker or calculate hash, re-extract
+        return False
+
+
+def extract_php_parser(archive_path: Path, vendor_path: Path) -> None:
+    """Extract PHP-Parser archive to vendor directory.
+
+    Args:
+        archive_path: Path to the php-parser tar.gz archive.
+        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 archive, guarding against path traversal
+    with tarfile.open(archive_path, "r:gz") as tar_ref:
+        _extract_members_safely(tar_ref, vendor_path)
+
+    # Create marker file with archive hash
+    archive_hash = calculate_archive_hash(archive_path)
+    marker_file = get_marker_file()
+    marker_file.write_text(archive_hash, encoding="utf-8")
+
+
+def _extract_members_safely(tar_ref: tarfile.TarFile, vendor_path: Path) -> None:
+    """Extract tar members, rejecting links and escaping paths."""
+    target = vendor_path.resolve()
+    for member in tar_ref.getmembers():
+        # A link member could point outside the target and let a later
+        # member write through it; the archive carries only regular files.
+        if not (member.isfile() or member.isdir()):
+            raise ValueError(
+                f"Archive member {member.name!r} is not a regular file or directory"
+            )
+        destination = (target / member.name).resolve()
+        if not destination.is_relative_to(target):
+            raise ValueError(
+                f"Archive member {member.name!r} escapes the target directory"
+            )
+    tar_ref.extractall(vendor_path)
+
+
+def _find_archive() -> Path:
+    # Locate the single bundled php-parser archive.
+    resources_path = get_resources_path()
+    archive_files = list(resources_path.glob("php-parser-*.tar.gz"))
+    if not archive_files:
+        raise FileNotFoundError(
+            f"PHP-Parser archive not found in {resources_path}. "
+            f"Expected a file matching pattern 'php-parser-*.tar.gz'"
+        )
+    if len(archive_files) > 1:
+        names = ", ".join(sorted(f.name for f in archive_files))
+        raise RuntimeError(
+            f"Multiple PHP-Parser archives found in {resources_path}: "
+            f"{names}. The installation is inconsistent; reinstall the "
+            "package."
+        )
+    return archive_files[0]
+
+
+def ensure_php_parser_extracted() -> Path:
+    """Ensure PHP-Parser is extracted and ready to use.
+
+    Called before any PHP invocation. Thread-safe; extraction runs at
+    most once per process.
+
+    Returns:
+        Path to the vendor directory containing PHP-Parser.
+
+    Raises:
+        FileNotFoundError: If the php-parser archive is not found.
+        RuntimeError: If extraction fails or more than one php-parser
+            archive is bundled.
+    """
+    if _extraction_state["done"]:
+        return get_vendor_path()
+
+    with _extraction_lock:
+        if _extraction_state["done"]:
+            return get_vendor_path()
+
+        archive_path = _find_archive()
+        if not is_already_extracted(archive_path):
+            try:
+                extract_php_parser(archive_path, get_vendor_path())
+            except (OSError, tarfile.TarError, ValueError) as e:
+                raise RuntimeError(
+                    f"Failed to extract PHP-Parser from {archive_path}: {e}"
+                ) from e
+
+        _extraction_state["done"] = True
+        return get_vendor_path()

php_parser_py/_runtime/_runner.py

@@ -0,0 +1,258 @@
+"""Runner class for PHP-Parser invocation."""
+
+from __future__ import annotations
+
+import base64
+import json
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any, cast
+
+from static_php_py import PHP, ExecutionError, ExecutionResult
+
+from .._exceptions import ParseError, RunnerError
+from .._transport import decode_values
+from .._types import PrintMode, PrintRequest
+from ._binary import resolve_php
+from ._bundle import ensure_php_parser_extracted, get_resources_path
+
+# Stdout carries the JSON/base64 protocol; PHP warnings and fatals must
+# never interleave with it, so diagnostics go to stderr on every run.
+_BASE_INI = {"display_errors": "stderr"}
+
+
+def _failure_message(result: ExecutionResult) -> str:
+    # Assemble the RunnerError message carrying the process's full output.
+    message = f"PHP execution failed with exit code {result.return_code}"
+    if result.stderr:
+        message += f"\nStderr: {result.stderr}"
+    if result.stdout:
+        message += f"\nStdout: {result.stdout}"
+    return message
+
+
+class Runner:
+    """Manages PHP-Parser invocation via PHP binary.
+
+    Handles execution of PHP scripts for parsing and code generation,
+    communicating with PHP-Parser through the PHP wrapper's stdin/stdout
+    channel.
+
+    Attributes:
+        _php: PHP binary wrapper executing every invocation.
+        _vendor_dir: Path to directory containing PHP-Parser PHAR.
+        _ini_settings: PHP ini overrides applied as ``-d name=value`` on
+            every invocation; always routes diagnostics to stderr.
+    """
+
+    def __init__(
+        self,
+        php: PHP | None = None,
+        ini_settings: Mapping[str, str] | None = None,
+    ) -> None:
+        """Initialize Runner with PHP binary wrapper.
+
+        Args:
+            php: Optional PHP instance. If not provided, uses the bundled
+                binary, falling back to a system PHP on PATH.
+            ini_settings: Optional PHP ini overrides (e.g. ``memory_limit``)
+                passed as ``-d name=value`` on every invocation. Default
+                None inherits the binary's environment.
+
+        Raises:
+            RunnerError: If no usable PHP binary can be located.
+        """
+        self._vendor_dir = ensure_php_parser_extracted()
+        self._php = php if php is not None else resolve_php()
+        self._ini_settings: Mapping[str, str] = {
+            **_BASE_INI,
+            **(ini_settings or {}),
+        }
+
+    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.
+        """
+        return self._run_php(
+            lambda: self._php.eval(script, input=stdin, ini=self._ini_settings)
+        )
+
+    def _run_php(self, invoke: Callable[[], ExecutionResult]) -> str:
+        """Run one PHP invocation and return its stdout.
+
+        Args:
+            invoke: Zero-argument call into the PHP wrapper (``run`` or
+                ``eval`` with its arguments bound).
+
+        Returns:
+            Process stdout.
+
+        Raises:
+            RunnerError: If PHP execution fails.
+        """
+        try:
+            result = invoke()
+        except (ExecutionError, FileNotFoundError) as e:
+            raise RunnerError(
+                f"Failed to execute PHP script: {e}", stderr=str(e), exit_code=1
+            ) from e
+
+        if not result.success:
+            raise RunnerError(
+                _failure_message(result),
+                stderr=result.stderr,
+                exit_code=result.return_code,
+            )
+        return result.stdout
+
+    def parse(self, code: str) -> list[dict[str, Any]]:
+        """Invoke PHP-Parser parse + JsonSerializer.
+
+        Args:
+            code: PHP source code to parse.
+
+        Returns:
+            Parsed statements as a list of PHP-Parser JSON node dicts.
+
+        Raises:
+            ParseError: If PHP-Parser reports syntax error.
+            RunnerError: If PHP execution fails or emits a malformed payload.
+        """
+        stdin = self._build_parse_stdin(code)
+
+        try:
+            output = self._execute_script_file("parse.php", stdin)
+            # Restore raw bytes and non-finite floats parse.php marker-wrapped.
+            result = decode_values(json.loads(output))
+        except json.JSONDecodeError as e:
+            raise RunnerError(
+                f"Failed to decode PHP-Parser JSON output: {e}",
+                stderr=str(e),
+                exit_code=1,
+            ) from e
+        except RecursionError as e:
+            raise RunnerError(
+                "AST is nested too deeply to decode: Python's recursion limit "
+                "was reached while reading the PHP-Parser JSON output",
+                stderr=str(e),
+                exit_code=1,
+            ) from e
+
+        return self._normalize_payload(result)
+
+    @staticmethod
+    def _normalize_payload(result: object) -> list[dict[str, Any]]:
+        """Validate the decoded parse payload at the channel boundary.
+
+        An errors envelope is only ever emitted on syntax failure; one with
+        no entries is a malformed tool result, not an AST payload. A lone
+        node dict is wrapped so callers always receive a statement list.
+
+        Raises:
+            ParseError: Built from the first entry of the errors payload.
+            RunnerError: On an empty envelope or an unexpected payload shape
+                (fail-fast; no silent ``[]``).
+        """
+        if isinstance(result, dict) and "errors" in result:
+            errors = result["errors"]
+            if not errors:
+                raise RunnerError(
+                    "PHP-Parser returned an error envelope with no error details",
+                    exit_code=1,
+                )
+            raise ParseError(
+                errors[0].get("message", "Unknown parse error"),
+                errors[0].get("line"),
+            )
+        if isinstance(result, list):
+            return result
+        if isinstance(result, dict):
+            return [result]
+        raise RunnerError(
+            "PHP-Parser produced a malformed payload: expected list or dict, "
+            f"got {type(result).__name__}"
+        )
+
+    def print(self, request: PrintRequest) -> str:
+        """Render and run the print script for one file.
+
+        Args:
+            request: Print inputs (printer class, mode, statements, origin).
+
+        Returns:
+            Generated PHP source code.
+
+        Raises:
+            RunnerError: If PHP execution fails.
+        """
+        stdin = self._build_print_stdin(request)
+        output = self._execute_script_file("print.php", stdin)
+        # print.php base64-encodes its output so non-UTF-8 source bytes survive
+        # the text stdout channel; recover the exact bytes back to a str.
+        return base64.b64decode(output).decode("utf-8", "surrogateescape")
+
+    def _build_parse_stdin(self, code: str) -> str:
+        """Pack the parse inputs into a single JSON stdin payload.
+
+        The code field travels as base64: PHP source may legally hold raw
+        non-UTF-8 bytes (carried here as surrogate escapes), and JSON can
+        transport neither those bytes nor lone-surrogate escapes.
+        """
+        raw = code.encode("utf-8", "surrogateescape")
+        payload = {
+            "phar_path": str(self._phar_path()),
+            "code": base64.b64encode(raw).decode("ascii"),
+        }
+        return json.dumps(payload)
+
+    def _build_print_stdin(self, request: PrintRequest) -> str:
+        """Pack the print inputs into a single JSON stdin payload.
+
+        The printer class name travels as the ``printer_class`` field; it is
+        read as data by ``print.php`` and never interpolated into PHP source.
+        """
+        payload: dict[str, str] = {
+            "phar_path": str(self._phar_path()),
+            "extended_path": str(get_resources_path() / "ExtendedPrinter.php"),
+            "printer_class": request.php_class,
+            "mode": request.mode.value,
+            "stmts": request.stmts_json,
+        }
+        if request.mode is PrintMode.FORMAT_PRESERVING:
+            # Original source may hold non-UTF-8 bytes (e.g. Latin-1 literals).
+            # JSON is UTF-8 only, so transport the raw bytes as base64 rather
+            # than letting an invalid sequence break PHP's json_decode.
+            raw = cast(str, request.orig_source).encode("utf-8", "surrogateescape")
+            payload["orig_source"] = base64.b64encode(raw).decode("ascii")
+        return json.dumps(payload)
+
+    def _phar_path(self) -> Path:
+        """Absolute path to the bundled php-parser PHAR."""
+        return self._vendor_dir / "php-parser.phar"
+
+    def _execute_script_file(self, script_name: str, stdin: str) -> str:
+        """Run a static ``.php`` resource file with a JSON stdin payload.
+
+        Args:
+            script_name: File name under ``_resources`` (e.g. ``parse.php``).
+            stdin: Single JSON payload piped to the script.
+
+        Returns:
+            Script stdout.
+
+        Raises:
+            RunnerError: If PHP execution fails.
+        """
+        script_path = get_resources_path() / script_name
+        return self._run_php(
+            lambda: self._php.run(script_path, input=stdin, ini=self._ini_settings)
+        )

php_parser_py/_transport.py

@@ -0,0 +1,104 @@
+"""Byte-safe value codec for the PHP JSON channel.
+
+JSON is UTF-8 only and rejects non-finite floats, but PHP source and
+string values are raw bytes (carried on the Python side as
+surrogate-escaped ``str``) and PHP float values may be INF or NAN. A
+value that cannot travel as strict JSON is wrapped in a NUL-prefixed
+marker string; ``_resources/transport.php`` applies the same codec on
+the PHP side.
+"""
+
+from __future__ import annotations
+
+import base64
+import math
+from collections.abc import Callable
+
+# NUL-prefixed so no printable value collides by accident; a legitimate
+# string that does start with a marker prefix is escaped by wrapping it
+# in the string marker too.
+_STR_MARKER = "\x00pppy\x00"
+_FLOAT_MARKER = "\x00pppyf\x00"
+_MARKER_PREFIX = "\x00pppy"  # common prefix of both markers
+
+
+def encode_values(value: object) -> object:
+    """Wrap channel-unsafe values for the Python -> PHP channel.
+
+    Returns a new tree; the input is never mutated.
+    """
+    return _transform_tree(value, _encode_value)
+
+
+def decode_values(value: object) -> object:
+    """Restore marker-wrapped values from the PHP -> Python channel.
+
+    Returns a new tree; the input is never mutated.
+    """
+    return _transform_tree(value, _decode_value)
+
+
+def _transform_tree(value: object, transform: Callable[[object], object]) -> object:
+    # Iterative walk: a recursive one would halve the nesting depth the
+    # channel can carry, failing ASTs json.loads itself handles fine.
+    # A new tree is built because the input may hold live graph-owned
+    # containers (serialize passes node property values by reference).
+    stack: list[tuple[object, object]] = []
+    result = _transform_item(value, transform, stack)
+    while stack:
+        source, target = stack.pop()
+        if isinstance(source, list) and isinstance(target, list):
+            target.extend(_transform_item(item, transform, stack) for item in source)
+        elif isinstance(source, dict) and isinstance(target, dict):
+            for key, item in source.items():
+                target[key] = _transform_item(item, transform, stack)
+        else:
+            raise TypeError(f"Mismatched walk pair: {type(source)}, {type(target)}")
+    return result
+
+
+def _transform_item(
+    item: object,
+    transform: Callable[[object], object],
+    stack: list[tuple[object, object]],
+) -> object:
+    # Transform leaf values; defer containers onto the walk stack, paired
+    # with the empty shell that receives their transformed items.
+    if isinstance(item, (list, dict)):
+        shell: list[object] | dict[str, object] = [] if isinstance(item, list) else {}
+        stack.append((item, shell))
+        return shell
+    return transform(item)
+
+
+def _encode_value(value: object) -> object:
+    if isinstance(value, str):
+        return _encode_str(value)
+    # bool is an int subtype, not a float, so it never matches here.
+    if isinstance(value, float) and not math.isfinite(value):
+        return _FLOAT_MARKER + repr(value)
+    return value
+
+
+def _decode_value(value: object) -> object:
+    if not isinstance(value, str) or not value.startswith(_MARKER_PREFIX):
+        return value
+    if value.startswith(_STR_MARKER):
+        raw = base64.b64decode(value[len(_STR_MARKER) :])
+        return raw.decode("utf-8", "surrogateescape")
+    if value.startswith(_FLOAT_MARKER):
+        return float(value[len(_FLOAT_MARKER) :])
+    return value
+
+
+def _encode_str(value: str) -> str:
+    # Surrogate escapes would serialize as invalid lone-surrogate JSON;
+    # a marker-prefixed string would be mis-decoded on the other side.
+    if not value.startswith(_MARKER_PREFIX):
+        try:
+            value.encode("utf-8")
+            return value
+        except UnicodeEncodeError:
+            pass
+    raw = value.encode("utf-8", "surrogateescape")
+    return _STR_MARKER + base64.b64encode(raw).decode("ascii")