From 2477c9cec845d228dd8f8891c5cca4201a9e0326 Mon Sep 17 00:00:00 2001 From: Jake Hotson Date: Fri, 11 Apr 2025 01:07:21 +0100 Subject: [PATCH] [TASK] Deconflate `getAllValues()` parameters 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. --- CHANGELOG.md | 8 +++++ src/CSSList/CSSBlockList.php | 32 ++++++++++++++---- tests/Unit/CSSList/CSSBlockListTest.php | 45 +++++++++++++++++++++++++ 3 files changed, 79 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a74924aa..13e28ddd 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/src/CSSList/CSSBlockList.php b/src/CSSList/CSSBlockList.php index 0423caea..3e936912 100644 --- a/src/CSSList/CSSBlockList.php +++ b/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 * * @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; diff --git a/tests/Unit/CSSList/CSSBlockListTest.php b/tests/Unit/CSSList/CSSBlockListTest.php index 84e53610..2a83f647 100644 --- a/tests/Unit/CSSList/CSSBlockListTest.php +++ b/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); + } }