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

php_parser_py/_mapping/_serialize.py

@@ -0,0 +1,220 @@
+"""Backward direction: AST graph -> PHP-Parser JSON.
+
+Stateless reconstruction behind the module-level ``serialize`` entry point,
+the backward public surface of the mapping package.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .._graph import AST, Edge
+from .._transport import encode_values
+from .._types import PARENT_OF_EDGE
+from ._contract import ATTRIBUTE_KEYS_PROPERTY, LIST_LENGTHS_PROPERTY
+
+
+def _parent_of(edge: Edge) -> bool:
+    # succ() follows every edge type; reconstruction walks only the tree,
+    # so caller-added analysis edges (DATA_FLOW, ...) must not surface
+    # children twice or drag in nodes that are not tree children.
+    return edge.type == PARENT_OF_EDGE
+
+
+def _edge_index(edge: Edge) -> int | None:
+    # A bool or negative index would silently misplace or overwrite a
+    # sibling in _fill_arrays; any other non-int breaks ordering. One
+    # validation point for both _file_statements and _reconstruct_children.
+    index = edge.get("index")
+    if index is None:
+        return None
+    if isinstance(index, int) and not isinstance(index, bool) and index >= 0:
+        return index
+    raise ValueError(
+        f"Edge index must be a non-negative int, got {index!r} on edge "
+        f"{edge.from_nid!r} -> {edge.to_nid!r}"
+    )
+
+
+def serialize(ast: AST, file_hash: str | None = None) -> str:
+    """Reconstruct PHP-Parser JSON from an ``AST``.
+
+    Backward entry of the mapping package; inverse of ``build``.
+
+    Args:
+        ast: Populated AST to export.
+        file_hash: When set, exports only that file's statements; otherwise
+            exports all files, or the code root's statements when no file
+            structure exists.
+
+    Returns:
+        JSON string compatible with PHP-Parser's JsonDecoder.
+
+    Raises:
+        KeyError: If ``file_hash`` — or, lacking file structure, the code
+            root node — is not in ``ast``.
+        ValueError: If two children of one node occupy the same
+            (field, index) slot, or PARENT_OF edges do not form a tree
+            (cycle or shared subtree).
+    """
+    top_level = _top_level_ids(ast, file_hash)
+    result = [_reconstruct_node(ast, nid) for nid in top_level]
+    # Marker-wrap surrogate-bearing strings and non-finite floats:
+    # json.dumps would emit lone-surrogate escapes or Infinity/NaN tokens
+    # that PHP's json_decode rejects. allow_nan=False turns any value the
+    # codec missed into a loud error instead of invalid JSON.
+    return json.dumps(encode_values(result), allow_nan=False)
+
+
+def _top_level_ids(ast: AST, file_hash: str | None) -> list[str]:
+    # Resolve the root node IDs to export. Top-level membership is always
+    # an explicit stmts edge from an anchor (file node or code root);
+    # subtrees detached by remove_node are never exported.
+    if file_hash:
+        return statement_ids(ast, file_hash)
+    file_nodes = ast.file_nodes()
+    if file_nodes:
+        collected: list[str] = []
+        for file_node in file_nodes:
+            collected.extend(statement_ids(ast, file_node.id))
+        return collected
+    return statement_ids(ast, ast.project_root_id)
+
+
+def statement_ids(ast: AST, parent_id: str) -> list[str]:
+    """Top-level statement IDs anchored under a file or code-root node.
+
+    Args:
+        ast: Graph to query.
+        parent_id: File node ID, or the code root ID for code-only ASTs.
+
+    Returns:
+        Targets of the anchor's ``stmts`` PARENT_OF edges, ordered by
+        edge index.
+
+    Raises:
+        KeyError: If ``parent_id`` is not in ``ast``.
+        ValueError: If an edge carries an invalid index.
+    """
+    anchor = ast.node(parent_id)
+    ordered: list[tuple[tuple[int, int], str]] = []
+    for child in ast.succ(anchor, _parent_of):
+        edge = ast.edge(parent_id, child.id, PARENT_OF_EDGE)
+        if edge.get("field") != "stmts":
+            continue
+        ordered.append((_sort_key(_edge_index(edge)), child.id))
+    ordered.sort(key=lambda pair: pair[0])
+    return [nid for _, nid in ordered]
+
+
+def _reconstruct_node(ast: AST, nid: str) -> dict[str, Any]:
+    # Rebuild one node's JSON subtree, inverse of _process_node.
+    # Explicit-stack DFS: recursion would cap the AST depth at a fraction
+    # of the interpreter stack, failing trees json.dumps itself handles.
+    root = _node_result(ast, nid)
+    visited = {nid}
+    stack: list[tuple[str, dict[str, Any]]] = [(nid, root)]
+    while stack:
+        current_id, result = stack.pop()
+        for child_id, child_json in _reconstruct_children(ast, result, current_id):
+            # A node reached twice means a PARENT_OF cycle or a shared
+            # subtree; without this guard a cycle would loop the walk
+            # forever.
+            if child_id in visited:
+                raise ValueError(
+                    f"Node {child_id!r} reached twice via {current_id!r}; "
+                    "PARENT_OF edges must form a tree"
+                )
+            visited.add(child_id)
+            stack.append((child_id, child_json))
+    return root
+
+
+def _node_result(ast: AST, nid: str) -> dict[str, Any]:
+    # Rebuild one node's own JSON object, children left for the caller.
+    node = ast.node(nid)
+    props = node.all_properties
+    attr_keys: list[str] = props.get(ATTRIBUTE_KEYS_PROPERTY, [])
+    result: dict[str, Any] = {"nodeType": node.node_type}
+    result["attributes"] = {k: props[k] for k in attr_keys}
+    _add_scalar_props(result, props, attr_keys)
+    return result
+
+
+def _add_scalar_props(
+    result: dict[str, Any], props: dict[str, Any], attr_keys: list[str]
+) -> None:
+    # Copy non-attribute scalar properties onto the result. The list-length
+    # and attribute-key records are build bookkeeping, consumed by
+    # _fill_arrays and _reconstruct_node instead.
+    skip = set(attr_keys) | {"nodeType", LIST_LENGTHS_PROPERTY, ATTRIBUTE_KEYS_PROPERTY}
+    for key, value in props.items():
+        if key not in skip:
+            result[key] = value
+
+
+def _reconstruct_children(
+    ast: AST, result: dict[str, Any], nid: str
+) -> list[tuple[str, dict[str, Any]]]:
+    # Reassemble subnode fields and ordered arrays from PARENT_OF edges,
+    # returning (child id, child result) pairs for the caller to descend.
+    node = ast.node(nid)
+    arrays: dict[str, dict[int, Any]] = {}
+    seen: set[tuple[str, int | None]] = set()
+    descend: list[tuple[str, dict[str, Any]]] = []
+    for child in ast.succ(node, _parent_of):
+        edge = ast.edge(nid, child.id, PARENT_OF_EDGE)
+        field_name = edge.get("field")
+        if field_name is None:
+            continue
+        index = _edge_index(edge)
+        # Two children on one slot means the graph is corrupt; a silent
+        # overwrite would drop whichever node iterates first.
+        if (field_name, index) in seen:
+            raise ValueError(
+                f"Duplicate child for field {field_name!r} index {index} on node {nid}"
+            )
+        seen.add((field_name, index))
+        child_json = _node_result(ast, child.id)
+        descend.append((child.id, child_json))
+        if index is None:
+            result[field_name] = child_json
+        else:
+            arrays.setdefault(field_name, {})[index] = child_json
+    _fill_arrays(result, arrays, node.all_properties.get(LIST_LENGTHS_PROPERTY, {}))
+    _add_default_attrs(result, node.node_type)
+    return descend
+
+
+def _add_default_attrs(result: dict[str, Any], node_type: str) -> None:
+    # PHP-Parser expects attrGroups on certain node types.
+    if "attrGroups" in result:
+        return
+    prefixes = ("Stmt_", "Expr_Closure", "Expr_ArrowFunction")
+    if node_type == "Param" or any(node_type.startswith(p) for p in prefixes):
+        result["attrGroups"] = []
+
+
+def _sort_key(index: int | None) -> tuple[int, int]:
+    # Single-object subnodes (index None) sort after indexed ones.
+    if index is None:
+        return (1, 0)
+    return (0, index)
+
+
+def _fill_arrays(
+    result: dict[str, Any],
+    arrays: dict[str, dict[int, Any]],
+    lengths: dict[str, int],
+) -> None:
+    # Expand indexed child maps into dense ordered lists; `lengths`
+    # restores trailing null items, which carry no child edge.
+    for field_name, indexed in arrays.items():
+        if not indexed:
+            continue
+        length = max(max(indexed) + 1, lengths.get(field_name, 0))
+        ordered: list[Any] = [None] * length
+        for idx, child in indexed.items():
+            ordered[idx] = child
+        result[field_name] = ordered

php_parser_py/_parser.py

@@ -0,0 +1,311 @@
+"""Parsing entry points: Parser class and module-level parse functions."""
+
+from __future__ import annotations
+
+import codecs
+import hashlib
+import logging
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+from static_php_py import PHP
+
+from ._exceptions import ParseError, RunnerError
+from ._graph import AST, Node
+from ._mapping import build, statement_ids
+from ._runtime import Runner
+from ._types import FileRecord, ProjectLayout
+
+logger = logging.getLogger(__name__)
+
+
+# Suffixes that conventionally carry PHP source: the canonical .php,
+# template and legacy interpreter registrations (.phtml, .php3-.php7),
+# and include-style sources used by legacy and Drupal projects. A
+# non-PHP match costs one skip warning; a missing suffix silently
+# drops source files, so the set leans inclusive.
+_PHP_SUFFIXES = frozenset(
+    {
+        ".php",
+        ".phtml",
+        ".php3",
+        ".php4",
+        ".php5",
+        ".php7",
+        ".inc",
+        ".module",
+        ".install",
+        ".theme",
+    }
+)
+
+
+def _default_file_filter(path: Path) -> bool:
+    # Default project filter: PHP source files by suffix.
+    return path.suffix.lower() in _PHP_SUFFIXES
+
+
+def _validate_encoding(encoding: str | None) -> None:
+    # Fail on an unknown codec name before any file is read.
+    if encoding is not None:
+        codecs.lookup(encoding)
+
+
+def _file_id(path: Path) -> str:
+    # 64-bit path-derived file node ID. SHA-256 stays available on
+    # FIPS-restricted builds where MD5 raises; surrogateescape keeps
+    # undecodable filesystem bytes hashable.
+    raw = str(path).encode("utf-8", "surrogateescape")
+    return hashlib.sha256(raw).hexdigest()[:16]
+
+
+class Parser:
+    """Parses PHP source code using PHP-Parser.
+
+    Delegates all JSON->graph construction to ``build``. Parser never calls
+    Storage or Modifier directly.
+
+    Attributes:
+        _runner: Runner instance for PHP-Parser invocation.
+    """
+
+    def __init__(
+        self,
+        php: PHP | None = None,
+        ini_settings: Mapping[str, str] | None = None,
+    ) -> None:
+        """Initialize Parser with Runner.
+
+        Args:
+            php: Optional PHP instance. If not provided, uses bundled PHP.
+            ini_settings: Optional PHP ini overrides forwarded to the Runner.
+                Default None inherits the binary's environment.
+        """
+        self._runner = Runner(php=php, ini_settings=ini_settings)
+
+    def parse_code(self, code: str) -> list[Node]:
+        """Parse PHP code string into a list of top-level statement nodes.
+
+        Does not create file nodes; statements are anchored under a
+        synthetic code root node. Returns raw statement nodes that can be
+        used for analysis or inserted into other AST structures.
+
+        Args:
+            code: PHP source code to parse.
+
+        Returns:
+            List of Node instances representing top-level statements.
+
+        Raises:
+            ParseError: If code has syntax errors.
+            RunnerError: If PHP execution fails.
+        """
+        node_list = self._runner.parse(code)
+        ast = build(node_list, ProjectLayout(project_path=None))
+        return [ast.node(nid) for nid in statement_ids(ast, ast.project_root_id)]
+
+    def parse_file(self, path: str, encoding: str | None = None) -> AST:
+        """Parse a single PHP file into an AST with project and file nodes.
+
+        Creates a project node (ID: "project") and a file node (ID: hex
+        hash of path). File node contains all statements from the file.
+
+        Args:
+            path: File path string.
+            encoding: Optional Python codec name declaring the file's byte
+                encoding; the file is transcoded before parsing. Default
+                None passes source bytes through unchanged.
+
+        Returns:
+            AST instance with project -> file -> statements hierarchy.
+
+        Raises:
+            ParseError: If PHP-Parser reports syntax error.
+            FileNotFoundError: If file does not exist.
+            ValueError: If path is not a regular file.
+            LookupError: If ``encoding`` names no Python codec.
+            UnicodeDecodeError: If the file's bytes do not decode under the
+                declared ``encoding``.
+        """
+        _validate_encoding(encoding)
+        file_path = Path(path).resolve()
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {path}")
+        if not file_path.is_file():
+            raise ValueError(f"Path is not a file: {path}")
+
+        record = self._read_file(file_path, encoding)
+        layout = ProjectLayout(project_path=file_path.parent, files=[record])
+        return build([], layout)
+
+    def parse_project(
+        self,
+        project_path: str,
+        file_filter: Callable[[Path], bool] = _default_file_filter,
+        encoding: str | None = None,
+    ) -> AST:
+        """Parse all PHP files in a project directory into an AST.
+
+        Recursively traverses the project directory to find all PHP files,
+        then parses them into a single AST with project and file nodes.
+        Files that fail to read or to parse are skipped with a warning.
+
+        Args:
+            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 common PHP
+                source suffixes (.php, .phtml, legacy and Drupal-style).
+            encoding: Optional Python codec name declaring every file's byte
+                encoding; each file is transcoded before parsing. A file that
+                does not decode is skipped with a warning. Default None
+                passes source bytes through unchanged.
+
+        Returns:
+            AST instance with project -> files -> statements hierarchy.
+
+        Raises:
+            FileNotFoundError: If project directory does not exist.
+            ValueError: If project_path is not a directory, or if two files
+                hash to the same file ID.
+            LookupError: If ``encoding`` names no Python codec.
+        """
+        _validate_encoding(encoding)
+        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}")
+
+        php_files = [
+            f for f in project_path_obj.rglob("*") if f.is_file() and file_filter(f)
+        ]
+        if not php_files:
+            logger.warning("No PHP files found in project directory: %s", project_path)
+
+        records = self._read_files(php_files, encoding)
+        layout = ProjectLayout(project_path=project_path_obj, files=records)
+        return build([], layout)
+
+    # -- Internal helpers --
+
+    def _read_files(self, paths: list[Path], encoding: str | None) -> list[FileRecord]:
+        # Read and parse each file, skipping any that fail to read, to
+        # parse, or to decode under a declared encoding — one bad file
+        # must not abort the whole project. A file-ID collision would
+        # corrupt the graph (two files, one node), so it fails loudly.
+        records: list[FileRecord] = []
+        seen: dict[str, Path] = {}
+        for path in paths:
+            try:
+                record = self._read_file(path, encoding)
+            except (ParseError, RunnerError, UnicodeDecodeError, OSError) as exc:
+                logger.warning("Skipping unparseable file %s: %s", path, exc)
+                continue
+            first = seen.setdefault(record.file_hash, path)
+            if first != path:
+                raise ValueError(
+                    f"File ID collision: {first} and {path} both hash to "
+                    f"{record.file_hash}"
+                )
+            records.append(record)
+        return records
+
+    def _read_file(self, path: Path, encoding: str | None) -> FileRecord:
+        # Parse one file into a FileRecord. Without a declared encoding,
+        # surrogateescape keeps non-UTF-8 source bytes intact;
+        # errors="replace" would silently corrupt them.
+        if encoding is None:
+            code = path.read_bytes().decode("utf-8", "surrogateescape")
+        else:
+            code = path.read_bytes().decode(encoding)
+        statements = self._runner.parse(code)
+        return FileRecord(path=path, file_hash=_file_id(path), statements=statements)
+
+
+def parse_code(code: str) -> list[Node]:
+    """Parse PHP code string into a list of top-level statement nodes.
+
+    Does not create file nodes; statements are anchored under a synthetic
+    code root node. Returns raw statement nodes.
+
+    Args:
+        code: PHP source code string.
+
+    Returns:
+        List of Node instances representing top-level statements.
+
+    Raises:
+        ParseError: If PHP-Parser reports syntax error.
+    """
+    parser = Parser()
+    return parser.parse_code(code)
+
+
+def parse_file(path: str, encoding: str | None = None) -> AST:
+    """Read and parse a single PHP file into an AST.
+
+    Creates a project node and a file node. The file node contains
+    all statements from the file.
+
+    Args:
+        path: File path string.
+        encoding: Optional Python codec name declaring the file's byte
+            encoding; the file is transcoded before parsing. Default None
+            passes source bytes through unchanged.
+
+    Returns:
+        AST instance with project -> file -> statements hierarchy.
+
+    Raises:
+        ParseError: If PHP-Parser reports syntax error.
+        FileNotFoundError: If file does not exist.
+        ValueError: If path is not a regular file.
+        LookupError: If ``encoding`` names no Python codec.
+        UnicodeDecodeError: If the file's bytes do not decode under the
+            declared ``encoding``.
+    """
+    parser = Parser()
+    return parser.parse_file(path, encoding=encoding)
+
+
+def parse_project(
+    project_path: str,
+    file_filter: Callable[[Path], bool] | None = None,
+    ini_settings: Mapping[str, str] | None = None,
+    encoding: str | None = None,
+) -> AST:
+    """Parse all PHP files in a project directory into an AST.
+
+    Recursively traverses the project directory to find all PHP files,
+    then parses them into a single AST with project and file nodes.
+    Files that fail to read or to parse are skipped with a warning.
+
+    Args:
+        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 common PHP
+            source suffixes (.php, .phtml, legacy and Drupal-style).
+        ini_settings: Optional PHP ini overrides (e.g. ``memory_limit``)
+            applied to every PHP invocation. Default None inherits the
+            binary's environment.
+        encoding: Optional Python codec name declaring every file's byte
+            encoding; each file is transcoded before parsing. A file that
+            does not decode is skipped with a warning. Default None passes
+            source bytes through unchanged.
+
+    Returns:
+        AST instance with project -> files -> statements hierarchy.
+
+    Raises:
+        FileNotFoundError: If project directory does not exist.
+        ValueError: If project_path is not a directory, or if two files
+            hash to the same file ID.
+        LookupError: If ``encoding`` names no Python codec.
+    """
+    if file_filter is None:
+        file_filter = _default_file_filter
+    parser = Parser(ini_settings=ini_settings)
+    return parser.parse_project(
+        project_path, file_filter=file_filter, encoding=encoding
+    )

php_parser_py/_printer.py

@@ -0,0 +1,147 @@
+"""Printer Protocol and its two strategies: StandardPrinter, ExtendedPrinter."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Protocol, runtime_checkable
+
+from static_php_py import PHP
+
+from ._graph import AST, Node
+from ._mapping import serialize
+from ._runtime import Runner
+from ._types import PrintMode, PrintRequest
+
+logger = logging.getLogger(__name__)
+
+_STANDARD_CLASS = "PhpParser\\PrettyPrinter\\Standard"
+_EXTENDED_CLASS = "Blv\\ExtendedPrinter"
+
+
+@runtime_checkable
+class Printer(Protocol):
+    """Structural contract for converting an AST to PHP source per file."""
+
+    def print(self, ast: AST) -> dict[str, str]:
+        """Full-rewrite print of every file in the AST.
+
+        Args:
+            ast: AST instance, possibly multi-file.
+
+        Returns:
+            Mapping of file path to generated PHP source. An AST with no file
+            structure yields a single entry keyed "".
+
+        Raises:
+            RunnerError: On PHP-Parser failure.
+        """
+
+    def print_preserving(
+        self, ast: AST, origin_source: Mapping[str, str]
+    ) -> dict[str, str]:
+        """Format-preserving print; reprint only changed or new nodes.
+
+        Args:
+            ast: Modified AST instance.
+            origin_source: Mapping of each file key to its original source.
+
+        Returns:
+            Mapping of file path to generated PHP source.
+
+        Raises:
+            RunnerError: On PHP-Parser failure.
+            KeyError: If an AST file key is absent from origin_source.
+        """
+
+
+class _PrinterBase:
+    """Shared print orchestration parameterized by PHP printer class."""
+
+    _php_class: str
+
+    def __init__(
+        self,
+        php: PHP | None = None,
+        ini_settings: Mapping[str, str] | None = None,
+    ) -> None:
+        """Initialize with a Runner.
+
+        Args:
+            php: Optional PHP instance. Defaults to the bundled binary.
+            ini_settings: Optional PHP ini overrides forwarded to the Runner.
+                Default None inherits the binary's environment.
+        """
+        self._runner = Runner(php=php, ini_settings=ini_settings)
+
+    def print(self, ast: AST) -> dict[str, str]:
+        """Full-rewrite print of every file in the AST."""
+        return {
+            key: self._runner.print(
+                PrintRequest(
+                    php_class=self._php_class,
+                    mode=PrintMode.FULL_REWRITE,
+                    stmts_json=json_str,
+                )
+            )
+            for key, json_str in self._file_statements(ast).items()
+        }
+
+    def print_preserving(
+        self, ast: AST, origin_source: Mapping[str, str]
+    ) -> dict[str, str]:
+        """Format-preserving print; reprint only changed or new nodes."""
+        result: dict[str, str] = {}
+        for key, json_str in self._file_statements(ast).items():
+            if key not in origin_source:
+                raise KeyError(f"No origin source for AST file {key!r}.")
+            result[key] = self._runner.print(
+                PrintRequest(
+                    php_class=self._php_class,
+                    mode=PrintMode.FORMAT_PRESERVING,
+                    stmts_json=json_str,
+                    orig_source=origin_source[key],
+                )
+            )
+        return result
+
+    @staticmethod
+    def _file_statements(ast: AST) -> dict[str, str]:
+        """Map each file key to its statement JSON.
+
+        An AST with no file structure maps the single key "" to all
+        statements.
+        """
+        file_nodes = ast.file_nodes()
+        if not file_nodes:
+            return {"": serialize(ast)}
+        return {
+            _PrinterBase._file_key(file_node): serialize(ast, file_hash=file_node.id)
+            for file_node in file_nodes
+        }
+
+    @staticmethod
+    def _file_key(file_node: Node) -> str:
+        """Key a file by its absolute path, falling back to its node id."""
+        path = file_node.get_property("absolutePath", "")
+        return str(path) if path else file_node.id
+
+
+class StandardPrinter(_PrinterBase):
+    """Stock PHP-Parser printing via PrettyPrinter\\Standard.
+
+    Baseline behavior with no printer-bug fixes.
+    """
+
+    _php_class = _STANDARD_CLASS
+
+
+class ExtendedPrinter(_PrinterBase):
+    """PHP-Parser printing with selective printer-bug fixes.
+
+    Instantiates Blv\\ExtendedPrinter, a userland class extending Standard.
+    Overrides affect only reprinted nodes, so an unmodified round-trip is
+    inert.
+    """
+
+    _php_class = _EXTENDED_CLASS