Debian Codegraph @

vendor/sabberworm/php-css-parser/src/RuleSet/DeclarationBlock.php

raw
1 <?php
2
3 declare(strict_types=1);
4
5 namespace Sabberworm\CSS\RuleSet;
6
7 use Sabberworm\CSS\Comment\Comment;
8 use Sabberworm\CSS\Comment\CommentContainer;
9 use Sabberworm\CSS\CSSElement;
10 use Sabberworm\CSS\CSSList\CSSList;
11 use Sabberworm\CSS\CSSList\CSSListItem;
12 use Sabberworm\CSS\CSSList\KeyFrame;
13 use Sabberworm\CSS\OutputFormat;
14 use Sabberworm\CSS\Parsing\OutputException;
15 use Sabberworm\CSS\Parsing\ParserState;
16 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
17 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
18 use Sabberworm\CSS\Position\Position;
19 use Sabberworm\CSS\Position\Positionable;
20 use Sabberworm\CSS\Property\Declaration;
21 use Sabberworm\CSS\Property\KeyframeSelector;
22 use Sabberworm\CSS\Property\Selector;
23 use Sabberworm\CSS\Settings;
24
25 /**
26 * This class represents a `RuleSet` constrained by a `Selector`.
27 *
28 * It contains an array of selector objects (comma-separated in the CSS) as well as the rules to be applied to the
29 * matching elements.
30 *
31 * Declaration blocks usually appear directly inside a `Document` or another `CSSList` (mostly a `MediaQuery`).
32 *
33 * Note that `CSSListItem` extends both `Commentable` and `Renderable`, so those interfaces must also be implemented.
34 */
35 class DeclarationBlock implements CSSElement, CSSListItem, Positionable, DeclarationList
36 {
37 use CommentContainer;
38 use LegacyDeclarationListMethods;
39 use Position;
40
41 /**
42 * @var list<Selector>
43 */
44 private $selectors = [];
45
46 /**
47 * @var RuleSet
48 */
49 private $ruleSet;
50
51 /**
52 * @param int<1, max>|null $lineNumber
53 */
54 public function __construct(?int $lineNumber = null)
55 {
56 $this->ruleSet = new RuleSet($lineNumber);
57 $this->setPosition($lineNumber);
58 }
59
60 /**
61 * @throws UnexpectedTokenException
62 * @throws UnexpectedEOFException
63 *
64 * @internal since V8.8.0
65 */
66 public static function parse(ParserState $parserState, ?CSSList $list = null): ?DeclarationBlock
67 {
68 $comments = [];
69 $result = new DeclarationBlock($parserState->currentLine());
70 try {
71 $selectors = self::parseSelectors($parserState, $list, $comments);
72 $result->setSelectors($selectors, $list);
73 if ($parserState->comes('{')) {
74 $parserState->consume(1);
75 }
76 } catch (UnexpectedTokenException $e) {
77 if ($parserState->getSettings()->usesLenientParsing()) {
78 if (!$parserState->consumeIfComes('}')) {
79 $parserState->consumeUntil(['}', ParserState::EOF], false, true);
80 }
81 return null;
82 } else {
83 throw $e;
84 }
85 }
86 $result->setComments($comments);
87
88 RuleSet::parseRuleSet($parserState, $result->getRuleSet());
89
90 return $result;
91 }
92
93 /**
94 * @param array<Selector|string>|string $selectors
95 *
96 * @throws UnexpectedTokenException
97 */
98 public function setSelectors($selectors, ?CSSList $list = null): void
99 {
100 if (\is_array($selectors)) {
101 $selectorsToSet = $selectors;
102 } else {
103 // A string of comma-separated selectors requires parsing.
104 try {
105 $parserState = new ParserState($selectors, Settings::create());
106 $selectorsToSet = self::parseSelectors($parserState, $list);
107 if (!$parserState->isEnd()) {
108 throw new UnexpectedTokenException('EOF', 'more');
109 }
110 } catch (UnexpectedTokenException $exception) {
111 // The exception message from parsing may refer to the faux `{` block start token,
112 // which would be confusing.
113 // Rethrow with a more useful message, that also includes the selector(s) string that was passed.
114 throw new UnexpectedTokenException(
115 'Selector(s) string is not valid.',
116 $selectors,
117 'custom'
118 );
119 }
120 }
121
122 // Convert all items to a `Selector` if not already
123 foreach ($selectorsToSet as $key => $selector) {
124 if (!($selector instanceof Selector)) {
125 if ($list === null || !($list instanceof KeyFrame)) {
126 if (!Selector::isValid($selector)) {
127 throw new UnexpectedTokenException(
128 "Selector did not match '" . Selector::SELECTOR_VALIDATION_RX . "'.",
129 $selector,
130 'custom'
131 );
132 }
133 $selectorsToSet[$key] = new Selector($selector);
134 } else {
135 if (!KeyframeSelector::isValid($selector)) {
136 throw new UnexpectedTokenException(
137 "Selector did not match '" . KeyframeSelector::SELECTOR_VALIDATION_RX . "'.",
138 $selector,
139 'custom'
140 );
141 }
142 $selectorsToSet[$key] = new KeyframeSelector($selector);
143 }
144 }
145 }
146
147 // Discard the keys and reindex the array
148 $this->selectors = \array_values($selectorsToSet);
149 }
150
151 /**
152 * Remove one of the selectors of the block.
153 *
154 * @param Selector|string $selectorToRemove
155 */
156 public function removeSelector($selectorToRemove): bool
157 {
158 if ($selectorToRemove instanceof Selector) {
159 $selectorToRemove = $selectorToRemove->getSelector();
160 }
161 foreach ($this->selectors as $key => $selector) {
162 if ($selector->getSelector() === $selectorToRemove) {
163 unset($this->selectors[$key]);
164 return true;
165 }
166 }
167 return false;
168 }
169
170 /**
171 * @return list<Selector>
172 */
173 public function getSelectors(): array
174 {
175 return $this->selectors;
176 }
177
178 public function getRuleSet(): RuleSet
179 {
180 return $this->ruleSet;
181 }
182
183 /**
184 * @see RuleSet::addDeclaration()
185 */
186 public function addDeclaration(Declaration $declarationToAdd, ?Declaration $sibling = null): void
187 {
188 $this->ruleSet->addDeclaration($declarationToAdd, $sibling);
189 }
190
191 /**
192 * @return array<int<0, max>, Declaration>
193 *
194 * @see RuleSet::getDeclarations()
195 */
196 public function getDeclarations(?string $searchPattern = null): array
197 {
198 return $this->ruleSet->getDeclarations($searchPattern);
199 }
200
201 /**
202 * @param array<Declaration> $declarations
203 *
204 * @see RuleSet::setDeclarations()
205 */
206 public function setDeclarations(array $declarations): void
207 {
208 $this->ruleSet->setDeclarations($declarations);
209 }
210
211 /**
212 * @return array<string, Declaration>
213 *
214 * @see RuleSet::getDeclarationsAssociative()
215 */
216 public function getDeclarationsAssociative(?string $searchPattern = null): array
217 {
218 return $this->ruleSet->getDeclarationsAssociative($searchPattern);
219 }
220
221 /**
222 * @see RuleSet::removeDeclaration()
223 */
224 public function removeDeclaration(Declaration $declarationToRemove): void
225 {
226 $this->ruleSet->removeDeclaration($declarationToRemove);
227 }
228
229 /**
230 * @see RuleSet::removeMatchingDeclarations()
231 */
232 public function removeMatchingDeclarations(string $searchPattern): void
233 {
234 $this->ruleSet->removeMatchingDeclarations($searchPattern);
235 }
236
237 /**
238 * @see RuleSet::removeAllDeclarations()
239 */
240 public function removeAllDeclarations(): void
241 {
242 $this->ruleSet->removeAllDeclarations();
243 }
244
245 /**
246 * @return non-empty-string
247 *
248 * @throws OutputException
249 */
250 public function render(OutputFormat $outputFormat): string
251 {
252 $formatter = $outputFormat->getFormatter();
253 $result = $formatter->comments($this);
254 if (\count($this->selectors) === 0) {
255 // If all the selectors have been removed, this declaration block becomes invalid
256 throw new OutputException(
257 'Attempt to print declaration block with missing selector',
258 $this->getLineNumber()
259 );
260 }
261 $result .= $outputFormat->getContentBeforeDeclarationBlock();
262 $result .= $formatter->implode(
263 $formatter->spaceBeforeSelectorSeparator() . ',' . $formatter->spaceAfterSelectorSeparator(),
264 $this->selectors
265 );
266 $result .= $outputFormat->getContentAfterDeclarationBlockSelectors();
267 $result .= $formatter->spaceBeforeOpeningBrace() . '{';
268 $result .= $this->ruleSet->render($outputFormat);
269 $result .= '}';
270 $result .= $outputFormat->getContentAfterDeclarationBlock();
271
272 return $result;
273 }
274
275 /**
276 * @return array<string, bool|int|float|string|array<mixed>|null>
277 *
278 * @internal
279 */
280 public function getArrayRepresentation(): array
281 {
282 throw new \BadMethodCallException('`getArrayRepresentation` is not yet implemented for `' . self::class . '`');
283 }
284
285 /**
286 * @param list<Comment> $comments
287 *
288 * @return list<Selector>
289 *
290 * @throws UnexpectedTokenException
291 */
292 private static function parseSelectors(ParserState $parserState, ?CSSList $list, array &$comments = []): array
293 {
294 $selectorClass = $list instanceof KeyFrame ? KeyFrameSelector::class : Selector::class;
295 $selectors = [];
296
297 while (true) {
298 $selectors[] = $selectorClass::parse($parserState, $comments);
299 if (!$parserState->consumeIfComes(',')) {
300 break;
301 }
302 }
303
304 return $selectors;
305 }
306 }