Fix #279: Add support for conditional CSS classes in Html::addCssClass()

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 4.2.1 under development
 
 - New #278: Add dedicated classes for missing HTML tags (@Mister-42)
+- New #279: Add support for conditional CSS classes in `Html::addCssClass()` (@Mister-42)
 
 ## 4.2.0 June 05, 2026
 

src/Html.php

@@ -2405,11 +2405,11 @@
                     /** @psalm-var array<array-key, scalar[]|string|Stringable|null> $value */
                     foreach ($value as $n => $v) {
                         if (!isset($v)) {
                             continue;
                         }
                         $fullName = "$name-$n";
                         if (in_array($fullName, self::ATTRIBUTES_WITH_CONCATENATED_VALUES, true)) {
                             $html .= self::renderAttribute(
                                 $fullName,
                                 self::encodeAttribute(
                                     is_array($v) ? implode(' ', $v) : $v,
@@ -2462,10 +2462,10 @@
      *
      * @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.
+     * @param (BackedEnum|null|bool|string)[]|BackedEnum|string|null $class The CSS class(es) to be added. Null values will
+     * be ignored. When passing an array, use a boolean value to conditionally include/exclude a class by its key.
      *
-     * @psalm-param BackedEnum|string|array<array-key,BackedEnum|string|null>|null $class
+     * @psalm-param BackedEnum|string|array<array-key,BackedEnum|bool|string|null>|null $class
      */
     public static function addCssClass(array &$attributes, BackedEnum|array|string|null $class): void
     {
@@ -2483,12 +2483,23 @@
         if (is_array($class)) {
             $filteredClass = [];
             foreach ($class as $key => $value) {
+                if (is_bool($value)) {
+                    if ($value && is_string($key)) {
+                        $filteredClass[] = $key;
+                    }
+                    continue;
+                }
+
                 if ($value instanceof BackedEnum) {
                     $value = is_string($value->value) ? $value->value : null;
                 }
 
                 if ($value !== null) {
-                    $filteredClass[$key] = $value;
+                    if (is_int($key) && array_key_exists($key, $filteredClass)) {
+                        $filteredClass[] = $value;
+                    } else {
+                        $filteredClass[$key] = $value;
+                    }
                 }
             }
             if (empty($filteredClass)) {

tests/HtmlTest.php

@@ -1049,6 +1049,17 @@ public static function dataAddCssClass(): array
             16 => [['id' => 'w2', 'class' => 't1'], ['id' => 'w2'], 't1'],
             17 => [['id' => 'w2', 'class' => ['t3', 2 => 't4']], ['id' => 'w2'], ['t3', null, 't4']],
             18 => [['id' => 'w2', 'class' => ['t3', 2 => 't4']], ['id' => 'w2'], ['t3', null, 't4', null]],
+            19 => [['class' => ['btn-active']], [], ['btn-active' => true]],
+            20 => [[], [], ['btn-active' => false]],
+            21 => [['class' => ['btn', 'btn-active']], [], ['btn', 'btn-active' => true]],
+            22 => [['class' => ['btn']], [], ['btn', 'btn-active' => false]],
+            23 => [['class' => ['btn', 'btn-active']], ['class' => 'btn'], ['btn-active' => true]],
+            24 => [['class' => 'btn'], ['class' => 'btn'], ['btn-active' => false]],
+            25 => [['class' => ['btn', 'btn-active']], ['class' => 'btn'], ['btn-active' => true, 'hidden' => false]],
+            26 => [['class' => ['btn']], ['class' => 'btn'], ['btn' => true]],
+            27 => [['class' => ['persistent' => 'widget', 'btn', 'btn-active']], ['class' => ['persistent' => 'widget']], ['btn', 'btn-active' => true]],
+            28 => [['class' => ['persistent' => 'widget', 'btn-active', 'btn']], ['class' => ['persistent' => 'widget']], ['btn-active' => true, 'btn']],
+            29 => [['class' => ['persistent' => 'widget', 'btn-active', 'btn', 'btn-sm']], ['class' => ['persistent' => 'widget']], ['btn-active' => true, 'btn', 'btn-sm' => true]],
         ];
     }