• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

dragomano / scss-php / 23594295754

26 Mar 2026 12:19PM UTC coverage: 84.536%. First build
23594295754

push

github

web-flow
Merge pull request #51 from dragomano/refactor

Rewrite compiler

10140 of 12016 new or added lines in 162 files covered. (84.39%)

10272 of 12151 relevant lines covered (84.54%)

83.37 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

81.54
/src/Builtins/SassStringModule.php
1
<?php
2

3
declare(strict_types=1);
4

5
namespace Bugo\SCSS\Builtins;
6

7
use Bugo\SCSS\Exceptions\BuiltinArgumentException;
8
use Bugo\SCSS\Exceptions\MissingFunctionArgumentsException;
9
use Bugo\SCSS\Exceptions\UnknownSassFunctionException;
10
use Bugo\SCSS\Nodes\AstNode;
11
use Bugo\SCSS\Nodes\ColorNode;
12
use Bugo\SCSS\Nodes\ListNode;
13
use Bugo\SCSS\Nodes\NamedArgumentNode;
14
use Bugo\SCSS\Nodes\NumberNode;
15
use Bugo\SCSS\Nodes\StringNode;
16
use Bugo\SCSS\Runtime\BuiltinCallContext;
17
use Bugo\SCSS\Utils\StringHelper;
18

19
use function array_map;
20
use function implode;
21
use function is_int;
22
use function strlen;
23
use function strpos;
24
use function strtolower;
25
use function strtoupper;
26
use function substr;
27

