| 1 |
<?php |
| 2 |
|
| 3 |
namespace ipl\Web\Less; |
| 4 |
|
| 5 |
use Less_Functions; |
| 6 |
use Less_Tree_Call; |
| 7 |
use Less_Tree_Color; |
| 8 |
use Less_Tree_Keyword; |
| 9 |
use Less_Tree_Mixin_Call; |
| 10 |
use Less_Tree_Mixin_Definition; |
| 11 |
use Less_Tree_Variable; |
| 12 |
use SplDoublyLinkedList; |
| 13 |
|
| 14 |
/** |
| 15 |
* Replace Less color variables with CSS `var()` function calls |
| 16 |
* |
| 17 |
* Every color variable reference (even nested aliases) is replaced with a `var(--name, fallback)` call. |
| 18 |
* The visitor is scope-aware: it excludes mixin parameter names from replacement and disables replacement |
| 19 |
* inside built-in Less functions that require resolved color values. |
| 20 |
* |
| 21 |
* See the following example Less and resolved CSS for a rough overview of the visitor features. |
| 22 |
* Note that at-signs used for Less variables are omitted because PHPStorm interprets them as annotations. |
| 23 |
* |
| 24 |
* Less: |
| 25 |
* ``` |
| 26 |
* bg-color: black; |
| 27 |
* text-color: white; |
| 28 |
* |
| 29 |
* body { |
| 30 |
* background-color: bg-color; |
| 31 |
* color: text-color; |
| 32 |
* } |
| 33 |
* ``` |
| 34 |
* |
| 35 |
* CSS: |
| 36 |
* ``` |
| 37 |
* body { |
| 38 |
* background-color: var(--bg-color, black); |
| 39 |
* color: var(--text-color, white); |
| 40 |
* } |
| 41 |
* ``` |
| 42 |
*/ |
| 43 |
class CssVarVisitor extends PreEvalVisitor |
| 44 |
{ |
| 45 |
/** |
| 46 |
* Boolean stack that gates CSS `var()` replacement during compilation |
| 47 |
* |
| 48 |
* Push `false` when you compile a context that must see resolved Less values (e.g., built-in Less functions), |
| 49 |
* and pop it when you leave that context. Keep at least one frame on the stack at all times. |
| 50 |
* |
| 51 |
* @var SplDoublyLinkedList<bool> |
| 52 |
*/ |
| 53 |
protected SplDoublyLinkedList $replaceCssVars; |
| 54 |
|
| 55 |
/** |
| 56 |
* Stack of mixin parameter names to exclude from CSS `var()` replacement |
| 57 |
* |
| 58 |
* Each frame represents one mixin definition currently being visited and contains its parameter names. |
| 59 |
* Frames are kept in innermost-first order: {@see visitMixinDefinition()} prepends each new frame, |
| 60 |
* so index 0 always holds the currently active scope. This lets {@see visitVariable()} iterate |
| 61 |
* forward without reversing to check the nearest enclosing scope first. |
| 62 |
* |
| 63 |
* @var list<list<string>> |
| 64 |
*/ |
| 65 |
protected array $mixinParams = []; |
| 66 |
|
| 67 |
/** |
| 68 |
* Handle a {@see Less_Tree_Call} node during AST traversal |
| 69 |
* |
| 70 |
* Call nodes represent both built-in Less functions (e.g., `fade()`) and CSS functions (e.g., `calc()`). |
| 71 |
* Less.php calls our {@see visitVariable()} for function call arguments, |
| 72 |
* potentially replacing them with CSS `var()` calls. |
| 73 |
* That behavior is desired for CSS functions such as `calc()`, but it breaks built-in Less functions |
| 74 |
* such as `fade()`, because they require resolved values. To preserve Less semantics, |
| 75 |
* this method replaces the call node that compiles twice if applicable: |
| 76 |
* |
| 77 |
* - First pass: disable CSS `var()` replacement while compiling the call (so built-in Less functions see |
| 78 |
* resolved values). |
| 79 |
* |
| 80 |
* - Second pass: if compilation still returns a call node, treat it as a CSS function and recompile with |
| 81 |
* CSS `var()` replacement enabled again. |
| 82 |
* |
| 83 |
* Given the context `icinga-red: red`, this ensures that: |
| 84 |
* |
| 85 |
* - `fade(icinga-red)` compiles to `fade(red)`. |
| 86 |
* - `calc(icinga-red)` compiles to `calc(var(--icinga-red, red))`. |
| 87 |
* |
| 88 |
* @param Less_Tree_Call $c The function call node being visited |
| 89 |
* |
| 90 |
* @return Less_Tree_Call A new call node replacing the original with adjusted `compile()` logic |
| 91 |
* |
| 92 |
* @see visitVariable() For variable replacement logic |
| 93 |
* @see Less_Functions For built-in Less functions |
| 94 |
*/ |
| 95 |
public function visitCall(Less_Tree_Call $c): Less_Tree_Call |
| 96 |
{ |
| 97 |
$call = new class ($c->name, $c->args, $c->index, $c->currentFileInfo) extends Less_Tree_Call { |
| 98 |
/** @var SplDoublyLinkedList<bool> */ |
| 99 |
public SplDoublyLinkedList $replaceCssVars; |
| 100 |
|
| 101 |
public function compile($env) |
| 102 |
{ |
| 103 |
// Temporarily disable CSS `var()` replacement for current call node arguments. |
| 104 |
$this->replaceCssVars->push(false); |
| 105 |
$compiled = parent::compile($env); |
| 106 |
$this->replaceCssVars->pop(); |
| 107 |
|
| 108 |
if ($compiled instanceof Less_Tree_Call) { |
| 109 |
// Built-in Less functions (e.g. `fade()`) compile to a specific value (e.g. Color), |
| 110 |
// whereas CSS functions (e.g. `calc()`) remain a call node after compilation. |
| 111 |
// Recompile such call nodes with CSS `var()` replacement enabled for arguments. |
| 112 |
// (Note: Replacement might still be disabled due to nested function calls.) |
| 113 |
$compiled = parent::compile($env); |
| 114 |
} |
| 115 |
|
| 116 |
return $compiled; |
| 117 |
} |
| 118 |
}; |
| 119 |
$call->replaceCssVars = $this->replaceCssVars; |
| 120 |
|
| 121 |
return $call; |
| 122 |
} |
| 123 |
|
| 124 |
/** |
| 125 |
* Handle a {@see Less_Tree_Variable} node during AST traversal |
| 126 |
* |
| 127 |
* Less variable nodes represent unresolved references that Less.php resolves during compilation. |
| 128 |
* This visitor replaces variable nodes that compile to a CSS `var()` call, unless: |
| 129 |
* |
| 130 |
* 1. The variable is a mixin parameter name. |
| 131 |
* 2. It is an argument to a built-in Less function. |
| 132 |
* 3. The resolved value is not a color or not already a CSS `var()` call. |
| 133 |
* |
| 134 |
* Mixin parameters are special: they behave like variables, but must not be replaced with CSS `var()` calls. |
| 135 |
* The parameter stack maintained by {@see visitMixinDefinition()} and {@see visitMixinDefinitionOut()} |
| 136 |
* provides context to ignore them. |
| 137 |
* |
| 138 |
* @param Less_Tree_Variable $v The variable node being visited |
| 139 |
* |
| 140 |
* @return Less_Tree_Variable The original variable if it is a mixin parameter; otherwise a |
| 141 |
* replacement variable node that compiles to a CSS `var()` call if applicable |
| 142 |
* |
| 143 |
* @see visitCall() For disabling replacement in built-in Less functions |
| 144 |
* @see visitMixinDefinition() For mixin parameter stack setup |
| 145 |
* @see visitMixinDefinitionOut() For mixin parameter stack teardown |
| 146 |
*/ |
| 147 |
public function visitVariable(Less_Tree_Variable $v): Less_Tree_Variable |
| 148 |
{ |
| 149 |
foreach ($this->mixinParams as $ignoreVars) { |
| 150 |
if (in_array($v->name, $ignoreVars, true)) { |
| 151 |
return $v; |
| 152 |
} |
| 153 |
} |
| 154 |
|
| 155 |
$variable = new class ($v->name, $v->index, $v->currentFileInfo) extends Less_Tree_Variable { |
| 156 |
/** @var SplDoublyLinkedList<bool> */ |
| 157 |
public SplDoublyLinkedList $replaceCssVars; |
| 158 |
|
| 159 |
public function compile($env) |
| 160 |
{ |
| 161 |
$compiled = parent::compile($env); |
| 162 |
|
| 163 |
// Do not replace variable with CSS `var()` function call if... |
| 164 |
if ( |
| 165 |
// ... replacing CSS vars is disabled because a function call is compiled, |
| 166 |
! $this->replaceCssVars->top() |
| 167 |
// ... or the compiled variable is neither a color nor a CSS `var()` call. |
| 168 |
|| ( |
| 169 |
! $compiled instanceof Less_Tree_Color |
| 170 |
&& (! $compiled instanceof Less_Tree_Call || $compiled->name !== 'var') |
| 171 |
) |
| 172 |
) { |
| 173 |
return $compiled; |
| 174 |
} |
| 175 |
|
| 176 |
// Remove '@' from name. |
| 177 |
$name = substr($this->name, 1); |
| 178 |
|
| 179 |
if ($name[0] === '@') { |
| 180 |
// Evaluate variable variable as in Less_Tree_Variable. |
| 181 |
$name = (new Less_Tree_Variable($name, $this->index + 1, $this->currentFileInfo)) |
| 182 |
->compile($env) |
| 183 |
->value; |
| 184 |
} |
| 185 |
|
| 186 |
$args = [ |
| 187 |
'var', |
| 188 |
[ |
| 189 |
new Less_Tree_Keyword("--{$name}"), |
| 190 |
$compiled, |
| 191 |
], |
| 192 |
$this->index, |
| 193 |
]; |
| 194 |
|
| 195 |
// No need to call `compile()` on the new call node (replacing the variable node), |
| 196 |
// as it's not a built-in Less function, `Less_Tree_Keyword::compile()` is a no-op, |
| 197 |
// and it wraps the already compiled variable node. |
| 198 |
return new Less_Tree_Call(...$args); |
| 199 |
} |
| 200 |
}; |
| 201 |
$variable->replaceCssVars = $this->replaceCssVars; |
| 202 |
|
| 203 |
return $variable; |
| 204 |
} |
| 205 |
|
| 206 |
/** |
| 207 |
* Handle a {@see Less_Tree_Mixin_Definition} node during AST traversal |
| 208 |
* |
| 209 |
* Less.php does not visit default parameter values, which would leave |
| 210 |
* `.mixin(@color: @icinga-red)` producing `var(--color, …)` instead of `var(--icinga-red, …)`. |
| 211 |
* |
| 212 |
* This method works around the traversal gap by pushing the mixin's parameter names onto a stack and |
| 213 |
* manually visiting each parameter value. For all frames in the stack, {@see visitVariable()} |
| 214 |
* returns parameter names unchanged and only rewrites parameter values. |
| 215 |
* |
| 216 |
* Simplified AST traversal context: |
| 217 |
* ``` |
| 218 |
* MixinDefinition(.mixin) ← visitMixinDefinition() |
| 219 |
* └─ Parameters |
| 220 |
* ├─ Variable (name: color) ← instrument visitVariable() call to ignore this variable |
| 221 |
* └─ Variable (value: icinga-red) ← force visitVariable() call |
| 222 |
* visitMixinDefinitionOut() revert instrumentation |
| 223 |
* ``` |
| 224 |
* |
| 225 |
* @param Less_Tree_Mixin_Definition $d The mixin definition node being visited |
| 226 |
* |
| 227 |
* @return Less_Tree_Mixin_Definition The original mixin definition node (modified in-place) |
| 228 |
* |
| 229 |
* @see visitMixinDefinitionOut() For cleanup after traversal |
| 230 |
* @see visitVariable() For replacement logic that checks exclusion stack |
| 231 |
*/ |
| 232 |
public function visitMixinDefinition(Less_Tree_Mixin_Definition $d): Less_Tree_Mixin_Definition |
| 233 |
{ |
| 234 |
// Less_Tree_Mixin_Definition::accept() does not visit parameters, but we have to replace them if necessary. |
| 235 |
foreach ($d->params as &$p) { |
| 236 |
if (isset($p['value'])) { |
| 237 |
$p['value'] = $this->visitObj($p['value']); |
| 238 |
} |
| 239 |
} |
| 240 |
unset($p); |
| 241 |
|
| 242 |
array_unshift($this->mixinParams, array_column($d->params, 'name')); |
| 243 |
|
| 244 |
return $d; |
| 245 |
} |
| 246 |
|
| 247 |
/** |
| 248 |
* Leave a {@see Less_Tree_Mixin_Definition} node |
| 249 |
* |
| 250 |
* Removes the current mixin's parameter names from {@see $mixinParams}, |
| 251 |
* restoring the parent scope. |
| 252 |
* |
| 253 |
* @return void |
| 254 |
*/ |
| 255 |
public function visitMixinDefinitionOut(): void |
| 256 |
{ |
| 257 |
array_shift($this->mixinParams); |
| 258 |
} |
| 259 |
|
| 260 |
/** |
| 261 |
* Handle a {@see Less_Tree_Mixin_Call} node during AST traversal |
| 262 |
* |
| 263 |
* Since Less.php does not visit arguments of mixin calls, this visitor forces each argument to be visited |
| 264 |
* to trigger our {@see visitVariable()} so that arguments are replaced by CSS `var()` calls if applicable, |
| 265 |
* e.g., `.mixin(icinga-red)` → `.mixin(var(--icinga-red, ...))`. |
| 266 |
* |
| 267 |
* Simplified AST traversal context: |
| 268 |
* ``` |
| 269 |
* MixinCall (.mixin) ← visitMixinCall() |
| 270 |
* └─ Arguments |
| 271 |
* └─ Variable (icinga-red) ← force visitVariable() call |
| 272 |
* ``` |
| 273 |
* |
| 274 |
* @param Less_Tree_Mixin_Call $c The mixin call node being visited |
| 275 |
* |
| 276 |
* @return Less_Tree_Mixin_Call The original mixin call node (modified in-place) |
| 277 |
*/ |
| 278 |
public function visitMixinCall(Less_Tree_Mixin_Call $c): Less_Tree_Mixin_Call |
| 279 |
{ |
| 280 |
// Less_Tree_Mixin_Call::accept() does not visit arguments, but we have to replace them if necessary. |
| 281 |
foreach ($c->arguments as &$a) { |
| 282 |
$a['value'] = $this->visitObj($a['value']); |
| 283 |
} |
| 284 |
unset($a); |
| 285 |
|
| 286 |
return $c; |
| 287 |
} |
| 288 |
|
| 289 |
/** |
| 290 |
* Set up the CSS `var()` replacement state stack |
| 291 |
* |
| 292 |
* Creates {@see $replaceCssVars} with an initial `true` frame so that replacement |
| 293 |
* is enabled at the start of each traversal. |
| 294 |
* |
| 295 |
* @return void |
| 296 |
* |
| 297 |
* @see visitCall() Which pushes/pops frames to disable replacement inside built-in Less functions |
| 298 |
*/ |
| 299 |
protected function init(): void |
| 300 |
{ |
| 301 |
$this->replaceCssVars = new SplDoublyLinkedList(); |
| 302 |
// Enable CSS `var()` replacement. |
| 303 |
$this->replaceCssVars->push(true); |
| 304 |
} |
| 305 |
|
| 306 |
/** |
| 307 |
* Deep-copy object-type state when this visitor is cloned by {@see PreEvalVisitor::run()} |
| 308 |
* |
| 309 |
* {@see $replaceCssVars} is a {@see SplDoublyLinkedList} and would otherwise be shared |
| 310 |
* between the prototype and the clone. Cloning it ensures each traversal starts with |
| 311 |
* its own independent stack. |
| 312 |
* |
| 313 |
* @return void |
| 314 |
*/ |
| 315 |
public function __clone(): void |
| 316 |
{ |
| 317 |
$this->replaceCssVars = clone $this->replaceCssVars; |
| 318 |
} |
| 319 |
} |