[TASK] Add RuleSet::removeMatchingRules(), with deprecation

Passing `string` or `null` to `removeRule()` is deprecated.
The new method handles that functionality.

Relates to #1247.

Author: JakeQZ

CHANGELOG.md

@@ -10,6 +10,8 @@ Please also have a look at our
 
 ### Added
 
+- `RuleSet::removeMatchingRules()` method for implementing classes `AtRuleSet`
+  and `DeclarationBlock` (#1249)
 - Add Interface `CSSElement` (#1231)
 - Methods `getLineNumber` and `getColumnNumber` which return a nullable `int`
   for the following classes:
@@ -46,6 +48,9 @@ Please also have a look at our
 
 ### Deprecated
 
+- Passing a `string` or `null` to `RuleSet::removeRule()` is deprecated
+  (implementing classes are `AtRuleSet` and `DeclarationBlock`);
+  use `removeMatchingRules()` instead (#1249)
 - Passing a string as the first argument to `getAllValues()` is deprecated;
   the search pattern should now be passed as the second argument (#1241)
 - Passing a Boolean as the second argument to `getAllValues()` is deprecated;

src/RuleSet/RuleSet.php

@@ -209,18 +209,12 @@ public function getRulesAssoc($searchPattern = null): array
     }
 
     /**
-     * Removes a rule from this RuleSet. This accepts all the possible values that `getRules()` accepts.
-     *
-     * If given a Rule, it will only remove this particular rule (by identity).
-     * If given a name, it will remove all rules by that name.
-     *
-     * Note: this is different from pre-v.2.0 behaviour of PHP-CSS-Parser, where passing a Rule instance would
-     * remove all rules with the same name. To get the old behaviour, use `removeRule($rule->getRule())`.
+     * Removes a `Rule` from this `RuleSet` by identity.
      *
      * @param Rule|string|null $searchPattern
-     *        pattern to remove. If null, all rules are removed. If the pattern ends in a dash,
-     *        all rules starting with the pattern are removed as well as one matching the pattern with the dash
-     *        excluded. Passing a Rule behaves matches by identity.
+     *        `Rule` to remove.
+     *        Passing a `string` or `null` is deprecated in version 8.9.0, and will no longer work from v9.0.
+     *        Use `removeMatchingRules()` instead.
      */
     public function removeRule($searchPattern): void
     {
@@ -235,18 +229,31 @@ public function removeRule($searchPattern): void
                 }
             }
         } else {
-            foreach ($this->rules as $propertyName => $rules) {
-                // Either no search rule is given or the search rule matches the found rule exactly
-                // or the search rule ends in “-” and the found rule starts with the search rule or equals it
-                // (without the trailing dash).
-                if (
-                    $searchPattern === null || $propertyName === $searchPattern
-                    || (\strrpos($searchPattern, '-') === \strlen($searchPattern) - \strlen('-')
-                        && (\strpos($propertyName, $searchPattern) === 0
-                            || $propertyName === \substr($searchPattern, 0, -1)))
-                ) {
-                    unset($this->rules[$propertyName]);
-                }
+            $this->removeMatchingRules($searchPattern);
+        }
+    }
+
+    /**
+     * Removes rules by property name or search pattern.
+     *
+     * @param string|null $searchPattern
+     *        pattern to remove. If null, all rules are removed. If the pattern ends in a dash,
+     *        all rules starting with the pattern are removed as well as one matching the pattern with the dash
+     *        excluded.
+     */
+    public function removeMatchingRules(?string $searchPattern): void
+    {
+        foreach ($this->rules as $propertyName => $rules) {
+            // Either no search rule is given or the search rule matches the found rule exactly
+            // or the search rule ends in “-” and the found rule starts with the search rule or equals it
+            // (without the trailing dash).
+            if (
+                $searchPattern === null || $propertyName === $searchPattern
+                || (\strrpos($searchPattern, '-') === \strlen($searchPattern) - \strlen('-')
+                    && (\strpos($propertyName, $searchPattern) === 0
+                        || $propertyName === \substr($searchPattern, 0, -1)))
+            ) {
+                unset($this->rules[$propertyName]);
             }
         }
     }