diff --git a/CHANGELOG.md b/CHANGELOG.md index 72ad1588..14e3ecb8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ Please also have a look at our ### Changed +- Methods like `setRule()` in `RuleSet` and `DeclarationBlock` have been renamed + to `setDeclaration()`, etc. (#1521) - `Rule\Rule` class is renamed to `Property\Declaration` (#1508, #1512, #1513, #1522) - `Rule::setRule()` and `getRule()` are replaced with `setPropertyName()` and @@ -33,6 +35,8 @@ Please also have a look at our ### Deprecated +- Methods like `setRule()` in `RuleSet` and `DeclarationBlock` are deprecated; + there are direct replacements such as `setDeclaration()` (#1521) - `Rule\Rule` class is deprecated; `Property\Declaration` is a direct replacement (#1508) - `Rule::setRule()` and `getRule()` are deprecated and replaced with diff --git a/src/RuleSet/AtRuleSet.php b/src/RuleSet/AtRuleSet.php index 4cd5acc2..7307193d 100644 --- a/src/RuleSet/AtRuleSet.php +++ b/src/RuleSet/AtRuleSet.php @@ -61,7 +61,7 @@ public function render(OutputFormat $outputFormat): string $arguments = ' ' . $arguments; } $result .= "@{$this->type}$arguments{$formatter->spaceBeforeOpeningBrace()}{"; - $result .= $this->renderRules($outputFormat); + $result .= $this->renderDeclarations($outputFormat); $result .= '}'; return $result; } diff --git a/src/RuleSet/DeclarationBlock.php b/src/RuleSet/DeclarationBlock.php index 8ded5558..29265ca6 100644 --- a/src/RuleSet/DeclarationBlock.php +++ b/src/RuleSet/DeclarationBlock.php @@ -35,6 +35,7 @@ class DeclarationBlock implements CSSElement, CSSListItem, Positionable, RuleContainer { use CommentContainer; + use LegacyRuleContainerMethods; use Position; /** @@ -180,65 +181,65 @@ public function getRuleSet(): RuleSet } /** - * @see RuleSet::addRule() + * @see RuleSet::addDeclaration() */ - public function addRule(Declaration $declarationToAdd, ?Declaration $sibling = null): void + public function addDeclaration(Declaration $declarationToAdd, ?Declaration $sibling = null): void { - $this->ruleSet->addRule($declarationToAdd, $sibling); + $this->ruleSet->addDeclaration($declarationToAdd, $sibling); } /** * @return array, Declaration> * - * @see RuleSet::getRules() + * @see RuleSet::getDeclarations() */ - public function getRules(?string $searchPattern = null): array + public function getDeclarations(?string $searchPattern = null): array { - return $this->ruleSet->getRules($searchPattern); + return $this->ruleSet->getDeclarations($searchPattern); } /** * @param array $declarations * - * @see RuleSet::setRules() + * @see RuleSet::setDeclarations() */ - public function setRules(array $declarations): void + public function setDeclarations(array $declarations): void { - $this->ruleSet->setRules($declarations); + $this->ruleSet->setDeclarations($declarations); } /** * @return array * - * @see RuleSet::getRulesAssoc() + * @see RuleSet::getDeclarationsAssociative() */ - public function getRulesAssoc(?string $searchPattern = null): array + public function getDeclarationsAssociative(?string $searchPattern = null): array { - return $this->ruleSet->getRulesAssoc($searchPattern); + return $this->ruleSet->getDeclarationsAssociative($searchPattern); } /** - * @see RuleSet::removeRule() + * @see RuleSet::removeDeclaration() */ - public function removeRule(Declaration $declarationToRemove): void + public function removeDeclaration(Declaration $declarationToRemove): void { - $this->ruleSet->removeRule($declarationToRemove); + $this->ruleSet->removeDeclaration($declarationToRemove); } /** - * @see RuleSet::removeMatchingRules() + * @see RuleSet::removeMatchingDeclarations() */ - public function removeMatchingRules(string $searchPattern): void + public function removeMatchingDeclarations(string $searchPattern): void { - $this->ruleSet->removeMatchingRules($searchPattern); + $this->ruleSet->removeMatchingDeclarations($searchPattern); } /** - * @see RuleSet::removeAllRules() + * @see RuleSet::removeAllDeclarations() */ - public function removeAllRules(): void + public function removeAllDeclarations(): void { - $this->ruleSet->removeAllRules(); + $this->ruleSet->removeAllDeclarations(); } /** diff --git a/src/RuleSet/LegacyRuleContainerMethods.php b/src/RuleSet/LegacyRuleContainerMethods.php new file mode 100644 index 00000000..5ed6f794 --- /dev/null +++ b/src/RuleSet/LegacyRuleContainerMethods.php @@ -0,0 +1,75 @@ +addDeclaration($declarationToAdd, $sibling); + } + + /** + * @deprecated in v9.2, will be removed in v10.0; use `removeDeclaration()` instead. + */ + public function removeRule(Declaration $declarationToRemove): void + { + $this->removeDeclaration($declarationToRemove); + } + + /** + * @deprecated in v9.2, will be removed in v10.0; use `removeMatchingDeclarations()` instead. + */ + public function removeMatchingRules(string $searchPattern): void + { + $this->removeMatchingDeclarations($searchPattern); + } + + /** + * @deprecated in v9.2, will be removed in v10.0; use `removeAllDeclarations()` instead. + */ + public function removeAllRules(): void + { + $this->removeAllDeclarations(); + } + + /** + * @param array $declarations + * + * @deprecated in v9.2, will be removed in v10.0; use `setDeclarations()` instead. + */ + public function setRules(array $declarations): void + { + $this->setDeclarations($declarations); + } + + /** + * @return array, Declaration> + * + * @deprecated in v9.2, will be removed in v10.0; use `getDeclarations()` instead. + */ + public function getRules(?string $searchPattern = null): array + { + return $this->getDeclarations($searchPattern); + } + + /** + * @return array + * + * @deprecated in v9.2, will be removed in v10.0; use `getDeclarationsAssociative()` instead. + */ + public function getRulesAssoc(?string $searchPattern = null): array + { + return $this->getDeclarationsAssociative($searchPattern); + } +} diff --git a/src/RuleSet/RuleContainer.php b/src/RuleSet/RuleContainer.php index fcd212bf..2767d505 100644 --- a/src/RuleSet/RuleContainer.php +++ b/src/RuleSet/RuleContainer.php @@ -11,26 +11,67 @@ */ interface RuleContainer { + public function addDeclaration(Declaration $declarationToAdd, ?Declaration $sibling = null): void; + + public function removeDeclaration(Declaration $declarationToRemove): void; + + public function removeMatchingDeclarations(string $searchPattern): void; + + public function removeAllDeclarations(): void; + + /** + * @param array $declarations + */ + public function setDeclarations(array $declarations): void; + + /** + * @return array, Declaration> + */ + public function getDeclarations(?string $searchPattern = null): array; + + /** + * @return array + */ + public function getDeclarationsAssociative(?string $searchPattern = null): array; + + /** + * @deprecated in v9.2, will be removed in v10.0; use `addDeclaration()` instead. + */ public function addRule(Declaration $declarationToAdd, ?Declaration $sibling = null): void; + /** + * @deprecated in v9.2, will be removed in v10.0; use `removeDeclaration()` instead. + */ public function removeRule(Declaration $declarationToRemove): void; + /** + * @deprecated in v9.2, will be removed in v10.0; use `removeMatchingDeclarations()` instead. + */ public function removeMatchingRules(string $searchPattern): void; + /** + * @deprecated in v9.2, will be removed in v10.0; use `removeAllDeclarations()` instead. + */ public function removeAllRules(): void; /** * @param array $declarations + * + * @deprecated in v9.2, will be removed in v10.0; use `setDeclarations()` instead. */ public function setRules(array $declarations): void; /** * @return array, Declaration> + * + * @deprecated in v9.2, will be removed in v10.0; use `getDeclarations()` instead. */ public function getRules(?string $searchPattern = null): array; /** * @return array + * + * @deprecated in v9.2, will be removed in v10.0; use `getDeclarationsAssociative()` instead. */ public function getRulesAssoc(?string $searchPattern = null): array; } diff --git a/src/RuleSet/RuleSet.php b/src/RuleSet/RuleSet.php index 087ab30f..f124a2b1 100644 --- a/src/RuleSet/RuleSet.php +++ b/src/RuleSet/RuleSet.php @@ -22,13 +22,14 @@ * However, unknown `AtRule`s (like `@font-face`) are rule sets as well. * * If you want to manipulate a `RuleSet`, - * use the methods `addRule()`, `getRules()`, `removeRule()`, `removeMatchingRules()`, etc. + * use the methods `addDeclaration()`, `getDeclarations()`, `removeDeclaration()`, `removeMatchingDeclarations()`, etc. * * Note that `CSSListItem` extends both `Commentable` and `Renderable`, so those interfaces must also be implemented. */ class RuleSet implements CSSElement, CSSListItem, Positionable, RuleContainer { use CommentContainer; + use LegacyRuleContainerMethods; use Position; /** @@ -88,7 +89,7 @@ public static function parseRuleSet(ParserState $parserState, RuleSet $ruleSet): $declaration = Declaration::parse($parserState, $commentsBeforeDeclaration); } if ($declaration instanceof Declaration) { - $ruleSet->addRule($declaration); + $ruleSet->addDeclaration($declaration); } } $parserState->consume('}'); @@ -99,7 +100,7 @@ public static function parseRuleSet(ParserState $parserState, RuleSet $ruleSet): * if the last `Declaration` is needed as a basis for setting position, but does not have a valid position, * which should never happen */ - public function addRule(Declaration $declarationToAdd, ?Declaration $sibling = null): void + public function addDeclaration(Declaration $declarationToAdd, ?Declaration $sibling = null): void { $propertyName = $declarationToAdd->getPropertyName(); if (!isset($this->declarations[$propertyName])) { @@ -148,14 +149,14 @@ public function addRule(Declaration $declarationToAdd, ?Declaration $sibling = n if ($declarationToAdd->getLineNumber() === null) { //this node is added manually, give it the next best line $columnNumber = $declarationToAdd->getColumnNumber() ?? 0; - $declarations = $this->getRules(); + $declarations = $this->getDeclarations(); $declarationsCount = \count($declarations); if ($declarationsCount > 0) { $last = $declarations[$declarationsCount - 1]; $lastsLineNumber = $last->getLineNumber(); if (!\is_int($lastsLineNumber)) { throw new \UnexpectedValueException( - 'A Declaration without a line number was found during addRule', + 'A Declaration without a line number was found during addDeclaration', 1750718399 ); } @@ -173,9 +174,9 @@ public function addRule(Declaration $declarationToAdd, ?Declaration $sibling = n /** * Returns all declarations matching the given property name * - * @example $ruleSet->getRules('font') // returns array(0 => $declaration, …) or array(). + * @example $ruleSet->getDeclarations('font') // returns array(0 => $declaration, …) or array(). * - * @example $ruleSet->getRules('font-') + * @example $ruleSet->getDeclarations('font-') * //returns an array of all declarations either beginning with font- or matching font. * * @param string|null $searchPattern @@ -185,7 +186,7 @@ public function addRule(Declaration $declarationToAdd, ?Declaration $sibling = n * * @return array, Declaration> */ - public function getRules(?string $searchPattern = null): array + public function getDeclarations(?string $searchPattern = null): array { $result = []; foreach ($this->declarations as $propertyName => $declarations) { @@ -214,11 +215,11 @@ public function getRules(?string $searchPattern = null): array * * @param array $declarations */ - public function setRules(array $declarations): void + public function setDeclarations(array $declarations): void { $this->declarations = []; foreach ($declarations as $declaration) { - $this->addRule($declaration); + $this->addDeclaration($declaration); } } @@ -238,11 +239,11 @@ public function setRules(array $declarations): void * * @return array */ - public function getRulesAssoc(?string $searchPattern = null): array + public function getDeclarationsAssociative(?string $searchPattern = null): array { /** @var array $result */ $result = []; - foreach ($this->getRules($searchPattern) as $declaration) { + foreach ($this->getDeclarations($searchPattern) as $declaration) { $result[$declaration->getPropertyName()] = $declaration; } @@ -252,7 +253,7 @@ public function getRulesAssoc(?string $searchPattern = null): array /** * Removes a `Declaration` from this `RuleSet` by identity. */ - public function removeRule(Declaration $declarationToRemove): void + public function removeDeclaration(Declaration $declarationToRemove): void { $nameOfPropertyToRemove = $declarationToRemove->getPropertyName(); if (!isset($this->declarations[$nameOfPropertyToRemove])) { @@ -274,7 +275,7 @@ public function removeRule(Declaration $declarationToRemove): void * all declarations starting with the pattern are removed as well as one matching the pattern with the dash * excluded. */ - public function removeMatchingRules(string $searchPattern): void + public function removeMatchingDeclarations(string $searchPattern): void { foreach ($this->declarations as $propertyName => $declarations) { // Either the search pattern matches the found declaration's property name exactly @@ -291,7 +292,7 @@ public function removeMatchingRules(string $searchPattern): void } } - public function removeAllRules(): void + public function removeAllDeclarations(): void { $this->declarations = []; } @@ -301,15 +302,15 @@ public function removeAllRules(): void */ public function render(OutputFormat $outputFormat): string { - return $this->renderRules($outputFormat); + return $this->renderDeclarations($outputFormat); } - protected function renderRules(OutputFormat $outputFormat): string + protected function renderDeclarations(OutputFormat $outputFormat): string { $result = ''; $isFirst = true; $nextLevelFormat = $outputFormat->nextLevel(); - foreach ($this->getRules() as $declaration) { + foreach ($this->getDeclarations() as $declaration) { $nextLevelFormatter = $nextLevelFormat->getFormatter(); $renderedDeclaration = $nextLevelFormatter->safely( static function () use ($declaration, $nextLevelFormat): string {