From 19967e0f4aaeb7efd40368060d9164c8693321ba Mon Sep 17 00:00:00 2001 From: Sergei Predvoditelev Date: Sun, 15 Mar 2026 19:49:21 +0300 Subject: [PATCH 1/2] Rename `$options` parameter to `$attributes` --- CHANGELOG.md | 2 + UPGRADE.md | 3 + src/Html.php | 93 ++++++++++++------------- tests/HtmlTest.php | 168 ++++++++++++++++++++++----------------------- 4 files changed, 136 insertions(+), 130 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c3eecd..dc6c9a2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,8 @@ - Chg #221: Throw `LogicException` in `Tag::id()` when id is empty string (@razvbir) - Chg #267: Make all `CheckboxItem` and `RadioItem` properties required (@vjik) - Chg #234: Remove tag attributes sorting (@FrankiFixx) +- Chg #269: Rename `$options` parameter to `$attributes` in `Html::addCssClass()`, `Html::removeCssClass()`, + `Html::addCssStyle()` and `Html::removeCssStyle()` methods (@vjik) ## 3.13.0 March 13, 2026 diff --git a/UPGRADE.md b/UPGRADE.md index 3c57137..c3dee9a 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -17,3 +17,6 @@ application when you upgrade the package from one version to another. according to a predefined priority list (`type`, `id`, `class`, `name`, `value`, etc.). Now attributes are rendered in the order they are set. If your code or tests depend on a specific attribute order in the rendered HTML, you need to update them. +- The `$options` parameter has been renamed to `$attributes` in the following methods: `Html::addCssClass()`, + `Html::removeCssClass()`, `Html::addCssStyle()` and `Html::removeCssStyle()`. If you use named arguments when + calling these methods, update them accordingly. diff --git a/src/Html.php b/src/Html.php index d711356..0c6048d 100644 --- a/src/Html.php +++ b/src/Html.php @@ -100,7 +100,7 @@ * Html provides a set of static methods for generating commonly used HTML tags. * * Nearly all the methods in this class allow setting additional HTML attributes for the HTML tags they generate. - * You can specify, for example, `class`, `style` or `id` for an HTML element using the `$options` parameter. See the + * You can specify, for example, `class`, `style` or `id` for an HTML element using the `$attributes` parameter. See the * documentation of the {@see tag()} method for more details. */ final class Html @@ -1695,28 +1695,29 @@ public static function renderTagAttributes(array $attributes): string } /** - * Adds a CSS class (or several classes) to the specified options. + * Adds a CSS class (or several classes) to the specified attributes. * - * If the CSS class is already in the options, it will not be added again. If class specification at given options - * is an array, and some class placed there with the named (string) key, overriding of such key will have no - * effect. For example: + * If the CSS class is already in the attributes, it will not be added again. If class specification at given + * attributes is an array, and some class placed there with the named (string) key, overriding of such key will have + * no effect. For example: * * ```php - * $options = ['class' => ['persistent' => 'initial']]; + * $attributes = ['class' => ['persistent' => 'initial']]; * * // ['class' => ['persistent' => 'initial']]; - * Html::addCssClass($options, ['persistent' => 'override']); + * Html::addCssClass($attributes, ['persistent' => 'override']); * ``` * * @see removeCssClass() * - * @param array $options The options to be modified. All string values in the array must be valid UTF-8 strings. + * @param array $attributes The attributes to be modified. All string values in the array must be valid UTF-8 + * strings. * @param BackedEnum|BackedEnum[]|null[]|string|string[]|null $class The CSS class(es) to be added. Null values will * be ignored. * * @psalm-param BackedEnum|string|array|null $class */ - public static function addCssClass(array &$options, BackedEnum|array|string|null $class): void + public static function addCssClass(array &$attributes, BackedEnum|array|string|null $class): void { if ($class === null) { return; @@ -1746,83 +1747,83 @@ public static function addCssClass(array &$options, BackedEnum|array|string|null $class = $filteredClass; } - if (isset($options['class'])) { - if (is_array($options['class'])) { - /** @psalm-var string[] $options['class'] */ - $options['class'] = self::mergeCssClasses($options['class'], (array) $class); + if (isset($attributes['class'])) { + if (is_array($attributes['class'])) { + /** @psalm-var string[] $attributes['class'] */ + $attributes['class'] = self::mergeCssClasses($attributes['class'], (array) $class); } else { /** - * @psalm-var string $options['class'] - * @var string[] $classes We assume that `$options['class']` is valid UTF-8 string, so `preg_split()` + * @psalm-var string $attributes['class'] + * @var string[] $classes We assume that `$attributes['class']` is valid UTF-8 string, so `preg_split()` * never returns `false`. */ - $classes = preg_split('/\s+/', $options['class'], -1, PREG_SPLIT_NO_EMPTY); + $classes = preg_split('/\s+/', $attributes['class'], -1, PREG_SPLIT_NO_EMPTY); $classes = self::mergeCssClasses($classes, (array) $class); - $options['class'] = is_array($class) ? $classes : implode(' ', $classes); + $attributes['class'] = is_array($class) ? $classes : implode(' ', $classes); } } else { - $options['class'] = $class; + $attributes['class'] = $class; } } /** - * Removes a CSS class from the specified options. + * Removes a CSS class from the specified attributes. * * @see addCssClass() * - * @param array $options The options to be modified. + * @param array $attributes The attributes to be modified. * @param string|string[] $class The CSS class(es) to be removed. */ - public static function removeCssClass(array &$options, string|array $class): void + public static function removeCssClass(array &$attributes, string|array $class): void { - if (isset($options['class'])) { - if (is_array($options['class'])) { - $classes = array_diff($options['class'], (array) $class); + if (isset($attributes['class'])) { + if (is_array($attributes['class'])) { + $classes = array_diff($attributes['class'], (array) $class); if (empty($classes)) { - unset($options['class']); + unset($attributes['class']); } else { - $options['class'] = $classes; + $attributes['class'] = $classes; } } else { /** @var string[] */ - $classes = preg_split('/\s+/', (string) $options['class'], -1, PREG_SPLIT_NO_EMPTY); + $classes = preg_split('/\s+/', (string) $attributes['class'], -1, PREG_SPLIT_NO_EMPTY); $classes = array_diff($classes, (array) $class); if (empty($classes)) { - unset($options['class']); + unset($attributes['class']); } else { - $options['class'] = implode(' ', $classes); + $attributes['class'] = implode(' ', $classes); } } } } /** - * Adds the specified CSS styles to the HTML options. + * Adds the specified CSS styles to the HTML attributes. * - * If the options already contain a `style` element, the new style will be merged + * If the attributes already contain a `style` element, the new style will be merged * with the existing one. If a CSS property exists in both the new and the old styles, * the old one may be overwritten if `$overwrite` is true. * * For example, * * ```php - * Html::addCssStyle($options, 'width: 100px; height: 200px'); + * Html::addCssStyle($attributes, 'width: 100px; height: 200px'); * ``` * * @see removeCssStyle() * - * @param array $options The HTML options to be modified. + * @param array $attributes The HTML attributes to be modified. * @param string|string[] $style The new style string (e.g. `'width: 100px; height: 200px'`) or array * (e.g. `['width' => '100px', 'height' => '200px']`). * @param bool $overwrite Whether to overwrite existing CSS properties if the new style contain them too. * * @psalm-param array|string $style */ - public static function addCssStyle(array &$options, array|string $style, bool $overwrite = true): void + public static function addCssStyle(array &$attributes, array|string $style, bool $overwrite = true): void { - if (!empty($options['style'])) { - /** @psalm-var array|string $options['style'] */ - $oldStyle = is_array($options['style']) ? $options['style'] : self::cssStyleToArray($options['style']); + if (!empty($attributes['style'])) { + /** @psalm-var array|string $attributes['style'] */ + $oldStyle = is_array($attributes['style']) ? $attributes['style'] : self::cssStyleToArray($attributes['style']); $newStyle = is_array($style) ? $style : self::cssStyleToArray($style); if (!$overwrite) { foreach ($newStyle as $property => $_value) { @@ -1833,33 +1834,33 @@ public static function addCssStyle(array &$options, array|string $style, bool $o } $style = array_merge($oldStyle, $newStyle); } - $options['style'] = is_array($style) ? self::cssStyleFromArray($style) : $style; + $attributes['style'] = is_array($style) ? self::cssStyleFromArray($style) : $style; } /** - * Removes the specified CSS styles from the HTML options. + * Removes the specified CSS styles from the HTML attributes. * * For example, * * ```php - * Html::removeCssStyle($options, ['width', 'height']); + * Html::removeCssStyle($attributes, ['width', 'height']); * ``` * * @see addCssStyle() * - * @param array $options The HTML options to be modified. + * @param array $attributes The HTML attributes to be modified. * @param string|string[] $properties The CSS properties to be removed. You may use a string if you are removing a * single property. */ - public static function removeCssStyle(array &$options, string|array $properties): void + public static function removeCssStyle(array &$attributes, string|array $properties): void { - if (!empty($options['style'])) { - /** @psalm-var array|string $options['style'] */ - $style = is_array($options['style']) ? $options['style'] : self::cssStyleToArray($options['style']); + if (!empty($attributes['style'])) { + /** @psalm-var array|string $attributes['style'] */ + $style = is_array($attributes['style']) ? $attributes['style'] : self::cssStyleToArray($attributes['style']); foreach ((array) $properties as $property) { unset($style[$property]); } - $options['style'] = self::cssStyleFromArray($style); + $attributes['style'] = self::cssStyleFromArray($style); } } diff --git a/tests/HtmlTest.php b/tests/HtmlTest.php index f13ad10..597f2e7 100644 --- a/tests/HtmlTest.php +++ b/tests/HtmlTest.php @@ -1003,26 +1003,26 @@ public static function dataAddCssClass(): array } #[DataProvider('dataAddCssClass')] - public function testAddCssClass(array $expected, array $options, array|string|null $class): void + public function testAddCssClass(array $expected, array $attributes, array|string|null $class): void { - Html::addCssClass($options, $class); - $this->assertSame($expected, $options); + Html::addCssClass($attributes, $class); + $this->assertSame($expected, $attributes); } public function testAddCssClassWithBackedEnum(): void { - $options = ['class' => 'test']; - Html::addCssClass($options, ClassEnum::TEST_CLASS_2); - $this->assertSame(['class' => 'test test-class-2'], $options); + $attributes = ['class' => 'test']; + Html::addCssClass($attributes, ClassEnum::TEST_CLASS_2); + $this->assertSame(['class' => 'test test-class-2'], $attributes); - Html::addCssClass($options, IntegerEnum::A); - $this->assertSame(['class' => 'test test-class-2'], $options); + Html::addCssClass($attributes, IntegerEnum::A); + $this->assertSame(['class' => 'test test-class-2'], $attributes); - Html::addCssClass($options, ClassEnum::TEST_CLASS_1); - $this->assertSame(['class' => 'test test-class-2 test-class-1'], $options); + Html::addCssClass($attributes, ClassEnum::TEST_CLASS_1); + $this->assertSame(['class' => 'test test-class-2 test-class-1'], $attributes); - Html::addCssClass($options, IntegerEnum::B); - $this->assertSame(['class' => 'test test-class-2 test-class-1'], $options); + Html::addCssClass($attributes, IntegerEnum::B); + $this->assertSame(['class' => 'test test-class-2 test-class-1'], $attributes); } /** @@ -1030,37 +1030,37 @@ public function testAddCssClassWithBackedEnum(): void */ public function testMergeCssClass(): void { - $options = [ + $attributes = [ 'class' => [ 'persistent' => 'test1', ], ]; - Html::addCssClass($options, ['persistent' => 'test2']); - $this->assertSame(['persistent' => 'test1'], $options['class']); - Html::addCssClass($options, ['additional' => 'test2']); - $this->assertSame(['persistent' => 'test1', 'additional' => 'test2'], $options['class']); + Html::addCssClass($attributes, ['persistent' => 'test2']); + $this->assertSame(['persistent' => 'test1'], $attributes['class']); + Html::addCssClass($attributes, ['additional' => 'test2']); + $this->assertSame(['persistent' => 'test1', 'additional' => 'test2'], $attributes['class']); } public function testAddCssClassArrayToString(): void { - $options = ['class' => 'test']; + $attributes = ['class' => 'test']; - Html::addCssClass($options, ['test1', 'test2']); + Html::addCssClass($attributes, ['test1', 'test2']); $this->assertSame( [ 'class' => ['test', 'test1', 'test2'], ], - $options, + $attributes, ); } public function testAddCssClassWithKeyToString(): void { - $options = ['class' => 'test_class']; + $attributes = ['class' => 'test_class']; - Html::addCssClass($options, ['widget' => 'some_widget_class']); - Html::addCssClass($options, ['widget' => 'some_other_widget_class_2']); + Html::addCssClass($attributes, ['widget' => 'some_widget_class']); + Html::addCssClass($attributes, ['widget' => 'some_other_widget_class_2']); $this->assertSame( [ @@ -1069,16 +1069,16 @@ public function testAddCssClassWithKeyToString(): void 'widget' => 'some_widget_class', ], ], - $options, + $attributes, ); } public function testAddCssClassWithKeyToArray(): void { - $options = ['class' => ['test_class']]; + $attributes = ['class' => ['test_class']]; - Html::addCssClass($options, ['widget' => 'some_widget_class']); - Html::addCssClass($options, ['widget' => 'some_other_widget_class_2']); + Html::addCssClass($attributes, ['widget' => 'some_widget_class']); + Html::addCssClass($attributes, ['widget' => 'some_other_widget_class_2']); $this->assertSame( [ @@ -1087,16 +1087,16 @@ public function testAddCssClassWithKeyToArray(): void 'widget' => 'some_widget_class', ], ], - $options, + $attributes, ); } public function testAddCssClassWithKeyToKeyArray(): void { - $options = ['class' => ['widget' => 'test_class']]; + $attributes = ['class' => ['widget' => 'test_class']]; - Html::addCssClass($options, ['widget' => 'some_widget_class']); - Html::addCssClass($options, ['widget' => 'some_other_widget_class_2']); + Html::addCssClass($attributes, ['widget' => 'some_widget_class']); + Html::addCssClass($attributes, ['widget' => 'some_other_widget_class_2']); $this->assertSame( [ @@ -1104,34 +1104,34 @@ public function testAddCssClassWithKeyToKeyArray(): void 'widget' => 'test_class', ], ], - $options, + $attributes, ); } public function testRemoveCssClass(): void { - $options = ['class' => 'test test2 test3']; - Html::removeCssClass($options, 'test2'); - $this->assertSame(['class' => 'test test3'], $options); - Html::removeCssClass($options, 'test2'); - $this->assertSame(['class' => 'test test3'], $options); - Html::removeCssClass($options, 'test'); - $this->assertSame(['class' => 'test3'], $options); - Html::removeCssClass($options, 'test3'); - $this->assertSame([], $options); - - $options = ['class' => ['test', 'test2', 'test3']]; - Html::removeCssClass($options, 'test2'); - $this->assertSame(['class' => ['test', 2 => 'test3']], $options); - Html::removeCssClass($options, 'test'); - Html::removeCssClass($options, 'test3'); - $this->assertSame([], $options); - - $options = [ + $attributes = ['class' => 'test test2 test3']; + Html::removeCssClass($attributes, 'test2'); + $this->assertSame(['class' => 'test test3'], $attributes); + Html::removeCssClass($attributes, 'test2'); + $this->assertSame(['class' => 'test test3'], $attributes); + Html::removeCssClass($attributes, 'test'); + $this->assertSame(['class' => 'test3'], $attributes); + Html::removeCssClass($attributes, 'test3'); + $this->assertSame([], $attributes); + + $attributes = ['class' => ['test', 'test2', 'test3']]; + Html::removeCssClass($attributes, 'test2'); + $this->assertSame(['class' => ['test', 2 => 'test3']], $attributes); + Html::removeCssClass($attributes, 'test'); + Html::removeCssClass($attributes, 'test3'); + $this->assertSame([], $attributes); + + $attributes = [ 'class' => 'test test1 test2', ]; - Html::removeCssClass($options, ['test1', 'test2']); - $this->assertSame(['class' => 'test'], $options); + Html::removeCssClass($attributes, ['test1', 'test2']); + $this->assertSame(['class' => 'test'], $attributes); } public function testCssStyleFromArray(): void @@ -1154,56 +1154,56 @@ public function testCssStyleToArray(): void public function testAddCssStyle(): void { - $options = ['style' => 'width: 100px; height: 200px;']; - Html::addCssStyle($options, 'width: 110px; color: red;'); - $this->assertSame('width: 110px; height: 200px; color: red;', $options['style']); + $attributes = ['style' => 'width: 100px; height: 200px;']; + Html::addCssStyle($attributes, 'width: 110px; color: red;'); + $this->assertSame('width: 110px; height: 200px; color: red;', $attributes['style']); - $options = ['style' => 'width: 100px; height: 200px;']; - Html::addCssStyle($options, ['width' => '110px', 'color' => 'red']); - $this->assertSame('width: 110px; height: 200px; color: red;', $options['style']); + $attributes = ['style' => 'width: 100px; height: 200px;']; + Html::addCssStyle($attributes, ['width' => '110px', 'color' => 'red']); + $this->assertSame('width: 110px; height: 200px; color: red;', $attributes['style']); - $options = ['style' => 'width: 100px; height: 200px;']; - Html::addCssStyle($options, 'width: 110px; color: red;', false); - $this->assertSame('width: 100px; height: 200px; color: red;', $options['style']); + $attributes = ['style' => 'width: 100px; height: 200px;']; + Html::addCssStyle($attributes, 'width: 110px; color: red;', false); + $this->assertSame('width: 100px; height: 200px; color: red;', $attributes['style']); - $options = []; - Html::addCssStyle($options, 'width: 110px; color: red;'); - $this->assertSame('width: 110px; color: red;', $options['style']); + $attributes = []; + Html::addCssStyle($attributes, 'width: 110px; color: red;'); + $this->assertSame('width: 110px; color: red;', $attributes['style']); - $options = []; - Html::addCssStyle($options, 'width: 110px; color: red;', false); - $this->assertSame('width: 110px; color: red;', $options['style']); + $attributes = []; + Html::addCssStyle($attributes, 'width: 110px; color: red;', false); + $this->assertSame('width: 110px; color: red;', $attributes['style']); - $options = [ + $attributes = [ 'style' => [ 'width' => '100px', ], ]; - Html::addCssStyle($options, ['color' => 'red'], false); - $this->assertSame('width: 100px; color: red;', $options['style']); + Html::addCssStyle($attributes, ['color' => 'red'], false); + $this->assertSame('width: 100px; color: red;', $attributes['style']); } public function testRemoveCssStyle(): void { - $options = ['style' => 'width: 110px; height: 200px; color: red;']; - Html::removeCssStyle($options, 'width'); - $this->assertSame('height: 200px; color: red;', $options['style']); - Html::removeCssStyle($options, ['height']); - $this->assertSame('color: red;', $options['style']); - Html::removeCssStyle($options, ['color', 'background']); - $this->assertNull($options['style']); - - $options = []; - Html::removeCssStyle($options, ['color', 'background']); - $this->assertNotTrue(array_key_exists('style', $options)); - $options = [ + $attributes = ['style' => 'width: 110px; height: 200px; color: red;']; + Html::removeCssStyle($attributes, 'width'); + $this->assertSame('height: 200px; color: red;', $attributes['style']); + Html::removeCssStyle($attributes, ['height']); + $this->assertSame('color: red;', $attributes['style']); + Html::removeCssStyle($attributes, ['color', 'background']); + $this->assertNull($attributes['style']); + + $attributes = []; + Html::removeCssStyle($attributes, ['color', 'background']); + $this->assertNotTrue(array_key_exists('style', $attributes)); + $attributes = [ 'style' => [ 'color' => 'red', 'width' => '100px', ], ]; - Html::removeCssStyle($options, ['color']); - $this->assertSame('width: 100px;', $options['style']); + Html::removeCssStyle($attributes, ['color']); + $this->assertSame('width: 100px;', $attributes['style']); } public static function dataNormalizeRegexpPattern(): array From b52676ed09e1fb3bea46a67397952a012a1834dd Mon Sep 17 00:00:00 2001 From: Sergei Predvoditelev Date: Sun, 15 Mar 2026 19:58:20 +0300 Subject: [PATCH 2/2] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/Html.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Html.php b/src/Html.php index 0c6048d..b3e71a9 100644 --- a/src/Html.php +++ b/src/Html.php @@ -1815,7 +1815,7 @@ public static function removeCssClass(array &$attributes, string|array $class): * @param array $attributes The HTML attributes to be modified. * @param string|string[] $style The new style string (e.g. `'width: 100px; height: 200px'`) or array * (e.g. `['width' => '100px', 'height' => '200px']`). - * @param bool $overwrite Whether to overwrite existing CSS properties if the new style contain them too. + * @param bool $overwrite Whether to overwrite existing CSS properties if the new style contains them too. * * @psalm-param array|string $style */