[TASK] Deconflate getAllValues() parameters (#1241)

The `$element` parameter was overloaded with a dual purpose.

A second separate parameter has been added for rule filtering,
which is not actually mutually exclusive with CSS subtree selection.

Since `getAllValues()` is part of the public API,
the method now supports being called with the old or new signatures,
with the old signature being deprecated.

Once the deprecation has been included in the 8.x release branch,
the messiness of supporting the previous API can be removed.

Part of #994.  Also relates to #1230.

Author: JakeQZ

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