Start 4.0.0

CHANGELOG.md

@@ -1,8 +1,8 @@
 # Yii HTML Change Log
 
-## 3.13.1 under development
+## 4.0.0 under development
 
-- no changes in this release.
+- Chg #221: Throw `LogicException` in `Tag::id()` when id is empty string (@razvbir)
 
 ## 3.13.0 March 13, 2026
 

UPGRADE.md

@@ -0,0 +1,13 @@
+# Upgrading Instructions for Yii HTML
+
+This file contains the upgrade notes. These notes highlight changes that could break your
+application when you upgrade the package from one version to another.
+
+> **Important!** The following upgrading instructions are cumulative. That is, if you want
+> to upgrade from version A to version C and there is version B between A and C, you need
+> to follow the instructions for both A and B.
+
+## Upgrade from 3.x
+
+- `Tag::id()` now throws `LogicException` when an empty string is passed. Check your code for places where you call 
+  `Tag::id()` and make sure you are not passing an empty string.

src/Tag/Base/Tag.php

@@ -5,6 +5,7 @@
 namespace Yiisoft\Html\Tag\Base;
 
 use BackedEnum;
+use LogicException;
 use Yiisoft\Html\Html;
 use Yiisoft\Html\NoEncodeStringableInterface;
 
@@ -73,12 +74,17 @@ final public function attribute(string $name, mixed $value): static
     /**
      * Set tag ID.
      *
-     * @param string|null $id Tag ID.
+     * @param string|null $id Non-empty tag ID.
      *
      * @psalm-param non-empty-string|null $id
      */
     final public function id(?string $id): static
     {
+        /** @psalm-suppress TypeDoesNotContainType */
+        if ($id === '') {
+            throw new LogicException('The tag id cannot be an empty string.');
+        }
+
         $new = clone $this;
         $new->attributes['id'] = $id;
         return $new;

tests/Tag/Base/TagTest.php

@@ -4,6 +4,7 @@
 
 namespace Yiisoft\Html\Tests\Tag\Base;
 
+use LogicException;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
 use Yiisoft\Html\Tests\Objects\TestTag;
@@ -132,6 +133,13 @@ public function testId(string $expected, ?string $id): void
         $this->assertSame($expected, (string) (new TestTag())->id($id));
     }
 
+    public function testIdEmptyString(): void
+    {
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('The tag id cannot be an empty string.');
+        (new TestTag())->id('');
+    }
+
     public static function dataAddClass(): array
     {
         return [