[TASK] Deconflate getAllValues() parameters

CHANGELOG.md

@@ -27,6 +27,9 @@ Please also have a look at our
 
 ### Changed
 
+- Parameters for `getAllValues()` are deconflated, so it now takes three (all
+  optional), allowing `$element` and `$ruleSearchPattern` to be specified
+  separately (#1241)
 - Implement `Positionable` in the following CSS item classes:
   `Comment`, `CSSList`, `SourceException`, `Charset`, `CSSNamespace`, `Import`,
   `Rule`, `DeclarationBlock`, `RuleSet`, `CSSFunction`, `Value` (#1225)
@@ -43,6 +46,11 @@ Please also have a look at our
 
 ### Deprecated
 
+- 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;
+  the flag for searching in function arguments should now be passed as the third
+  argument (#1241)
 - `getLineNo()` is deprecated in these classes (use `getLineNumber()` instead):
   `Comment`, `CSSList`, `SourceException`, `Charset`, `CSSNamespace`, `Import`,
   `Rule`, `DeclarationBlock`, `RuleSet`, `CSSFunction`, `Value` (#1225, #1233)

src/CSSList/CSSBlockList.php

@@ -64,24 +64,44 @@ public function getAllRuleSets(): array
     /**
      * Returns all `Value` objects found recursively in `Rule`s in the tree.
      *
-     * @param CSSElement|string $element
-     *        the `CSSList` or `RuleSet` to start the search from (defaults to the whole document).
-     *        If a string is given, it is used as rule name filter.
+     * @param CSSElement|string|null $element
+     *        This is the `CSSList` or `RuleSet` to start the search from (defaults to the whole document).
+     *        If a string is given, it is used as a rule name filter.
+     *        Passing a string for this parameter is deprecated in version 8.9.0, and will not work from v9.0;
+     *        use the following parameter to pass a rule name filter instead.
+     * @param string|bool|null $ruleSearchPatternOrSearchInFunctionArguments
+     *        This allows filtering rules by property name
+     *        (e.g. if "color" is passed, only `Value`s from `color` properties will be returned,
+     *        or if "font-" is provided, `Value`s from all font rules, like `font-size`, and including `font` itself,
+     *        will be returned).
+     *        If a Boolean is provided, it is treated as the `$searchInFunctionArguments` argument.
+     *        Passing a Boolean for this parameter is deprecated in version 8.9.0, and will not work from v9.0;
+     *        use the `$searchInFunctionArguments` parameter instead.
      * @param bool $searchInFunctionArguments whether to also return Value objects used as Function arguments.
      *
      * @return array<int, Value>
      *
      * @see RuleSet->getRules()
      */
-    public function getAllValues($element = null, bool $searchInFunctionArguments = false): array
-    {
-        $searchString = null;
+    public function getAllValues(
+        $element = null,
+        $ruleSearchPatternOrSearchInFunctionArguments = null,
+        bool $searchInFunctionArguments = false
+    ): array {
+        if (\is_bool($ruleSearchPatternOrSearchInFunctionArguments)) {
+            $searchInFunctionArguments = $ruleSearchPatternOrSearchInFunctionArguments;
+            $searchString = null;
+        } else {
+            $searchString = $ruleSearchPatternOrSearchInFunctionArguments;
+        }
+
         if ($element === null) {
             $element = $this;
         } elseif (\is_string($element)) {
             $searchString = $element;
             $element = $this;
         }
+
         $result = [];
         $this->allValues($element, $result, $searchString, $searchInFunctionArguments);
         return $result;

tests/Unit/CSSList/CSSBlockListTest.php

@@ -430,6 +430,30 @@ public function getAllValuesWithSearchStringProvidedReturnsOnlyValuesFromMatchin
         self::assertSame([$value1], $result);
     }
 
+    /**
+     * @test
+     */
+    public function getAllValuesWithSearchStringProvidedInNewMethodSignatureReturnsOnlyValuesFromMatchingRules(): void
+    {
+        $subject = new ConcreteCSSBlockList();
+
+        $value1 = new CSSString('Superfont');
+        $value2 = new CSSString('aquamarine');
+
+        $declarationBlock = new DeclarationBlock();
+        $rule1 = new Rule('font-family');
+        $rule1->setValue($value1);
+        $declarationBlock->addRule($rule1);
+        $rule2 = new Rule('color');
+        $rule2->setValue($value2);
+        $declarationBlock->addRule($rule2);
+        $subject->setContents([$declarationBlock]);
+
+        $result = $subject->getAllValues(null, 'font-');
+
+        self::assertSame([$value1], $result);
+    }
+
     /**
      * @test
      */
@@ -471,4 +495,25 @@ public function getAllValuesWithSearchInFunctionArgumentsReturnsValuesInFunction
 
         self::assertSame([$value1, $value2], $result);
     }
+
+    /**
+     * @test
+     */
+    public function getAllValuesWithSearchInFunctionArgumentsInNewMethodSignatureReturnsValuesInFunctionArguments(): void
+    {
+        $subject = new ConcreteCSSBlockList();
+
+        $value1 = new Size(10, 'px');
+        $value2 = new Size(2, '%');
+
+        $declarationBlock = new DeclarationBlock();
+        $rule = new Rule('margin');
+        $rule->setValue(new CSSFunction('max', [$value1, $value2]));
+        $declarationBlock->addRule($rule);
+        $subject->setContents([$declarationBlock]);
+
+        $result = $subject->getAllValues(null, null, true);
+
+        self::assertSame([$value1, $value2], $result);
+    }
 }