[TASK] Rename methods in RuleContainer

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,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\RuleSet;
+
+use Sabberworm\CSS\Property\Declaration;
+
+/**
+ * Provides a mapping of the deprecated methods in a `RuleContainer` to their renamed replacements.
+ */
+trait LegacyRuleContainerMethods
+{
+    /**
+     * @deprecated in v9.2, will be removed in v10.0; use `addDeclaration()` instead.
+     */
+    public function addRule(Declaration $declarationToAdd, ?Declaration $sibling = null): void
+    {
+        $this->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<Declaration> $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<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 $this->getDeclarations($searchPattern);
+    }
+
+    /**
+     * @return array<string, Declaration>
+     *
+     * @deprecated in v9.2, will be removed in v10.0; use `getDeclarationsAssociative()` instead.
+     */
+    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;
 }