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

php_parser_py/_resources/ExtendedPrinter.php

@@ -0,0 +1,212 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blv;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\Assign;
+use PhpParser\Node\Expr\CallLike;
+use PhpParser\Node\Expr\Instanceof_;
+use PhpParser\Node\Expr\Yield_;
+use PhpParser\Node\Scalar\String_;
+use PhpParser\Node\Stmt\Declare_;
+use PhpParser\Node\Stmt\Nop;
+use PhpParser\PrettyPrinter\Standard;
+
+/**
+ * Attribute marking a node whose printed form must be wrapped in parens.
+ */
+const FORMAT_WRAP_PARENS = '__format_wrap_parens';
+
+/**
+ * Attribute marking a string node whose value is emitted raw (unescaped).
+ */
+const FORMAT_REGEX = '__format_regex';
+
+/**
+ * Standard printer with selective printer-bug fixes.
+ *
+ * Each override defers to its parent method and transforms the result, or
+ * rebuilds the same output from parent-shaped parts. Overrides affect only
+ * reprinted (modified or inserted) nodes, so an unmodified round-trip is
+ * inert.
+ */
+class ExtendedPrinter extends Standard
+{
+    /**
+     * Reindex statements from 0 and guarantee a trailing PHP_EOL.
+     */
+    public function prettyPrintFile(array $stmts): string
+    {
+        $stmts = array_values($stmts);
+        $code = parent::prettyPrintFile($stmts);
+        if (!str_ends_with($code, PHP_EOL)) {
+            $code .= PHP_EOL;
+        }
+        return $code;
+    }
+
+    /**
+     * Print declare(...) with a whitespace-free header.
+     *
+     * The parent emits "declare (" and ", " item separators. A regex over
+     * its output would also mangle a block body or a string item value, so
+     * the statement is rebuilt with parent-shaped parts instead.
+     */
+    protected function pStmt_Declare(Declare_ $node): string
+    {
+        $items = array_map(fn (Node $item): string => $this->p($item), $node->declares);
+        $header = 'declare(' . implode(',', $items) . ')';
+        if ($node->stmts === null) {
+            return $header . ';';
+        }
+        return $header . ' {' . $this->pStmts($node->stmts) . $this->nl . '}';
+    }
+
+    /**
+     * Strip leading whitespace on blank lines produced before a Nop node.
+     */
+    protected function pArray(
+        array $nodes,
+        array $origNodes,
+        int &$pos,
+        int $indentAdjustment,
+        string $parentNodeClass,
+        string $subNodeName,
+        ?int $fixup
+    ): ?string {
+        $code = parent::pArray(
+            $nodes,
+            $origNodes,
+            $pos,
+            $indentAdjustment,
+            $parentNodeClass,
+            $subNodeName,
+            $fixup
+        );
+        if ($code === null) {
+            return null;
+        }
+        $hasNop = false;
+        foreach ($nodes as $node) {
+            if ($node instanceof Nop) {
+                $hasNop = true;
+                break;
+            }
+        }
+        if (!$hasNop) {
+            return $code;
+        }
+        return preg_replace('/^[ \t]+$/m', '', $code);
+    }
+
+    /**
+     * Mark an assignment left operand for parenthesization.
+     *
+     * When the left operand is itself an assignment that came from the
+     * original source while the right operand was created after parsing,
+     * the reprinted form needs explicit parentheses to preserve precedence.
+     */
+    private function wrapAssign(Node $left, Node $right): void
+    {
+        if ($left instanceof Assign
+            && $left->getStartTokenPos() > 0
+            && $right->getStartTokenPos() < 0
+        ) {
+            $left->setAttribute(FORMAT_WRAP_PARENS, true);
+        }
+    }
+
+    /**
+     * Flag a chained-assignment left operand before infix printing.
+     */
+    protected function pInfixOp(
+        string $class,
+        Node $leftNode,
+        string $operatorString,
+        Node $rightNode,
+        int $precedence,
+        int $lhsPrecedence
+    ): string {
+        $this->wrapAssign($leftNode, $rightNode);
+        return parent::pInfixOp(
+            $class,
+            $leftNode,
+            $operatorString,
+            $rightNode,
+            $precedence,
+            $lhsPrecedence
+        );
+    }
+
+    /**
+     * Flag a chained-assignment left operand before instanceof printing.
+     */
+    protected function pExpr_Instanceof(
+        Instanceof_ $node,
+        int $precedence,
+        int $lhsPrecedence
+    ): string {
+        $this->wrapAssign($node->expr, $node->class);
+        return parent::pExpr_Instanceof($node, $precedence, $lhsPrecedence);
+    }
+
+    /**
+     * Parenthesize a yield used as an assigned value.
+     */
+    protected function pExpr_Assign(
+        Assign $node,
+        int $precedence,
+        int $lhsPrecedence
+    ): string {
+        if ($node->expr instanceof Yield_) {
+            $node->expr->setAttribute(FORMAT_WRAP_PARENS, true);
+        }
+        return parent::pExpr_Assign($node, $precedence, $lhsPrecedence);
+    }
+
+    /**
+     * Wrap a node's printed form in parentheses when flagged.
+     */
+    protected function p(
+        Node $node,
+        int $precedence = self::MAX_PRECEDENCE,
+        int $lhsPrecedence = self::MAX_PRECEDENCE,
+        bool $parentFormatPreserved = false
+    ): string {
+        $result = parent::p($node, $precedence, $lhsPrecedence, $parentFormatPreserved);
+        if ($node instanceof CallLike && $node->isFirstClassCallable()) {
+            $result = $this->dropPlaceholderComma($result);
+        }
+        if ($node->getAttribute(FORMAT_WRAP_PARENS)) {
+            return '(' . $result . ')';
+        }
+        return $result;
+    }
+
+    /**
+     * Remove a stray comma left after a first-class-callable placeholder.
+     *
+     * Format-preserving printing copies the original inner formatting around
+     * the argument list. When the call gains a "..." placeholder, the copied
+     * trailing comma becomes invalid syntax; drop it while keeping spacing.
+     * The printed call ends with its own argument list, so the anchor keeps
+     * the pattern away from an identical byte run inside a string literal.
+     */
+    private function dropPlaceholderComma(string $code): string
+    {
+        return preg_replace('/(\.\.\.\s*),(\s*\))\z/', '$1$2', $code);
+    }
+
+    /**
+     * Emit a regex string verbatim when the node is flagged.
+     */
+    protected function pScalar_String(String_ $node): string
+    {
+        if ($node->getAttribute(FORMAT_REGEX)) {
+            return $node->value;
+        }
+        return parent::pScalar_String($node);
+    }
+}

