Debian Codegraph @

vendor/ipl/web/src/Less/PreEvalVisitor.php

raw
1 <?php
2
3 namespace ipl\Web\Less;
4
5 use Less_Parser;
6 use Less_Tree;
7 use Less_VisitorReplacing;
8
9 /**
10 * Base class for Less pre-evaluation AST visitors
11 *
12 * Subclasses hook into the pre-`compile()` phase of the Less parser,
13 * receiving the raw parsed AST before variables, functions, and mixins are resolved.
14 * Override {@see init()} to set up any state the visitor needs before traversal.
15 *
16 * {@see run()} clones the instance before each traversal so that the clean state
17 * established by {@see init()} is preserved across multiple runs. The same instance
18 * can therefore be safely passed to multiple parsers without state from one traversal
19 * leaking into the next.
20 *
21 * Subclasses whose {@see init()} assigns object-type properties must also implement
22 * `__clone()` to deep-copy those objects, as PHP's default `clone` is shallow and
23 * would otherwise leave both copies sharing the same object reference.
24 */
25 abstract class PreEvalVisitor extends Less_VisitorReplacing
26 {
27 /**
28 * Control the visitor execution phase
29 *
30 * When `true`, this visitor runs in the pre-`compile()` phase,
31 * receiving the raw parsed AST before variables, functions, and mixins are resolved.
32 *
33 * @phpstan-ignore property.neverRead (Used by {@see Less_Parser::PreVisitors()})
34 *
35 * @var true
36 *
37 * @link https://github.com/wikimedia/less.php/blob/v5.5.0/lib/Less/Parser.php#L405
38 */
39 public readonly true $isPreEvalVisitor;
40
41 public function __construct()
42 {
43 parent::__construct();
44
45 $this->isPreEvalVisitor = true;
46 $this->init();
47 }
48
49 /**
50 * Workaround for a port bug in wikimedia/less.php
51 *
52 * {@see Less_Tree_Import::accept()} calls `$visitor->visit($this->root)` instead
53 * of `$visitor->visitObj($this->root)`. In less.js, the visitor's main
54 * type-dispatch method is named `visit()`; the PHP port renamed it to `visitObj()`
55 * but missed this one call site in `Import::accept()`, leaving it referencing a
56 * method that does not exist on {@see Less_VisitorReplacing}.
57 *
58 * Pre-eval visitors are the only ones affected: {@see Less_ImportVisitor} runs
59 * first and populates `Import::$root` with each imported file's parsed ruleset, so
60 * the `$root` branch in `accept()` is always taken during pre-eval traversal.
61 * Post-eval visitors never hit it because `$root->compile()` inlines the import
62 * contents beforehand, dissolving the `Import` nodes entirely.
63 *
64 * Delegates to {@see visitObj()} to preserve normal type dispatch.
65 *
66 * @param Less_Tree $node The imported file's root ruleset
67 *
68 * @return Less_Tree The visited node, potentially replaced
69 *
70 * @link https://github.com/wikimedia/less.php/blob/v5.5.0/lib/Less/Tree/Import.php#L84
71 */
72 public function visit(Less_Tree $node): Less_Tree
73 {
74 return $this->visitObj($node);
75 }
76
77
78 /**
79 * Visitor entrypoint called by {@see Less_Parser::PreVisitors()}
80 *
81 * Clones this instance for a fresh copy of the construction-time state established by
82 * {@see init()}, starts traversal on the clone, and leaves the original untouched.
83 * Subclasses may override this to intentionally modify `$tree` (e.g., injecting helper nodes
84 * before traversal) — see {@see DetachedRulesetCallVisitor::run()} for an example.
85 *
86 * @param Less_Tree $tree The root AST node to traverse
87 *
88 * @return void
89 *
90 * @link https://github.com/wikimedia/less.php/blob/v5.5.0/lib/Less/Parser.php#L406
91 */
92 public function run(Less_Tree $tree): void
93 {
94 $clone = clone $this;
95 $clone->visitObj($tree);
96 }
97
98 /**
99 * Set up visitor state at construction time
100 *
101 * Called once from {@see __construct()}; {@see run()} clones the instance before each
102 * traversal so this state serves as the clean starting point for every run. Subclasses
103 * assigning object-type properties must implement `__clone()` to deep-copy them.
104 *
105 * @return void
106 */
107 protected function init(): void
108 {
109 }
110 }