php-parser-py 1.2.6__py3-none-win_amd64.whl → 2.0.3__py3-none-win_amd64.whl

php_parser_py/__init__.py

@@ -6,13 +6,16 @@ and manipulation of PHP code.
 
 from __future__ import annotations
 
-__version__ = "1.2.2"
+from importlib.metadata import version as _distribution_version
+
+__version__ = _distribution_version("php-parser-py")
 __all__ = [
     "AST",
     "Edge",
     "Modifier",
     "Node",
     "Parser",
+    "PHPVersion",
     "Printer",
     "StandardPrinter",
     "ExtendedPrinter",
@@ -31,3 +34,4 @@ from ._graph import AST, Edge, Modifier, Node
 from ._parser import Parser, parse_code, parse_file, parse_project
 from ._printer import ExtendedPrinter, Printer, StandardPrinter
 from ._types import PrintMode, PrintRequest
+from ._version import PHPVersion

php_parser_py/_graph/_ast.py

@@ -8,6 +8,7 @@ from cpg2py import AbcGraphQuerier, Storage
 
 from .._exceptions import NodeNotInFileError
 from .._types import PARENT_OF_EDGE, PROJECT_ROOT_ID
+from .._version import PHPVersion
 from ._edge import Edge
 from ._node import Node
 from ._node_id import NodeId
@@ -31,17 +32,27 @@ class AST(AbcGraphQuerier[Node, Edge]):
 
     Attributes:
         _root_node_id: ID of the root project node (always "project").
+        _target_php: Target PHP version the parser parsed the source under;
+            None when no parser produced this graph.
     """
 
-    def __init__(self, storage: Storage, root_node_id: str = PROJECT_ROOT_ID) -> None:
+    def __init__(
+        self,
+        storage: Storage,
+        root_node_id: str = PROJECT_ROOT_ID,
+        target_php: PHPVersion | None = None,
+    ) -> None:
         """Initialize AST with populated storage.
 
         Args:
             storage: cpg2py Storage containing AST nodes and edges.
             root_node_id: ID of the root node. Defaults to "project".
+            target_php: Target PHP version of the parse that produced the
+                graph. Default None marks the provenance unknown.
         """
         super().__init__(storage)
         self._root_node_id = root_node_id
+        self._target_php = target_php
 
     @property
     def storage(self) -> Storage:
@@ -68,13 +79,24 @@ class AST(AbcGraphQuerier[Node, Edge]):
         """Return the root node ID of this AST."""
         return self._root_node_id
 
+    @property
+    def target_php(self) -> PHPVersion | None:
+        """Return the target PHP version the source was parsed under.
+
+        Parse provenance, not a PHP node field: serialization and printing
+        never emit it as part of the PHP-Parser JSON. Always known on a graph
+        a parser produced; None on a graph built without a parse.
+        """
+        return self._target_php
+
     def copy(self) -> AST:
         """Return a new AST backed by a deep copy of this graph.
 
         Node IDs, the edge set, and all node/edge properties are duplicated
-        verbatim, preserving the ``{file_hash}_{counter}`` ID namespace and the
-        root node ID. The returned AST shares no mutable state with this one:
-        mutating either graph leaves the other unchanged.
+        verbatim, preserving the ``{file_hash}_{counter}`` ID namespace, the
+        root node ID and the target PHP version. The returned AST shares no
+        mutable state with this one: mutating either graph leaves the other
+        unchanged.
 
         Returns:
             A new AST whose storage is an independent copy of this graph.
@@ -82,7 +104,9 @@ class AST(AbcGraphQuerier[Node, Edge]):
         storage = Storage()
         self._copy_nodes_into(storage)
         self._copy_edges_into(storage)
-        return AST(storage, root_node_id=self._root_node_id)
+        return AST(
+            storage, root_node_id=self._root_node_id, target_php=self._target_php
+        )
 
     def _copy_nodes_into(self, storage: Storage) -> None:
         """Duplicate every node and its properties into ``storage``."""

php_parser_py/_mapping/_build.py

@@ -12,6 +12,7 @@ from cpg2py import Storage
 
 from .._graph import AST, Modifier, NodeId
 from .._types import PROJECT_ROOT_ID, FileRecord, ProjectLayout
+from .._version import PHPVersion
 from ._contract import (
     ATTRIBUTE_KEYS_PROPERTY,
     LIST_LENGTHS_PROPERTY,
@@ -26,7 +27,11 @@ _FILE_END_DEFAULTS: dict[str, int] = {"endLine": 1, "endFilePos": 0, "endTokenPo
 _CODE_ROOT_ID = "__code_root__"
 
 
-def build(json_trees: list[dict[str, object]], layout: ProjectLayout) -> AST:
+def build(
+    json_trees: list[dict[str, object]],
+    layout: ProjectLayout,
+    target_php: PHPVersion,
+) -> AST:
     """Populate a fresh ``AST`` from PHP-Parser JSON trees.
 
     Forward entry of the mapping package; inverse of ``serialize``.
@@ -34,6 +39,8 @@ def build(json_trees: list[dict[str, object]], layout: ProjectLayout) -> AST:
     Args:
         json_trees: Normalized list of root node dicts (code-only mode).
         layout: Project/file structure and per-file hashes.
+        target_php: Target PHP version the trees were parsed under; recorded
+            as the AST's provenance, never as a node field.
 
     Returns:
         AST with project -> file -> statement hierarchy, or a flat statement
@@ -42,7 +49,7 @@ def build(json_trees: list[dict[str, object]], layout: ProjectLayout) -> AST:
     Raises:
         ValueError: From ``Modifier.add_node`` on a duplicate ID.
     """
-    builder = _Builder()
+    builder = _Builder(target_php)
     if layout.project_path is None:
         return builder.build_code(json_trees)
     return builder.build_project(layout)
@@ -52,18 +59,22 @@ class _Builder:
     """Stateful JSON->graph builder with a per-file ID allocator.
 
     Attributes:
+        _target_php: Target PHP version stamped on the built AST.
         _next_index: Stateful per-file ID allocator counter.
         _prefix: Current file-hash prefix; empty string for code-only parsing.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, target_php: PHPVersion) -> None:
         """Initialize a builder with a fresh allocator state."""
+        self._target_php = target_php
         self._next_index = 1
         self._prefix = ""
 
     def build_code(self, json_trees: list[dict[str, object]]) -> AST:
         """Build statements anchored under a synthetic code-root node."""
-        modifier = Modifier(AST(Storage(), root_node_id=_CODE_ROOT_ID))
+        modifier = Modifier(
+            AST(Storage(), root_node_id=_CODE_ROOT_ID, target_php=self._target_php)
+        )
         # A real anchor node makes top-level membership explicit: serialize
         # exports the anchor's stmts edges. Inferring roots from missing
         # parent edges would promote subtrees orphaned by remove_node.
@@ -78,7 +89,7 @@ class _Builder:
         project_path = layout.project_path
         if project_path is None:
             raise ValueError("ProjectLayout.project_path is required for build")
-        modifier = Modifier(AST(Storage()))
+        modifier = Modifier(AST(Storage(), target_php=self._target_php))
         modifier.add_node(
             PROJECT_ROOT_ID,
             "Project",

php_parser_py/_mapping/_serialize.py

@@ -139,6 +139,10 @@ def _node_result(ast: AST, nid: str) -> dict[str, Any]:
     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)
+    # A recorded attributes bundle marks an original JSON node; only
+    # nodes created without that record need declaration defaults.
+    if ATTRIBUTE_KEYS_PROPERTY not in props:
+        _add_default_attrs(result, node.node_type)
     return result
 
 
@@ -183,7 +187,6 @@ def _reconstruct_children(
         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
 
 

php_parser_py/_parser.py

@@ -15,6 +15,7 @@ from ._graph import AST, Node
 from ._mapping import build, statement_ids
 from ._runtime import Runner
 from ._types import FileRecord, ProjectLayout
+from ._version import PHPVersion
 
 logger = logging.getLogger(__name__)
 
@@ -67,21 +68,35 @@ class Parser:
 
     Attributes:
         _runner: Runner instance for PHP-Parser invocation.
+        _target_php: PHP version every parse targets.
     """
 
     def __init__(
         self,
         php: PHP | None = None,
         ini_settings: Mapping[str, str] | None = None,
+        *,
+        target_php: PHPVersion,
     ) -> None:
         """Initialize Parser with Runner.
 
         Args:
             php: Optional PHP instance. If not provided, uses bundled PHP.
+                It runs PHP-Parser and is independent of ``target_php``.
             ini_settings: Optional PHP ini overrides forwarded to the Runner.
                 Default None inherits the binary's environment.
+            target_php: PHP version the parsed source targets; selects the
+                PHP-Parser grammar and is recorded on every AST produced.
+
+        Raises:
+            TypeError: If ``target_php`` is not a ``PHPVersion``.
         """
+        if not isinstance(target_php, PHPVersion):
+            raise TypeError(
+                f"target_php must be a PHPVersion, got {type(target_php).__name__}"
+            )
         self._runner = Runner(php=php, ini_settings=ini_settings)
+        self._target_php = target_php
 
     def parse_code(self, code: str) -> list[Node]:
         """Parse PHP code string into a list of top-level statement nodes.
@@ -100,8 +115,9 @@ class Parser:
             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))
+        node_list = self._runner.parse(code, self._target_php)
+        layout = ProjectLayout(project_path=None)
+        ast = build(node_list, layout, self._target_php)
         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:
@@ -136,7 +152,7 @@ class Parser:
 
         record = self._read_file(file_path, encoding)
         layout = ProjectLayout(project_path=file_path.parent, files=[record])
-        return build([], layout)
+        return build([], layout, self._target_php)
 
     def parse_project(
         self,
@@ -185,7 +201,7 @@ class Parser:
 
         records = self._read_files(php_files, encoding)
         layout = ProjectLayout(project_path=project_path_obj, files=records)
-        return build([], layout)
+        return build([], layout, self._target_php)
 
     # -- Internal helpers --
 
@@ -219,11 +235,11 @@ class Parser:
             code = path.read_bytes().decode("utf-8", "surrogateescape")
         else:
             code = path.read_bytes().decode(encoding)
-        statements = self._runner.parse(code)
+        statements = self._runner.parse(code, self._target_php)
         return FileRecord(path=path, file_hash=_file_id(path), statements=statements)
 
 
-def parse_code(code: str) -> list[Node]:
+def parse_code(code: str, *, target_php: PHPVersion) -> 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
@@ -231,18 +247,22 @@ def parse_code(code: str) -> list[Node]:
 
     Args:
         code: PHP source code string.
+        target_php: PHP version the source targets.
 
     Returns:
         List of Node instances representing top-level statements.
 
     Raises:
         ParseError: If PHP-Parser reports syntax error.
+        TypeError: If ``target_php`` is not a ``PHPVersion``.
     """
-    parser = Parser()
+    parser = Parser(target_php=target_php)
     return parser.parse_code(code)
 
 
-def parse_file(path: str, encoding: str | None = None) -> AST:
+def parse_file(
+    path: str, encoding: str | None = None, *, target_php: PHPVersion
+) -> AST:
     """Read and parse a single PHP file into an AST.
 
     Creates a project node and a file node. The file node contains
@@ -253,6 +273,7 @@ def parse_file(path: str, encoding: str | None = None) -> AST:
         encoding: Optional Python codec name declaring the file's byte
             encoding; the file is transcoded before parsing. Default None
             passes source bytes through unchanged.
+        target_php: PHP version the source targets; recorded on the AST.
 
     Returns:
         AST instance with project -> file -> statements hierarchy.
@@ -264,8 +285,9 @@ def parse_file(path: str, encoding: str | None = None) -> AST:
         LookupError: If ``encoding`` names no Python codec.
         UnicodeDecodeError: If the file's bytes do not decode under the
             declared ``encoding``.
+        TypeError: If ``target_php`` is not a ``PHPVersion``.
     """
-    parser = Parser()
+    parser = Parser(target_php=target_php)
     return parser.parse_file(path, encoding=encoding)
 
 
@@ -274,6 +296,8 @@ def parse_project(
     file_filter: Callable[[Path], bool] | None = None,
     ini_settings: Mapping[str, str] | None = None,
     encoding: str | None = None,
+    *,
+    target_php: PHPVersion,
 ) -> AST:
     """Parse all PHP files in a project directory into an AST.
 
@@ -293,6 +317,7 @@ def parse_project(
             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.
+        target_php: PHP version every file targets; recorded on the AST.
 
     Returns:
         AST instance with project -> files -> statements hierarchy.
@@ -302,10 +327,11 @@ def parse_project(
         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.
+        TypeError: If ``target_php`` is not a ``PHPVersion``.
     """
     if file_filter is None:
         file_filter = _default_file_filter
-    parser = Parser(ini_settings=ini_settings)
+    parser = Parser(ini_settings=ini_settings, target_php=target_php)
     return parser.parse_project(
         project_path, file_filter=file_filter, encoding=encoding
     )

php_parser_py/_printer.py

@@ -12,6 +12,7 @@ from ._graph import AST, Node
 from ._mapping import serialize
 from ._runtime import Runner
 from ._types import PrintMode, PrintRequest
+from ._version import PHPVersion
 
 logger = logging.getLogger(__name__)
 
@@ -35,6 +36,7 @@ class Printer(Protocol):
 
         Raises:
             RunnerError: On PHP-Parser failure.
+            ValueError: If the AST has no known parse target version.
         """
 
     def print_preserving(
@@ -52,6 +54,7 @@ class Printer(Protocol):
         Raises:
             RunnerError: On PHP-Parser failure.
             KeyError: If an AST file key is absent from origin_source.
+            ValueError: If the AST has no known parse target version.
         """
 
 
@@ -76,12 +79,14 @@ class _PrinterBase:
 
     def print(self, ast: AST) -> dict[str, str]:
         """Full-rewrite print of every file in the AST."""
+        target = self._target_of(ast)
         return {
             key: self._runner.print(
                 PrintRequest(
                     php_class=self._php_class,
                     mode=PrintMode.FULL_REWRITE,
                     stmts_json=json_str,
+                    target_php=target,
                 )
             )
             for key, json_str in self._file_statements(ast).items()
@@ -91,6 +96,7 @@ class _PrinterBase:
         self, ast: AST, origin_source: Mapping[str, str]
     ) -> dict[str, str]:
         """Format-preserving print; reprint only changed or new nodes."""
+        target = self._target_of(ast)
         result: dict[str, str] = {}
         for key, json_str in self._file_statements(ast).items():
             if key not in origin_source:
@@ -100,11 +106,22 @@ class _PrinterBase:
                     php_class=self._php_class,
                     mode=PrintMode.FORMAT_PRESERVING,
                     stmts_json=json_str,
+                    target_php=target,
                     orig_source=origin_source[key],
                 )
             )
         return result
 
+    @staticmethod
+    def _target_of(ast: AST) -> PHPVersion:
+        """Return the AST's parse target, rejecting unknown provenance."""
+        if ast.target_php is None:
+            raise ValueError(
+                "Cannot print an AST of unknown parse provenance: "
+                "target_php is None."
+            )
+        return ast.target_php
+
     @staticmethod
     def _file_statements(ast: AST) -> dict[str, str]:
         """Map each file key to its statement JSON.

php_parser_py/_resources/parse.php

@@ -5,10 +5,12 @@ declare(strict_types=1);
 /**
  * Parse PHP source into a JSON AST.
  *
- * Reads one JSON object from stdin: {"phar_path": string, "code": string}.
+ * Reads one JSON object from stdin:
+ * {"phar_path": string, "code": string, "target_major": int, "target_minor": int}.
  * The code field is base64: JSON cannot carry the raw non-UTF-8 bytes a
- * PHP source file may legally contain. Emits {"errors": [...]} with exit 0
- * on syntax errors, the serialized statements on success, or
+ * PHP source file may legally contain. The target version selects the
+ * PHP-Parser grammar the code is accepted under. Emits {"errors": [...]}
+ * with exit 0 on syntax errors, the serialized statements on success, or
  * {"error": ...} with exit 1 on any other failure.
  */
 
@@ -90,9 +92,9 @@ if ($code === false) {
     exit(2);
 }
 $errorHandler = new Collecting();
-$parser = (new ParserFactory())->createForNewestSupportedVersion();
 
 try {
+    $parser = (new ParserFactory())->createForVersion(pppy_target_version($payload));
     $stmts = $parser->parse($code, $errorHandler);
     if ($errorHandler->hasErrors()) {
         $errors = array_map(fn($e) => [

php_parser_py/_resources/print.php

@@ -12,11 +12,15 @@ declare(strict_types=1);
  *     "printer_class": string,  // FQCN to instantiate (read as data)
  *     "mode": string,           // "full_rewrite" | "format_preserving"
  *     "stmts": string,          // JSON of the (modified) statements
+ *     "target_major": int,      // target PHP version, read as data
+ *     "target_minor": int,
  *     "orig_source": string     // original source (format_preserving only)
  *   }
  *
  * The printer class name is read from the payload and instantiated via a
- * variable class expression; it is never spliced into source. Emits the
+ * variable class expression; it is never spliced into source. The target
+ * version sets the printer's phpVersion option and the version the original
+ * source is reparsed under. Emits the
  * generated PHP on success, or {"error": ...} with exit 1 on failure.
  */
 
@@ -44,13 +48,14 @@ try {
 
     // Normalize the FQCN and instantiate by name (class name travels as data).
     $printerClass = '\\' . ltrim($payload['printer_class'], '\\');
-    $printer = new $printerClass();
+    $version = pppy_target_version($payload);
+    $printer = new $printerClass(['phpVersion' => $version]);
 
     // Output is base64-encoded so non-UTF-8 source bytes survive the text
     // stdout channel back to the caller (mirrors the base64 orig_source input).
     if ($payload['mode'] === 'format_preserving') {
         $origSource = base64_decode($payload['orig_source']);
-        echo base64_encode(render_format_preserving($printer, $stmts, $origSource));
+        echo base64_encode(render_format_preserving($printer, $stmts, $origSource, $version));
     } else {
         echo base64_encode($printer->prettyPrintFile($stmts));
     }
@@ -93,9 +98,13 @@ function pppy_decode_stmts(string $stmtsJson): array
  * Re-parse the original source, link unchanged decoded nodes to their original
  * objects by token position, then reprint preserving original formatting.
  */
-function render_format_preserving($printer, array $stmts, string $origSource): string
-{
-    $parser = (new ParserFactory())->createForNewestSupportedVersion();
+function render_format_preserving(
+    $printer,
+    array $stmts,
+    string $origSource,
+    PhpParser\PhpVersion $version
+): string {
+    $parser = (new ParserFactory())->createForVersion($version);
     $origStmts = $parser->parse($origSource);
     $origTokens = $parser->getTokens();
 

php_parser_py/_resources/transport.php

@@ -10,7 +10,8 @@ declare(strict_types=1);
  * value that cannot travel as strict JSON is wrapped in a NUL-prefixed
  * marker string; the Python side (_transport.py) applies the same
  * codec. parse.php encodes before emitting; print.php decodes after
- * JsonDecoder.
+ * JsonDecoder. Both scripts also read the target PHP version from the
+ * payload through pppy_target_version.
  */
 
 // json_encode/json_decode default to a 512-level nesting cap, rejecting
@@ -193,3 +194,20 @@ function pppy_decode_comment(PhpParser\Comment $comment)
         $comment->getEndTokenPos()
     );
 }
+
+/**
+ * Read the target PHP version a payload carries as two integer fields,
+ * target_major and target_minor. Python validates the series before it
+ * sends the payload, so a missing or mistyped field is a channel fault.
+ */
+function pppy_target_version(array $payload): PhpParser\PhpVersion
+{
+    $major = $payload['target_major'] ?? null;
+    $minor = $payload['target_minor'] ?? null;
+    if (!is_int($major) || !is_int($minor)) {
+        throw new RuntimeException(
+            'payload target_major and target_minor must be integers'
+        );
+    }
+    return PhpParser\PhpVersion::fromComponents($major, $minor);
+}

php_parser_py/_runtime/_runner.py

@@ -13,6 +13,7 @@ from static_php_py import PHP, ExecutionError, ExecutionResult
 from .._exceptions import ParseError, RunnerError
 from .._transport import decode_values
 from .._types import PrintMode, PrintRequest
+from .._version import PHPVersion
 from ._binary import resolve_php
 from ._bundle import ensure_php_parser_extracted, get_resources_path
 
@@ -21,6 +22,11 @@ from ._bundle import ensure_php_parser_extracted, get_resources_path
 _BASE_INI = {"display_errors": "stderr"}
 
 
+def _target_fields(target_php: PHPVersion) -> dict[str, int]:
+    # The target travels as two integers read as data by the PHP scripts.
+    return {"target_major": target_php.major, "target_minor": target_php.minor}
+
+
 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}"
@@ -114,11 +120,12 @@ class Runner:
             )
         return result.stdout
 
-    def parse(self, code: str) -> list[dict[str, Any]]:
+    def parse(self, code: str, target_php: PHPVersion) -> list[dict[str, Any]]:
         """Invoke PHP-Parser parse + JsonSerializer.
 
         Args:
             code: PHP source code to parse.
+            target_php: PHP version whose grammar the parser accepts.
 
         Returns:
             Parsed statements as a list of PHP-Parser JSON node dicts.
@@ -127,7 +134,7 @@ class Runner:
             ParseError: If PHP-Parser reports syntax error.
             RunnerError: If PHP execution fails or emits a malformed payload.
         """
-        stdin = self._build_parse_stdin(code)
+        stdin = self._build_parse_stdin(code, target_php)
 
         try:
             output = self._execute_script_file("parse.php", stdin)
@@ -186,7 +193,8 @@ class Runner:
         """Render and run the print script for one file.
 
         Args:
-            request: Print inputs (printer class, mode, statements, origin).
+            request: Print inputs (printer class, mode, statements, target
+                version, origin).
 
         Returns:
             Generated PHP source code.
@@ -200,7 +208,7 @@ class Runner:
         # 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:
+    def _build_parse_stdin(self, code: str, target_php: PHPVersion) -> str:
         """Pack the parse inputs into a single JSON stdin payload.
 
         The code field travels as base64: PHP source may legally hold raw
@@ -211,6 +219,7 @@ class Runner:
         payload = {
             "phar_path": str(self._phar_path()),
             "code": base64.b64encode(raw).decode("ascii"),
+            **_target_fields(target_php),
         }
         return json.dumps(payload)
 
@@ -219,13 +228,15 @@ class Runner:
 
         The printer class name travels as the ``printer_class`` field; it is
         read as data by ``print.php`` and never interpolated into PHP source.
+        The target version travels as two integers.
         """
-        payload: dict[str, str] = {
+        payload: dict[str, str | int] = {
             "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,
+            **_target_fields(request.target_php),
         }
         if request.mode is PrintMode.FORMAT_PRESERVING:
             # Original source may hold non-UTF-8 bytes (e.g. Latin-1 literals).

php_parser_py/_types.py

@@ -6,6 +6,8 @@ from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
 
+from ._version import PHPVersion
+
 # The AST hierarchy edge type; fixed by the JSON<->graph mapping contract.
 PARENT_OF_EDGE = "PARENT_OF"
 
@@ -36,6 +38,8 @@ class PrintRequest:
         php_class: Fully-qualified printer class to instantiate.
         mode: Entry-point selector.
         stmts_json: JSON of the (modified) statements.
+        target_php: PHP version the printer options and the original-source
+            reparse follow; the parse provenance of the printed AST.
         orig_source: Original PHP source, re-parsed in-process to recover
             original objects and tokens. Required when ``mode`` is
             FORMAT_PRESERVING; None otherwise.
@@ -48,6 +52,7 @@ class PrintRequest:
     php_class: str
     mode: PrintMode
     stmts_json: str
+    target_php: PHPVersion
     orig_source: str | None = None
 
     def __post_init__(self) -> None:

php_parser_py/_version.py

@@ -0,0 +1,51 @@
+"""PHP target version: the (major, minor) series a parse or print targets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Newest minor accepted per supported major series. Project policy, not an
+# upstream boundary: PHP-Parser takes arbitrary components and treats the
+# target as best-effort.
+_NEWEST_MINOR_BY_MAJOR = {7: 4, 8: 5}
+_SUPPORTED_SERIES = " and ".join(
+    f"{major}.0-{major}.{newest}" for major, newest in _NEWEST_MINOR_BY_MAJOR.items()
+)
+
+
+def _require_int(name: str, value: object) -> None:
+    # bool is an int subtype but never a version component.
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(
+            f"PHPVersion {name} must be an int, got {type(value).__name__}: {value!r}"
+        )
+
+
+@dataclass(frozen=True)
+class PHPVersion:
+    """A target PHP series: major and minor version, without a patch level.
+
+    Accepted series are 7.0 to 7.4 and 8.0 to 8.5. The patch level is not
+    part of the target: PHP-Parser distinguishes series only.
+
+    Attributes:
+        major: PHP major version, 7 or 8.
+        minor: PHP minor version within the major series.
+
+    Raises:
+        TypeError: If a component is not an ``int`` (``bool`` included).
+        ValueError: If the pair is not an accepted series.
+    """
+
+    major: int
+    minor: int
+
+    def __post_init__(self) -> None:
+        _require_int("major", self.major)
+        _require_int("minor", self.minor)
+        newest = _NEWEST_MINOR_BY_MAJOR.get(self.major)
+        if newest is None or not 0 <= self.minor <= newest:
+            raise ValueError(
+                f"Unsupported target PHP version {self.major}.{self.minor}; "
+                f"supported series are {_SUPPORTED_SERIES}"
+            )

{php_parser_py-1.2.6.dist-info → php_parser_py-2.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: php-parser-py
-Version: 1.2.6
+Version: 2.0.3
 Summary: Python wrapper for PHP-Parser using cpg2py
 License-Expression: GPL-2.0-only
 License-File: LICENSE
@@ -37,10 +37,10 @@ Requires Python >= 3.10.
 ## Usage
 
 ```python
-from php_parser_py import parse_file, Modifier
+from php_parser_py import parse_file, Modifier, PHPVersion
 
-# Parse
-ast = parse_file("src/User.php")
+# Parse (the target PHP version is required)
+ast = parse_file("src/User.php", target_php=PHPVersion(8, 3))
 
 # Query
 functions = ast.nodes(lambda n: n.node_type == "Stmt_Function")
@@ -58,9 +58,11 @@ modified = modifier.ast
 
 | Function / Class | Signature | Description |
 |-----------------|-----------|-------------|
-| `parse_code` | `(code: str) -> list[Node]` | Parse PHP string into statement nodes |
-| `parse_file` | `(path: str) -> AST` | Parse single file with project/file structure |
-| `parse_project` | `(project_path: str, file_filter?) -> AST` | Parse all PHP files in a directory |
+| `PHPVersion` | `(major: int, minor: int)` | Target PHP version, 7.0 to 7.4 and 8.0 to 8.5 |
+| `parse_code` | `(code: str, *, target_php: PHPVersion) -> list[Node]` | Parse PHP string into statement nodes |
+| `parse_file` | `(path: str, *, target_php: PHPVersion) -> AST` | Parse single file with project/file structure |
+| `parse_project` | `(project_path: str, file_filter?, *, target_php: PHPVersion) -> AST` | Parse all PHP files in a directory |
+| `AST.target_php` | `-> PHPVersion \| None` | Version the graph was parsed under (read-only) |
 | `Modifier` | `(ast: AST)` | Copy-on-write graph mutation; read result from `modifier.ast` |
 | `AST.nodes` | `(predicate?) -> Generator[Node]` | Iterate/filter nodes |
 | `AST.succ` | `(node) -> Generator[Node]` | Get children |

{php_parser_py-1.2.6.dist-info → php_parser_py-2.0.3.dist-info}/RECORD

@@ -1,35 +1,35 @@
-php_parser_py/__init__.py,sha256=THb6r0h4R4e3E40EB_gPMfKbOTgRix6dtazlPaqG-_I,821
+php_parser_py/__init__.py,sha256=BkOXmqdi1q3YG3MZljPP9Aa43VoMUtc8gdyVyFVta-Q,968
 php_parser_py/_exceptions.py,sha256=lWGngHWCrOEGL3ILwPMFnU0mlha6e5U6SYxz7n1oLY8,1824
 php_parser_py/_graph/__init__.py,sha256=GAOtPcGGMQCbif86vdQgk9GgTkOJPee6_NA-wewN3g8,396
-php_parser_py/_graph/_ast.py,sha256=SCOVdQzIJ2lI6yzoyazRpzT3EYQrfYM4kKEPeT8kCMo,7959
+php_parser_py/_graph/_ast.py,sha256=HHlqm7-Et1T2aMRtILTrlXElPGo_15FB4DS--x_NEyg,8856
 php_parser_py/_graph/_edge.py,sha256=WzimZf6WB6inHACrFHsQOyFgrhdzyfGhv8UboEPOQjE,2995
 php_parser_py/_graph/_modifier.py,sha256=VLJruL0260_VbXoXYWZdGmrXO-oXgiWIWS6v3MRmsaM,4829
 php_parser_py/_graph/_node.py,sha256=hA4eRQx4PWAakHkehC5SbpS12FvtlGDf2UnT4RuFZQ4,8276
 php_parser_py/_graph/_node_id.py,sha256=YvtpkOO1DiT-yHyOED0pSsDqzuYFUiNRGtGvCNKvArY,1597
 php_parser_py/_mapping/__init__.py,sha256=XzQuME5jXu_GBiwFpXZyhM9EevRJaNyrH_vAu7jFNos,469
-php_parser_py/_mapping/_build.py,sha256=5iVycpqHb_spJXnx42ezcYKsfxdVoG5o7vGmFATtIg8,8843
+php_parser_py/_mapping/_build.py,sha256=C9gCBJKS3q5VYVNbqWdrI5gC3DD5X9dSJBBfOUDyVes,9271
 php_parser_py/_mapping/_contract.py,sha256=Czfspg4FbU_FZOJLV0AtAmEl6-Pjuo_RLOyOBH8NtYw,2451
-php_parser_py/_mapping/_serialize.py,sha256=_iGvXi-8LqV9zERTao3pXT_TpfTFzWcSX6BuwJ9wg4A,8485
-php_parser_py/_parser.py,sha256=lZ51OQc76Amd1U1Bc8QLdwyPRdvqRkdmaS7j49RRazY,11703
-php_parser_py/_printer.py,sha256=CUV4CmUNT0yX6qTFM6WlnKNliPvoY3yxhTWNdEYZuck,4561
+php_parser_py/_mapping/_serialize.py,sha256=EP3A5_wXD72a0-drb62j_N-hJ-JGJoUZ6qqFNWdYZOs,8670
+php_parser_py/_parser.py,sha256=juoRV9sxQJi7odimmm3s27s3l4aHUbBZ4toODEKc3PM,13012
+php_parser_py/_printer.py,sha256=SEr1ivOJnoDUxzDaKY0Hkiu5kNQOfAuqiwH10QtH6tI,5241
 php_parser_py/_resources/ExtendedPrinter.php,sha256=hv2wKJ7QzK6epkevlwmlWrOiFncClTetiqR8kriKsCY,6333
-php_parser_py/_resources/parse.php,sha256=EuCajqyBg8H7DlMApJp5dOLk-Sa9Kib6fcA3XbJs4GI,3624
-php_parser_py/_resources/php,sha256=vvXi2Cj0AtYVxcNp-Iaa2u-A8jR-znyvIZhDUM_-0bw,8918288
+php_parser_py/_resources/parse.php,sha256=g0pDrC1h1Lv85nqIbhOdZcuGgByjz4lJTEivNZAu6NY,3768
 php_parser_py/_resources/php-parser-5.7.0.tar.gz,sha256=CeU5G4YHMA__oybtkqM3dNW07VlcSLOUl2eQWpLklFs,143662
-php_parser_py/_resources/print.php,sha256=11Tp5NEeVxag7m7RmjivGiPfu6gqmkMnPgMmSpc3ElA,5649
-php_parser_py/_resources/transport.php,sha256=Ps7oE1Fv_zM39rslnpRTc1QZVV1DSJLII3kPN0ahkg8,6048
+php_parser_py/_resources/print.php,sha256=2YDlnK3XPJkqulabrpItAA3HlUDXMgjiO8G3vcrLT7k,5987
+php_parser_py/_resources/transport.php,sha256=WTkEf85Lx8rQ9gojqWC1aGo7tp3XR148M1o8B1OR2K4,6767
 php_parser_py/_runtime/__init__.py,sha256=gKauz8DvQxNUQyNMLfPgy08tEoyIxXsmWb_96bHheJE,223
 php_parser_py/_runtime/_binary.py,sha256=OrldT-rcPjA7P8PeDPNd717BPNfN2hXgwoUe63YWzl0,4145
 php_parser_py/_runtime/_bundle.py,sha256=tIWRCmDuIVGmmSYjtUD-i04rIFJcBIzIjpRM5dpIu7Y,5567
-php_parser_py/_runtime/_runner.py,sha256=-srSLadX2eR13BqOfvXkY0iJ68XH50TX0YBVD1PyAbs,9480
+php_parser_py/_runtime/_runner.py,sha256=MDvHIrBfeCq5Lw4qlYx2_W1Yj9mzG5vxUunNvqtVtNI,10044
 php_parser_py/_transport.py,sha256=J4qo0c8gBEGv05Vww59QnkDZ1R0Bjzrjtr8mV2xbCjo,3873
-php_parser_py/_types.py,sha256=E_eNJqyWN8guIlNGmSs7qILmT9xa289IdjiwaeGMzSA,2719
+php_parser_py/_types.py,sha256=70aTz0AbMsJjQb_5w_t8yVYVqg8GZonXi_2HHGDoF5o,2925
+php_parser_py/_version.py,sha256=ZFkpcL_cP2MZyPOwMy4QX68MTVNhYw77F3MNa41dXuo,1760
 php_parser_py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 php_parser_py/_resources/php.exe,sha256=yv_KdAxqo8Pc_xrwnCjdBA2_jn24PL1V4TB1Aey34vY,9529856
-php_parser_py-1.2.6.dist-info/METADATA,sha256=pO-QeApnKgXthtQees0JvDRi9BNe84r-DR-ViNukLhE,3544
-php_parser_py-1.2.6.dist-info/WHEEL,sha256=eOph205RIaepfK4qdVVjtNnzanETS7NC0N2C0Ks5Yc8,104
-php_parser_py-1.2.6.dist-info/licenses/LICENSE,sha256=gXf5dRMhNSbfLPYYTY_5hsZ1r7UU1OaKQEAQUhuIBkM,18092
-php_parser_py-1.2.6.dist-info/licenses/PHP-LICENSE,sha256=tC5N9eUObs2hBH1QPW2R1xAy0J7RAnuh7ynu0m-JDFo,3204
-php_parser_py-1.2.6.dist-info/licenses/PHP-Parser-LICENSE,sha256=3YWeEH-sn4ekQTq4w8lvDxYRoX9Zai21YqWk9JBMHpc,1520
-php_parser_py-1.2.6.dist-info/licenses/Zend-Engine-LICENSE,sha256=UJrrO-ZOQo1-AATOIkYgqwG_lK2qzvu0SWEZOd9WvFs,2803
-php_parser_py-1.2.6.dist-info/RECORD,,
+php_parser_py-2.0.3.dist-info/METADATA,sha256=JC0zDNsthV9OCG-fCpYYG3KQYJiADU7-6jRNKt5Lxp8,3893
+php_parser_py-2.0.3.dist-info/WHEEL,sha256=eOph205RIaepfK4qdVVjtNnzanETS7NC0N2C0Ks5Yc8,104
+php_parser_py-2.0.3.dist-info/licenses/LICENSE,sha256=gXf5dRMhNSbfLPYYTY_5hsZ1r7UU1OaKQEAQUhuIBkM,18092
+php_parser_py-2.0.3.dist-info/licenses/PHP-LICENSE,sha256=tC5N9eUObs2hBH1QPW2R1xAy0J7RAnuh7ynu0m-JDFo,3204
+php_parser_py-2.0.3.dist-info/licenses/PHP-Parser-LICENSE,sha256=3YWeEH-sn4ekQTq4w8lvDxYRoX9Zai21YqWk9JBMHpc,1520
+php_parser_py-2.0.3.dist-info/licenses/Zend-Engine-LICENSE,sha256=UJrrO-ZOQo1-AATOIkYgqwG_lK2qzvu0SWEZOd9WvFs,2803
+php_parser_py-2.0.3.dist-info/RECORD,,