php_parser_py/_resources/parse.php

@@ -0,0 +1,112 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Parse PHP source into a JSON AST.
+ *
+ * Reads one JSON object from stdin: {"phar_path": string, "code": string}.
+ * 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
+ * {"error": ...} with exit 1 on any other failure.
+ */
+
+require __DIR__ . '/transport.php';
+
+error_reporting(E_ALL & ~E_DEPRECATED);
+
+/**
+ * Report a json_encode failure as an error envelope instead of silently
+ * printing nothing (json_encode returns false). Never returns.
+ */
+function emit_encode_failure(): void
+{
+    // Scrub invalid bytes so the envelope itself always encodes.
+    echo json_encode(
+        ['error' => 'AST JSON encoding failed: ' . json_last_error_msg()],
+        JSON_INVALID_UTF8_SUBSTITUTE
+    );
+    exit(1);
+}
+
+/**
+ * Emit a diagnostic envelope as JSON. Error messages may quote raw source
+ * bytes; scrubbing them keeps the diagnostic deliverable.
+ */
+function emit_json($value): void
+{
+    $json = json_encode($value, 0, PPPY_JSON_DEPTH);
+    if ($json === false) {
+        $json = json_encode($value, JSON_INVALID_UTF8_SUBSTITUTE, PPPY_JSON_DEPTH);
+    }
+    if ($json === false) {
+        emit_encode_failure();
+    }
+    echo $json;
+}
+
+/**
+ * Emit the statements as JSON. String values holding invalid UTF-8 (or
+ * colliding with a marker prefix) and non-finite floats are wrapped in
+ * channel-safe transport markers, applied lazily so the common case
+ * skips the walk. JSON_PRESERVE_ZERO_FRACTION keeps whole-number floats
+ * float-typed: without it 2.0 emits as "2" and Python decodes an int.
+ */
+function emit_stmts(?array $stmts): void
+{
+    $json = json_encode($stmts, JSON_PRESERVE_ZERO_FRACTION, PPPY_JSON_DEPTH);
+    $recoverable = [JSON_ERROR_UTF8, JSON_ERROR_INF_OR_NAN];
+    $needs_escape = ($json === false && in_array(json_last_error(), $recoverable, true))
+        || ($json !== false && strpos($json, '\\u0000pppy') !== false);
+    if ($needs_escape) {
+        $json = json_encode(
+            pppy_encode_tree($stmts),
+            JSON_PRESERVE_ZERO_FRACTION,
+            PPPY_JSON_DEPTH
+        );
+    }
+    if ($json === false) {
+        emit_encode_failure();
+    }
+    echo $json;
+}
+
+$raw = file_get_contents('php://stdin');
+$payload = json_decode($raw, true);
+if ($payload === null) {
+    fwrite(STDERR, 'parse.php: payload decode failed: ' . json_last_error_msg()
+        . ' (bytes=' . strlen($raw) . ")\n");
+    exit(2);
+}
+require_once 'phar://' . $payload['phar_path'] . '/vendor/autoload.php';
+
+use PhpParser\ErrorHandler\Collecting;
+use PhpParser\ParserFactory;
+
+$code = base64_decode($payload['code'], true);
+if ($code === false) {
+    fwrite(STDERR, "parse.php: code field is not valid base64\n");
+    exit(2);
+}
+$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());
+        emit_json(['errors' => $errors]);
+        exit(0);
+    }
+    // PHP-Parser nodes implement JsonSerializable, so encode them directly.
+    emit_stmts($stmts);
+} catch (Throwable $e) {
+    // Throwable, not Exception: engine-level Error must also become a
+    // reportable envelope instead of an uncaught fatal.
+    echo json_encode(['error' => $e->getMessage()], JSON_INVALID_UTF8_SUBSTITUTE);
+    exit(1);
+}

