[TASK] Add interface RuleContainer for RuleSet (#1256)

This covers the maniplation of `Rule`s within the container,
and may be implemented by other classes in future (e.g. #1194).

Note that the naming is consistent with the current codebase,
rather than what the CSS entities are now called:
- `Rule` represents what is now called a "declaration";
- `RuleSet` represents what is now called a "declaration block";
- `DeclarationBlock` represents what is now called a "style rule";
- `CSSListItem` (closely) represents what is now generically called a "rule".

Renaming things is part of a longer-term plan touched on in #1189.

Author: JakeQZ

CHANGELOG.md

@@ -10,6 +10,7 @@ Please also have a look at our
 
 ### Added
 
+- Interface `RuleContainer` for `RuleSet` `Rule` manipulation methods (#1256)
 - `RuleSet::removeMatchingRules()` method
   (for the implementing classes `AtRuleSet` and `DeclarationBlock`) (#1249)
 - `RuleSet::removeAllRules()` method

README.md

@@ -636,6 +636,9 @@ classDiagram
     class CSSListItem {
         <<interface>>
     }
+    class RuleContainer {
+        <<interface>>
+    }
     class DeclarationBlock {
     }
     class RuleSet {
@@ -730,6 +733,7 @@ classDiagram
     Positionable <|.. RuleSet: realization
     CSSElement <|.. RuleSet: realization
     CSSListItem <|.. RuleSet: realization
+    RuleContainer <|.. RuleSet: realization
     RuleSet <|-- AtRuleSet: inheritance
     AtRule <|.. AtRuleSet: realization
     Renderable <|.. Selector: realization

src/CSSList/CSSBlockList.php

@@ -8,6 +8,7 @@
 use Sabberworm\CSS\Property\Selector;
 use Sabberworm\CSS\Rule\Rule;
 use Sabberworm\CSS\RuleSet\DeclarationBlock;
+use Sabberworm\CSS\RuleSet\RuleContainer;
 use Sabberworm\CSS\RuleSet\RuleSet;
 use Sabberworm\CSS\Value\CSSFunction;
 use Sabberworm\CSS\Value\Value;
@@ -95,7 +96,7 @@ public function getAllValues(
                     );
                 }
             }
-        } elseif ($element instanceof RuleSet) {
+        } elseif ($element instanceof RuleContainer) {
             foreach ($element->getRules($ruleSearchPattern) as $rule) {
                 $result = \array_merge(
                     $result,

src/RuleSet/RuleContainer.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS\RuleSet;
+
+use Sabberworm\CSS\Rule\Rule;
+
+/**
+ * Represents a CSS item that contains `Rules`, defining the methods to manipulate them.
+ */
+interface RuleContainer
+{
+    public function addRule(Rule $ruleToAdd, ?Rule $sibling = null): void;
+
+    public function removeRule(Rule $ruleToRemove): void;
+
+    public function removeMatchingRules(string $searchPattern): void;
+
+    public function removeAllRules(): void;
+
+    /**
+     * @param array<Rule> $rules
+     */
+    public function setRules(array $rules): void;
+
+    /**
+     * @return array<int<0, max>, Rule>
+     */
+    public function getRules(?string $searchPattern = null): array;
+
+    /**
+     * @return array<string, Rule>
+     */
+    public function getRulesAssoc(?string $searchPattern = null): array;
+}

src/RuleSet/RuleSet.php

@@ -27,7 +27,7 @@
  * Note that `CSSListItem` extends both `Commentable` and `Renderable`,
  * so those interfaces must also be implemented by concrete subclasses.
  */
-abstract class RuleSet implements CSSElement, CSSListItem, Positionable
+abstract class RuleSet implements CSSElement, CSSListItem, Positionable, RuleContainer
 {
     use CommentContainer;
     use Position;

tests/Unit/RuleSet/RuleSetTest.php

@@ -8,6 +8,7 @@
 use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\CSSList\CSSListItem;
 use Sabberworm\CSS\Rule\Rule;
+use Sabberworm\CSS\RuleSet\RuleContainer;
 use Sabberworm\CSS\Tests\Unit\RuleSet\Fixtures\ConcreteRuleSet;
 
 /**
@@ -41,6 +42,14 @@ public function implementsCSSListItem(): void
         self::assertInstanceOf(CSSListItem::class, $this->subject);
     }
 
+    /**
+     * @test
+     */
+    public function implementsRuleContainer(): void
+    {
+        self::assertInstanceOf(RuleContainer::class, $this->subject);
+    }
+
     /**
      * @return array<string, array{0: list<Rule>, 1: string, 2: list<string>}>
      */