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