[TASK] Rename methods in RuleContainer

E.g. `addRule()` is changed to `addDeclaration()`, with `addRule()` deprecated
and changed to a wrapper method to call on to `addDeclaration()`.

`RuleContainer` itself should be renamed to `DeclarationContainer` as a
separate change.

The tests will also be updated as a separate change.

Author: JakeQZ

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

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;
     }

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<int<0, max>, 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<Declaration> $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<string, Declaration>
      *
-     * @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();
     }
 
     /**

src/RuleSet/LegacyRuleContainerMethods.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\RuleSet;
+
+use Sabberworm\CSS\Property\Declaration;
+
+/**
+ * @internal
+ */
+trait LegacyRuleContainerMethods
+{
+    public function addRule(Declaration $declarationToAdd, ?Declaration $sibling = null): void
+    {
+        $this->addDeclaration($declarationToAdd, $sibling);
+    }
+
+    public function removeRule(Declaration $declarationToRemove): void
+    {
+        $this->removeDeclaration($declarationToRemove);
+    }
+
+    public function removeMatchingRules(string $searchPattern): void
+    {
+        $this->removeMatchingDeclarations($searchPattern);
+    }
+
+    public function removeAllRules(): void
+    {
+        $this->removeAllDeclarations();
+    }
+
+    /**
+     * @param array<Declaration> $declarations
+     */
+    public function setRules(array $declarations): void
+    {
+        $this->setDeclarations($declarations);
+    }
+
+    /**
+     * @return array<int<0, max>, Declaration>
+     */
+    public function getRules(?string $searchPattern = null): array
+    {
+        return $this->getDeclarations($searchPattern);
+    }
+
+    /**
+     * @return array<string, Declaration>
+     */
+    public function getRulesAssoc(?string $searchPattern = null): array
+    {
+        return $this->getDeclarationsAssociative($searchPattern);
+    }
+}

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<Declaration> $declarations
+     */
+    public function setDeclarations(array $declarations): void;
+
+    /**
+     * @return array<int<0, max>, Declaration>
+     */
+    public function getDeclarations(?string $searchPattern = null): array;
+
+    /**
+     * @return array<string, Declaration>
+     */
+    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<Declaration> $declarations
+     *
+     * @deprecated in v9.2, will be removed in v10.0; use `setDeclarations()` instead.
      */
     public function setRules(array $declarations): void;
 
     /**
      * @return array<int<0, max>, Declaration>
+     *
+     * @deprecated in v9.2, will be removed in v10.0; use `getDeclarations()` instead.
      */
     public function getRules(?string $searchPattern = null): array;
 
     /**
      * @return array<string, Declaration>
+     *
+     * @deprecated in v9.2, will be removed in v10.0; use `getDeclarationsAssociative()` instead.
      */
     public function getRulesAssoc(?string $searchPattern = null): array;
 }

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<int<0, max>, 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<Declaration> $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<string, Declaration>
      */
-    public function getRulesAssoc(?string $searchPattern = null): array
+    public function getDeclarationsAssociative(?string $searchPattern = null): array
     {
         /** @var array<string, Declaration> $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 {