php_parser_py/_resources/print.php

@@ -0,0 +1,150 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Render a JSON AST back into PHP source.
+ *
+ * Reads one JSON object from stdin:
+ *   {
+ *     "phar_path": string,      // php-parser.phar for the autoloader
+ *     "extended_path": string,  // Blv\ExtendedPrinter source file
+ *     "printer_class": string,  // FQCN to instantiate (read as data)
+ *     "mode": string,           // "full_rewrite" | "format_preserving"
+ *     "stmts": string,          // JSON of the (modified) statements
+ *     "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
+ * generated PHP on success, or {"error": ...} with exit 1 on failure.
+ */
+
+require __DIR__ . '/transport.php';
+
+error_reporting(E_ALL & ~E_DEPRECATED);
+
+$raw = file_get_contents('php://stdin');
+$payload = json_decode($raw, true);
+if ($payload === null) {
+    fwrite(STDERR, 'print.php: payload decode failed: ' . json_last_error_msg()
+        . ' (bytes=' . strlen($raw) . ")\n");
+    exit(2);
+}
+require_once 'phar://' . $payload['phar_path'] . '/vendor/autoload.php';
+require_once $payload['extended_path'];
+
+use PhpParser\JsonDecoder;
+use PhpParser\ParserFactory;
+
+try {
+    $stmts = pppy_decode_stmts($payload['stmts']);
+    // Restore raw bytes and non-finite floats the Python side marker-wrapped.
+    $stmts = pppy_decode_tree($stmts);
+
+    // Normalize the FQCN and instantiate by name (class name travels as data).
+    $printerClass = '\\' . ltrim($payload['printer_class'], '\\');
+    $printer = new $printerClass();
+
+    // 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));
+    } else {
+        echo base64_encode($printer->prettyPrintFile($stmts));
+    }
+} catch (Throwable $e) {
+    // Throwable, not Exception: engine-level Error (e.g. an unknown printer
+    // class) must also become a reportable envelope, not an uncaught fatal.
+    // Scrub invalid bytes so the envelope itself always encodes.
+    echo json_encode(['error' => $e->getMessage()], JSON_INVALID_UTF8_SUBSTITUTE);
+    exit(1);
+}
+
+/**
+ * Decode the statements JSON and rebuild PhpParser nodes.
+ *
+ * parse.php encodes at PPPY_JSON_DEPTH, so the decode here must accept the
+ * same nesting; JsonDecoder::decode hard-codes json_decode's default
+ * 512-level cap, hence the JSON is decoded here and the private node
+ * reconstruction step is reached through reflection. A float marker in a
+ * node field position would hit a typed float property inside JsonDecoder
+ * (strict_types TypeError), so hoist markers into an untyped attribute
+ * first. Python's json.dumps escapes the marker NUL bytes, hence the
+ * escaped-needle check.
+ */
+function pppy_decode_stmts(string $stmtsJson): array
+{
+    $data = json_decode($stmtsJson, true, PPPY_JSON_DEPTH);
+    if (json_last_error()) {
+        throw new RuntimeException(
+            'stmts decoding failed: ' . json_last_error_msg()
+        );
+    }
+    if (strpos($stmtsJson, '\\u0000pppyf') !== false) {
+        pppy_hoist_floats($data);
+    }
+    $reconstruct = new ReflectionMethod(JsonDecoder::class, 'decodeRecursive');
+    return $reconstruct->invoke(new JsonDecoder(), $data);
+}
+
+/**
+ * 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();
+    $origStmts = $parser->parse($origSource);
+    $origTokens = $parser->getTokens();
+
+    $index = [];
+    $collect = function ($nodes) use (&$collect, &$index) {
+        foreach ($nodes as $node) {
+            if (!$node instanceof PhpParser\Node) {
+                continue;
+            }
+            $start = $node->getStartTokenPos();
+            $end = $node->getEndTokenPos();
+            if ($start >= 0 && $end >= 0) {
+                $key = $start . ':' . $end . ':' . get_class($node);
+                $index[$key] = $node;
+            }
+            foreach ($node->getSubNodeNames() as $name) {
+                $child = $node->$name;
+                if ($child instanceof PhpParser\Node) {
+                    $collect([$child]);
+                } elseif (is_array($child)) {
+                    $collect($child);
+                }
+            }
+        }
+    };
+    $collect($origStmts);
+
+    $link = function ($nodes) use (&$link, &$index) {
+        foreach ($nodes as $node) {
+            if (!$node instanceof PhpParser\Node) {
+                continue;
+            }
+            $start = $node->getStartTokenPos();
+            $end = $node->getEndTokenPos();
+            $key = $start . ':' . $end . ':' . get_class($node);
+            if ($start >= 0 && $end >= 0 && isset($index[$key])) {
+                $node->setAttribute('origNode', $index[$key]);
+            }
+            foreach ($node->getSubNodeNames() as $name) {
+                $child = $node->$name;
+                if ($child instanceof PhpParser\Node) {
+                    $link([$child]);
+                } elseif (is_array($child)) {
+                    $link($child);
+                }
+            }
+        }
+    };
+    $link($stmts);
+
+    return $printer->printFormatPreserving($stmts, $origStmts, $origTokens);
+}

php_parser_py/_resources/transport.php

@@ -0,0 +1,195 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Byte-safe value codec for the Python JSON channel.
+ *
+ * JSON is UTF-8 only and rejects non-finite floats, but PHP source and
+ * string values are raw bytes and float values may be INF or NAN. A
+ * 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.
+ */
+
+// json_encode/json_decode default to a 512-level nesting cap, rejecting
+// deeply nested but valid ASTs; the engine's own parse recursion gives out
+// long before this ceiling. One depth for both channel directions, so
+// print.php accepts every AST parse.php emitted.
+const PPPY_JSON_DEPTH = 1000000;
+
+const PPPY_STR_MARKER = "\x00pppy\x00";
+const PPPY_FLOAT_MARKER = "\x00pppyf\x00";
+const PPPY_MARKER_PREFIX = "\x00pppy"; // common prefix of both markers
+// Node attribute carrying hoisted non-finite float fields (see
+// pppy_hoist_floats): {field name => 'inf'|'-inf'|'nan'}.
+const PPPY_NONFINITE_ATTR = 'pppy_nonfinite';
+
+/**
+ * Wrap a channel-unsafe value in a transport marker: a string that is
+ * not valid UTF-8 (or collides with a marker prefix), or a non-finite
+ * float.
+ */
+function pppy_encode_value($value)
+{
+    if (is_string($value)) {
+        // json_encode doubles as the exact "will the channel accept it" check.
+        if (!str_starts_with($value, PPPY_MARKER_PREFIX)
+            && json_encode($value) !== false
+        ) {
+            return $value;
+        }
+        return PPPY_STR_MARKER . base64_encode($value);
+    }
+    if (is_float($value) && !is_finite($value)) {
+        return PPPY_FLOAT_MARKER . pppy_float_name($value);
+    }
+    return $value;
+}
+
+/** Restore the original value of a marker-wrapped string. */
+function pppy_decode_value($value)
+{
+    if (!is_string($value) || !str_starts_with($value, PPPY_MARKER_PREFIX)) {
+        return $value;
+    }
+    if (str_starts_with($value, PPPY_STR_MARKER)) {
+        return base64_decode(substr($value, strlen(PPPY_STR_MARKER)));
+    }
+    if (str_starts_with($value, PPPY_FLOAT_MARKER)) {
+        return pppy_float_from_name(substr($value, strlen(PPPY_FLOAT_MARKER)));
+    }
+    return $value;
+}
+
+/** Spell a non-finite float the way Python's repr() does. */
+function pppy_float_name(float $value): string
+{
+    if (is_nan($value)) {
+        return 'nan';
+    }
+    return $value === INF ? 'inf' : '-inf';
+}
+
+/** Parse a Python-repr non-finite float name back to a PHP float. */
+function pppy_float_from_name(string $name): float
+{
+    switch ($name) {
+        case 'inf':
+            return INF;
+        case '-inf':
+            return -INF;
+        case 'nan':
+            return NAN;
+    }
+    throw new RuntimeException("Unknown transport float name: $name");
+}
+
+/**
+ * Convert nodes to their JSON-plain form with channel-unsafe leaves
+ * wrapped. Mirrors json_encode's JsonSerializable handling; typed node
+ * properties reject marker strings, the plain array form does not.
+ */
+function pppy_encode_tree($value)
+{
+    if ($value instanceof JsonSerializable) {
+        return pppy_encode_tree($value->jsonSerialize());
+    }
+    if (is_array($value)) {
+        foreach ($value as $key => $item) {
+            $value[$key] = pppy_encode_tree($item);
+        }
+        return $value;
+    }
+    return pppy_encode_value($value);
+}
+
+/**
+ * Move float markers out of node field positions into an untyped node
+ * attribute, leaving 0.0 behind. JsonDecoder assigns fields into typed
+ * node properties under strict_types, so a marker string in a
+ * float-typed field would throw; attributes travel as plain arrays.
+ */
+function pppy_hoist_floats(array &$value): void
+{
+    foreach ($value as &$item) {
+        if (is_array($item)) {
+            pppy_hoist_floats($item);
+        }
+    }
+    unset($item);
+    if (!isset($value['nodeType'])) {
+        return;
+    }
+    foreach ($value as $field => $item) {
+        if ($field === 'nodeType' || $field === 'attributes') {
+            continue;
+        }
+        if (is_string($item) && str_starts_with($item, PPPY_FLOAT_MARKER)) {
+            $value['attributes'][PPPY_NONFINITE_ATTR][$field] =
+                substr($item, strlen(PPPY_FLOAT_MARKER));
+            $value[$field] = 0.0;
+        }
+    }
+}
+
+/**
+ * Restore marker-wrapped strings and hoisted non-finite floats across
+ * a decoded node tree: arrays, node subnodes, node attributes, and
+ * comment text.
+ */
+function pppy_decode_tree($value)
+{
+    if (is_string($value)) {
+        return pppy_decode_value($value);
+    }
+    if (is_array($value)) {
+        foreach ($value as $key => $item) {
+            $value[$key] = pppy_decode_tree($item);
+        }
+        return $value;
+    }
+    if ($value instanceof PhpParser\Comment) {
+        return pppy_decode_comment($value);
+    }
+    if ($value instanceof PhpParser\Node) {
+        pppy_decode_node($value);
+    }
+    return $value;
+}
+
+/** Decode one node in place: subnodes, attributes, hoisted floats. */
+function pppy_decode_node(PhpParser\Node $node): void
+{
+    foreach ($node->getSubNodeNames() as $name) {
+        $node->$name = pppy_decode_tree($node->$name);
+    }
+    $attrs = pppy_decode_tree($node->getAttributes());
+    if (isset($attrs[PPPY_NONFINITE_ATTR])) {
+        foreach ($attrs[PPPY_NONFINITE_ATTR] as $field => $name) {
+            $node->$field = pppy_float_from_name($name);
+        }
+        unset($attrs[PPPY_NONFINITE_ATTR]);
+    }
+    $node->setAttributes($attrs);
+}
+
+/** Rebuild a comment with decoded text, keeping its positions. */
+function pppy_decode_comment(PhpParser\Comment $comment)
+{
+    $text = pppy_decode_value($comment->getText());
+    if ($text === $comment->getText()) {
+        return $comment;
+    }
+    $class = get_class($comment);
+    return new $class(
+        $text,
+        $comment->getStartLine(),
+        $comment->getStartFilePos(),
+        $comment->getStartTokenPos(),
+        $comment->getEndLine(),
+        $comment->getEndFilePos(),
+        $comment->getEndTokenPos()
+    );
+}

php_parser_py/_runtime/__init__.py

@@ -0,0 +1,11 @@
+"""PHP runtime layer: binary resolution, bundled archives, script runner."""
+
+from __future__ import annotations
+
+__all__ = [
+    "Runner",
+    "resolve_php",
+]
+
+from ._binary import resolve_php
+from ._runner import Runner