28
final class SassStringModule extends AbstractModule
29
{
30
    private const FUNCTIONS = [
31
        'index',
32
        'insert',
33
        'length',
34
        'quote',
35
        'slice',
36
        'split',
37
        'to-lower-case',
38
        'to-upper-case',
39
        'unique-id',
40
        'unquote',
41
    ];
42

43
    private const GLOBAL_FUNCTIONS = [
44
        'quote',
45
        'to-lower-case',
46
        'to-upper-case',
47
        'unique-id',
48
        'unquote',
49
    ];
50

51
    private const GLOBAL_ALIASES = [
52
        'str-index'  => 'index',
53
        'str-insert' => 'insert',
54
        'str-length' => 'length',
55
        'str-slice'  => 'slice',
56
    ];
57

58
    private int $uniqueId = 0;
59

60
    public function getName(): string
61
    {
62
        return 'string';
89 ✔
63
    }
64

65
    public function getFunctions(): array
66
    {
67
        return self::FUNCTIONS;
31 ✔
68
    }
69

70
    public function getGlobalAliases(): array
71
    {
72
        return $this->globalAliases(self::GLOBAL_FUNCTIONS, self::GLOBAL_ALIASES);
89 ✔
73
    }
74

75
    /**
76
     * @param array<int, AstNode> $positional
77
     * @param array<string, AstNode> $named
78
     */
79
    public function call(string $name, array $positional, array $named, ?BuiltinCallContext $context = null): AstNode
80
    {
81
        $previousDisplayName = $this->beginBuiltinCall($name, $context);
55 ✔
82

83
        try {
84
            return match ($name) {
55 ✔
85
                'index'         => $this->index($positional, $context),
7 ✔
86
                'insert'        => $this->insert($positional, $context),
8 ✔
87
                'length'        => $this->length($positional, $context),
9 ✔
88
                'quote'         => $this->quote($positional, $context),
5 ✔
89
                'slice'         => $this->slice($positional, $context),
9 ✔
90
                'split'         => $this->split($positional, $named, $context),
4 ✔
91
                'to-lower-case' => $this->toLowerCase($positional, $context),
7 ✔
92
                'to-upper-case' => $this->toUpperCase($positional, $context),
8 ✔
93
                'unique-id'     => $this->uniqueId($context),
5 ✔
94
                'unquote'       => $this->unquote($positional, $context),
7 ✔
95
                default         => throw new UnknownSassFunctionException('string', $name),
53 ✔
96
            };
55 ✔
97
        } finally {
98
            $this->endBuiltinCall($previousDisplayName);
55 ✔
99
        }
100
    }
101

102
    /**
103
     * @param array<int, AstNode> $positional
104
     */
105
    private function insert(array $positional, ?BuiltinCallContext $context): AstNode
106
    {
107
        $this->warnAboutDeprecatedStringFunction($context, 'insert', $positional);
8 ✔
108

109
        $string = $this->requireStringArg($positional, 0, 'string.insert');
8 ✔
110
        $insert = $this->requireStringArg($positional, 1, 'string.insert');
8 ✔
111
        $index  = $this->requireIntegerArg($positional, 2, 'string.insert');
7 ✔
112
        $length = strlen($string);
7 ✔
113

114
        $firstString  = $positional[0] ?? null;
7 ✔
115
        $secondString = $positional[1] ?? null;
7 ✔
116
        $quoted       = ($firstString instanceof StringNode && $firstString->quoted)
7 ✔
117
            || ($secondString instanceof StringNode && $secondString->quoted);
7 ✔
118

119
        if ($index === 0) {
7 ✔
120
            throw BuiltinArgumentException::mustNotBeZero(
1 ✔
121
                $this->builtinCallReference('string.insert'),
1 ✔
122
                'index'
1 ✔
123
            );
1 ✔
124
        }
125

126
        $offset = $index > 0 ? $index - 1 : $length + $index + 1;
6 ✔
127
        if ($offset < 0) {
6 ✔
NEW
128
            $offset = 0;
×
129
        }
130

131
        if ($offset > $length) {
6 ✔
NEW
132
            $offset = $length;
×
133
        }
134

135
        return new StringNode(
6 ✔
136
            substr($string, 0, $offset) . $insert . substr($string, $offset),
6 ✔
137
            $quoted
6 ✔
138
        );
6 ✔
139
    }
140

141
    /**
142
     * @param array<int, AstNode> $positional
143
     */
144
    private function index(array $positional, ?BuiltinCallContext $context): AstNode
145
    {
146
        $this->warnAboutDeprecatedStringFunction($context, 'index', $positional);
7 ✔
147

148
        $string    = $this->requireStringArg($positional, 0, 'string.index');
7 ✔
149
        $substring = $this->requireStringArg($positional, 1, 'string.index');
7 ✔
150

151
        $pos = strpos($string, $substring);
7 ✔
152

153
        if ($pos === false) {
7 ✔
154
            return $this->nullNode();
2 ✔
155
        }
156

157
        return new NumberNode($pos + 1);
7 ✔
158
    }
159

160
    /**
161
     * @param array<int, AstNode> $positional
162
     */
163
    private function length(array $positional, ?BuiltinCallContext $context): AstNode
164
    {
165
        $this->warnAboutDeprecatedStringFunction($context, 'length', $positional);
9 ✔
166

167
        $value = $this->requireStringArg($positional, 0, 'string.length');
9 ✔
168

169
        return new NumberNode(strlen($value));
9 ✔
170
    }
171

172
    /**
173
     * @param array<int, AstNode> $positional
174
     */
175
    private function quote(array $positional, ?BuiltinCallContext $context): AstNode
176
    {
177
        $this->warnAboutDeprecatedStringFunction($context, 'quote', $positional);
5 ✔
178

179
        return new StringNode(
5 ✔
180
            $this->stripQuotes($this->requireStringArg($positional, 0, 'string.quote')),
5 ✔
181
            true
5 ✔
182
        );
5 ✔
183
    }
184

185
    /**
186
     * @param array<int, AstNode> $positional
187
     */
188
    private function slice(array $positional, ?BuiltinCallContext $context): AstNode
189
    {
190
        $this->warnAboutDeprecatedStringFunction($context, 'slice', $positional);
9 ✔
191

192
        $string = $this->requireStringArg($positional, 0, 'string.slice');
9 ✔
193
        $start  = $this->requireIntegerArg($positional, 1, 'string.slice');
9 ✔
194
        $end    = isset($positional[2]) ? $this->requireIntegerArg($positional, 2, 'string.slice') : -1;
9 ✔
195
        $length = strlen($string);
9 ✔
196

197
        $firstString = $positional[0] ?? null;
9 ✔
198
        $quoted      = $firstString instanceof StringNode && $firstString->quoted;
9 ✔
199
        $startOffset = $start > 0 ? $start - 1 : ($start === 0 ? 0 : $length + $start);
9 ✔
200

201
        if ($startOffset < 0) {
9 ✔
NEW
202
            $startOffset = 0;
×
203
        }
204

205
        $endOffset = $end > 0 ? $end : $length + $end + 1;
9 ✔
206

207
        if ($endOffset < 0) {
9 ✔
NEW
208
            $endOffset = 0;
×
209
        }
210

211
        if ($endOffset < $startOffset) {
9 ✔
NEW
212
            return new StringNode('', $quoted);
×
213
        }
214

215
        return new StringNode(substr($string, $startOffset, $endOffset - $startOffset), $quoted);
9 ✔
216
    }
217

218
    /**
219
     * @param array<int, AstNode> $positional
220
     * @param array<string, AstNode> $named
221
     */
222
    private function split(array $positional, array $named, ?BuiltinCallContext $context): AstNode
223
    {
224
        $this->warnAboutDeprecatedStringFunction($context, 'split', $positional);
4 ✔
225

226
        $inputNode = $positional[0] ?? null;
4 ✔
227
        $quoted    = $inputNode instanceof StringNode && $inputNode->quoted;
4 ✔
228
        $string    = $this->requireStringArg($positional, 0, 'string.split');
4 ✔
229
        $separator = $this->requireStringArg($positional, 1, 'string.split');
4 ✔
230
        $limitNode = $named['limit'] ?? ($positional[2] ?? null);
4 ✔
231

232
        if ($limitNode !== null && (! ($limitNode instanceof NumberNode) || ! is_int($limitNode->value))) {
4 ✔
NEW
233
            throw new MissingFunctionArgumentsException(
×
NEW
234
                $this->builtinErrorContext('string.split'),
×
NEW
235
                'an integer argument'
×
NEW
236
            );
×
237
        }
238

239
        $limit = $limitNode instanceof NumberNode ? $limitNode->value : null;
4 ✔
240

241
        if ($limit !== null && $limit < 1) {
4 ✔
NEW
242
            throw BuiltinArgumentException::mustBePositiveInteger(
×
NEW
243
                $this->builtinCallReference('string.split'),
×
NEW
244
                'limit'
×
NEW
245
            );
×
246
        }
247

248
        if ($string === '') {
4 ✔
NEW
249
            return new ListNode([new StringNode('', $quoted)], 'comma', true);
×
250
        }
251

252
        $remaining = $string;
4 ✔
253

254
        $parts = [];
4 ✔
255
        $limit ??= strlen($string);
4 ✔
256
        $splits = 0;
4 ✔
257

258
        while ($splits <= $limit && strlen($remaining) > 0) {
4 ✔
259
            if ($splits === $limit) {
4 ✔
260
                $parts[] = $remaining;
1 ✔
261

262
                break;
1 ✔
263
            }
264

265
            if ($separator === '') {
4 ✔
266
                $parts[]   = substr($remaining, 0, 1);
1 ✔
267
                $remaining = substr($remaining, 1);
1 ✔
268

269
                $splits++;
1 ✔
270

271
                continue;
1 ✔
272
            }
273

274
            $index = strpos($remaining, $separator);
3 ✔
275

276
            if ($index === false) {
3 ✔
277
                $parts[] = $remaining;
2 ✔
278

279
                break;
2 ✔
280
            }
281

282
            $parts[]   = substr($remaining, 0, $index);
3 ✔
283
            $remaining = substr($remaining, $index + strlen($separator));
3 ✔
284

285
            $splits++;
3 ✔
286
        }
287

288
        return new ListNode(
4 ✔
289
            array_map(fn(string $part): AstNode => new StringNode($part, $quoted), $parts),
4 ✔
290
            'comma',
4 ✔
291
            true
4 ✔
292
        );
4 ✔
293
    }
294

295
    /**
296
     * @param array<int, AstNode> $positional
297
     */
298
    private function toLowerCase(array $positional, ?BuiltinCallContext $context): AstNode
299
    {
300
        $this->warnAboutDeprecatedStringFunction($context, 'to-lower-case', $positional);
7 ✔
301

302
        $inputNode = $positional[0] ?? null;
7 ✔
303
        $quoted    = $inputNode instanceof StringNode && $inputNode->quoted;
7 ✔
304

305
        return new StringNode(
7 ✔
306
            strtolower($this->requireStringArg($positional, 0, 'string.to-lower-case')),
7 ✔
307
            $quoted
7 ✔
308
        );
7 ✔
309
    }
310

311
    /**
312
     * @param array<int, AstNode> $positional
313
     */
314
    private function toUpperCase(array $positional, ?BuiltinCallContext $context): AstNode
315
    {
316
        $this->warnAboutDeprecatedStringFunction($context, 'to-upper-case', $positional);
8 ✔
317

318
        $inputNode = $positional[0] ?? null;
8 ✔
319
        $quoted    = $inputNode instanceof StringNode && $inputNode->quoted;
8 ✔
320

321
        return new StringNode(
8 ✔
322
            strtoupper($this->requireStringArg($positional, 0, 'string.to-upper-case')),
8 ✔
323
            $quoted
8 ✔
324
        );
8 ✔
325
    }
326

327
    private function uniqueId(?BuiltinCallContext $context): AstNode
328
    {
329
        $this->warnAboutDeprecatedStringFunction($context, 'unique-id');
5 ✔
330

331
        $this->uniqueId++;
5 ✔
332

333
        return new StringNode('u' . $this->uniqueId);
5 ✔
334
    }
335

336
    /**
337
     * @param array<int, AstNode> $positional
338
     */
339
    private function unquote(array $positional, ?BuiltinCallContext $context): AstNode
340
    {
341
        $this->warnAboutDeprecatedStringFunction($context, 'unquote', $positional);
7 ✔
342

343
        return new StringNode(
7 ✔
344
            StringHelper::unescapeQuotedContent(
7 ✔
345
                $this->stripQuotes($this->requireStringArg($positional, 0, 'string.unquote'))
7 ✔
346
            )
7 ✔
347
        );
7 ✔
348
    }
349

350
    /**
351
     * @param array<int, AstNode> $positional
352
     */
353
    private function warnAboutDeprecatedStringFunction(
354
        ?BuiltinCallContext $context,
355
        string $name,
356
        array $positional = []
357
    ): void {
358
        if (! $this->isGlobalBuiltinCall()) {
55 ✔
359
            return;
30 ✔
360
        }
361

362
        $this->warnAboutDeprecatedBuiltinFunctionWithSingleSuggestion(
26 ✔
363
            $context,
26 ✔
364
            $this->deprecatedStringSuggestion($name, $positional),
26 ✔
365
            'string.' . $name
26 ✔
366
        );
26 ✔
367
    }
368

369
    /**
370
     * @param array<int, AstNode> $positional
371
     */
372
    private function deprecatedStringSuggestion(string $name, array $positional): string
373
    {
374
        $arguments = $this->rawArgumentsAvailable() ? $this->rawPositionalArguments() : $positional;
26 ✔
375

376
        return 'string.' . $name . '(' . implode(', ', $this->describeArguments($arguments)) . ')';
26 ✔
377
    }
378

379
    /**
380
     * @param array<int, AstNode> $arguments
381
     * @return array<int, string>
382
     */
383
    private function describeArguments(array $arguments): array
384
    {
385
        return array_map($this->describeValue(...), $arguments);
26 ✔
386
    }
387

388
    private function describeValue(AstNode $value): string
389
    {
390
        if ($value instanceof StringNode) {
23 ✔
391
            return $value->quoted ? '"' . $value->value . '"' : $value->value;
23 ✔
392
        }
393

394
        if ($value instanceof NumberNode) {
5 ✔
395
            return "$value->value" . ($value->unit ?? '');
5 ✔
396
        }
397

NEW
398
        if ($value instanceof ListNode) {
×
NEW
399
            $items = $this->describeArguments($value->items);
×
NEW
400
            $glue  = $value->separator === 'comma' ? ', ' : ' ';
×
NEW
401
            $text  = implode($glue, $items);
×
402

NEW
403
            if ($value->bracketed) {
×
NEW
404
                return '[' . $text . ']';
×
405
            }
406

NEW
407
            return $text;
×
408
        }
409

NEW
410
        if ($value instanceof ColorNode) {
×
NEW
411
            return $value->value;
×
412
        }
413

NEW
414
        return '';
×
415
    }
416

417
    /**
418
     * @return array<int, AstNode>
419
     */
420
    private function rawPositionalArguments(): array
421
    {
422
        if ($this->activeBuiltinContext === null || $this->activeBuiltinContext->rawArguments === null) {
14 ✔
NEW
423
            return [];
×
424
        }
425

426
        $positional = [];
14 ✔
427

428
        foreach ($this->activeBuiltinContext->rawArguments as $argument) {
14 ✔
429
            if ($argument instanceof NamedArgumentNode) {
12 ✔
NEW
430
                continue;
×
431
            }
432

433
            $positional[] = $argument;
12 ✔
434
        }
435

436
        return $positional;
14 ✔
437
    }
438

439
    private function rawArgumentsAvailable(): bool
440
    {
441
        return $this->activeBuiltinContext !== null && $this->activeBuiltinContext->rawArguments !== null;
26 ✔
442
    }
443

444
    /**
445
     * @param array<int, AstNode> $positional
446
     */
447
    private function requireStringArg(array $positional, int $index, string $context): string
448
    {
449
        if (! isset($positional[$index])) {
51 ✔
450
            throw new MissingFunctionArgumentsException(
1 ✔
451
                $this->builtinErrorContext($context),
1 ✔
452
                'required argument'
1 ✔
453
            );
1 ✔
454
        }
455

456
        $value = $positional[$index];
51 ✔
457

458
        if ($value instanceof StringNode) {
51 ✔
459
            return $value->value;
51 ✔
460
        }
461

NEW
462
        if ($value instanceof NumberNode) {
×
NEW
463
            return "$value->value" . ($value->unit ?? '');
×
464
        }
465

NEW
466
        throw new MissingFunctionArgumentsException(
×
NEW
467
            $this->builtinErrorContext($context),
×
NEW
468
            'a string argument'
×
NEW
469
        );
×
470
    }
471

472
    /**
473
     * @param array<int, AstNode> $positional
474
     */
475
    private function requireIntegerArg(array $positional, int $index, string $context): int
476
    {
477
        if (
478
            ! isset($positional[$index])
14 ✔
479
            || ! ($positional[$index] instanceof NumberNode)
14 ✔
480
            || ! is_int($positional[$index]->value)
14 ✔
481
        ) {
NEW
482
            throw new MissingFunctionArgumentsException(
×
NEW
483
                $this->builtinErrorContext($context),
×
NEW
484
                'an integer argument'
×
NEW
485
            );
×
486
        }
487

488
        return $positional[$index]->value;
14 ✔
489
    }
490

491
    private function stripQuotes(string $value): string
492
    {
493
        return StringHelper::unquote($value);
11 ✔
494
    }
495
}
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE TRIAL · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2026 Coveralls, Inc