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

This is the backport of #1231, #1240 and #1241.

Author: JakeQZ

CHANGELOG.md

@@ -7,6 +7,7 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- Add Interface `CSSElement` (#1231)
 - Methods `getLineNumber` and `getColumnNumber` which return a nullable `int`
   for the following classes:
   `Comment`, `CSSList`, `SourceException`, `Charset`, `CSSNamespace`, `Import`,
@@ -16,12 +17,20 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ### 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)
 
 ### 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/CSSElement.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sabberworm\CSS;
+
+/**
+ * Represents any entity in the CSS that is encapsulated by a class.
+ *
+ * Its primary purpose is to provide a type for use with `Document::getAllValues()`
+ * when a subset of values from a particular part of the document is required.
+ *
+ * Thus, elements which don't contain `Value`s (such as statement at-rules) don't need to implement this.
+ *
+ * It extends `Renderable` because every element is renderable.
+ */
+interface CSSElement extends Renderable {}

src/CSSList/CSSBlockList.php

@@ -2,6 +2,7 @@
 
 namespace Sabberworm\CSS\CSSList;
 
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\Property\Selector;
 use Sabberworm\CSS\Rule\Rule;
 use Sabberworm\CSS\RuleSet\DeclarationBlock;
@@ -59,7 +60,53 @@ protected function allRuleSets(array &$aResult)
     }
 
     /**
-     * @param CSSList|Rule|RuleSet|Value $oElement
+     * Returns all `Value` objects found recursively in `Rule`s in the tree.
+     *
+     * @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,
+        $ruleSearchPatternOrSearchInFunctionArguments = null,
+        $searchInFunctionArguments = false
+    ) {
+        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;
+    }
+
+    /**
+     * @param CSSElement|string $oElement
      * @param array<int, Value> $aResult
      * @param string|null $sSearchString
      * @param bool $bSearchInFunctionArguments

src/CSSList/CSSList.php

@@ -4,6 +4,7 @@
 
 use Sabberworm\CSS\Comment\Comment;
 use Sabberworm\CSS\Comment\Commentable;
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\SourceException;
@@ -31,7 +32,7 @@
  *
  * It can also contain `Import` and `Charset` objects stemming from at-rules.
  */
-abstract class CSSList implements Commentable, Positionable, Renderable
+abstract class CSSList implements Commentable, CSSElement, Positionable
 {
     use Position;
 

src/CSSList/Document.php

@@ -8,7 +8,6 @@
 use Sabberworm\CSS\Property\Selector;
 use Sabberworm\CSS\RuleSet\DeclarationBlock;
 use Sabberworm\CSS\RuleSet\RuleSet;
-use Sabberworm\CSS\Value\Value;
 
 /**
  * This class represents the root of a parsed CSS file. It contains all top-level CSS contents: mostly declaration
@@ -77,33 +76,6 @@ public function getAllRuleSets()
         return $aResult;
     }
 
-    /**
-     * Returns all `Value` objects found recursively in `Rule`s in the tree.
-     *
-     * @param CSSList|RuleSet|string $mElement
-     *        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 bool $bSearchInFunctionArguments whether to also return Value objects used as Function arguments.
-     *
-     * @return array<int, Value>
-     *
-     * @see RuleSet->getRules()
-     */
-    public function getAllValues($mElement = null, $bSearchInFunctionArguments = false)
-    {
-        $sSearchString = null;
-        if ($mElement === null) {
-            $mElement = $this;
-        } elseif (is_string($mElement)) {
-            $sSearchString = $mElement;
-            $mElement = $this;
-        }
-        /** @var array<int, Value> $aResult */
-        $aResult = [];
-        $this->allValues($mElement, $aResult, $sSearchString, $bSearchInFunctionArguments);
-        return $aResult;
-    }
-
     /**
      * Returns all `Selector` objects with the requested specificity found recursively in the tree.
      *

src/Rule/Rule.php

@@ -4,13 +4,13 @@
 
 use Sabberworm\CSS\Comment\Comment;
 use Sabberworm\CSS\Comment\Commentable;
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
 use Sabberworm\CSS\Position\Position;
 use Sabberworm\CSS\Position\Positionable;
-use Sabberworm\CSS\Renderable;
 use Sabberworm\CSS\Value\RuleValueList;
 use Sabberworm\CSS\Value\Value;
 
@@ -19,7 +19,7 @@
  *
  * In CSS, `Rule`s are expressed as follows: “key: value[0][0] value[0][1], value[1][0] value[1][1];”
  */
-class Rule implements Commentable, Positionable, Renderable
+class Rule implements Commentable, CSSElement, Positionable
 {
     use Position;
 

src/RuleSet/RuleSet.php

@@ -4,6 +4,7 @@
 
 use Sabberworm\CSS\Comment\Comment;
 use Sabberworm\CSS\Comment\Commentable;
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\OutputFormat;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
@@ -22,7 +23,7 @@
  * If you want to manipulate a `RuleSet`, use the methods `addRule(Rule $rule)`, `getRules()` and `removeRule($rule)`
  * (which accepts either a `Rule` or a rule name; optionally suffixed by a dash to remove all related rules).
  */
-abstract class RuleSet implements Commentable, Positionable, Renderable
+abstract class RuleSet implements CSSElement, Commentable, Positionable
 {
     use Position;
 

src/Value/Value.php

@@ -2,19 +2,19 @@
 
 namespace Sabberworm\CSS\Value;
 
+use Sabberworm\CSS\CSSElement;
 use Sabberworm\CSS\Parsing\ParserState;
 use Sabberworm\CSS\Parsing\SourceException;
 use Sabberworm\CSS\Parsing\UnexpectedEOFException;
 use Sabberworm\CSS\Parsing\UnexpectedTokenException;
 use Sabberworm\CSS\Position\Position;
 use Sabberworm\CSS\Position\Positionable;
-use Sabberworm\CSS\Renderable;
 
 /**
  * Abstract base class for specific classes of CSS values: `Size`, `Color`, `CSSString` and `URL`, and another
  * abstract subclass `ValueList`.
  */
-abstract class Value implements Positionable, Renderable
+abstract class Value implements CSSElement, Positionable
 {
     use Position;