From 3a06b110974eabe4553d1068698198abf34e46ae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C4=83zvan=20Biri=C8=99an?= <razvan.birisan@pm.me>
Date: Wed, 11 Mar 2026 22:26:35 +0200
Subject: [PATCH 1/2] Add exception on pass empty string to Tag::id() (#221)

Remove meaningless @psalm-param tag from Tag::id docblock

Add CHANGELOG message
---
 CHANGELOG.md               | 1 +
 src/Tag/Base/Tag.php       | 7 +++++--
 tests/Tag/Base/TagTest.php | 7 +++++++
 3 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e291fb7..789e268f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@
 - Enh #261: Enhance `RadioList::addRadioWrapClass()` method for cleaner class addition (@vjik)
 - Enh #263: Explicitly import classes and constants in "use" section (@mspirkov)
 - Chg #243: Deprecate static constructors such as `TagName::tag()` in favor of `new TagName()` (@razvbir)
+- Chg #221: Throw `LogicException` in `Tag::id()` when id is empty string (@razvbir)
 
 ## 3.12.0 December 13, 2025
 
diff --git a/src/Tag/Base/Tag.php b/src/Tag/Base/Tag.php
index 942da0eb..7d146ae7 100644
--- a/src/Tag/Base/Tag.php
+++ b/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;
 
@@ -74,11 +75,13 @@ final public function attribute(string $name, mixed $value): static
      * Set tag ID.
      *
      * @param string|null $id Tag ID.
-     *
-     * @psalm-param non-empty-string|null $id
      */
     final public function id(?string $id): static
     {
+        if ($id === '') {
+            throw new LogicException('The tag id cannot be an empty string.');
+        }
+
         $new = clone $this;
         $new->attributes['id'] = $id;
         return $new;
diff --git a/tests/Tag/Base/TagTest.php b/tests/Tag/Base/TagTest.php
index e0a3416f..0fed5e14 100644
--- a/tests/Tag/Base/TagTest.php
+++ b/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,12 @@ public function testId(string $expected, ?string $id): void
         $this->assertSame($expected, (string) (new TestTag())->id($id));
     }
 
+    public function testIdEmptyString(): void
+    {
+        $this->expectException(LogicException::class);
+        (new TestTag())->id('');
+    }
+
     public static function dataAddClass(): array
     {
         return [

From fe202b340e58bc8963ad83f879b4ff8f596c29c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C4=83zvan=20Biri=C8=99an?= <razvan.birisan@pm.me>
Date: Thu, 12 Mar 2026 14:51:41 +0200
Subject: [PATCH 2/2] Annotate id() to throw LogicException

Add @throws LogicException to Tag::id docblock.
Update TagTest to expect an empty-string id to throw
LogicException with message: The tag id cannot be
an empty string.
---
 src/Tag/Base/Tag.php       | 2 ++
 tests/Tag/Base/TagTest.php | 1 +
 2 files changed, 3 insertions(+)

diff --git a/src/Tag/Base/Tag.php b/src/Tag/Base/Tag.php
index 7d146ae7..f8dc389c 100644
--- a/src/Tag/Base/Tag.php
+++ b/src/Tag/Base/Tag.php
@@ -75,6 +75,8 @@ final public function attribute(string $name, mixed $value): static
      * Set tag ID.
      *
      * @param string|null $id Tag ID.
+     *
+     * @throws LogicException
      */
     final public function id(?string $id): static
     {
diff --git a/tests/Tag/Base/TagTest.php b/tests/Tag/Base/TagTest.php
index 0fed5e14..62ca4310 100644
--- a/tests/Tag/Base/TagTest.php
+++ b/tests/Tag/Base/TagTest.php
@@ -136,6 +136,7 @@ public function testId(string $expected, ?string $id): void
     public function testIdEmptyString(): void
     {
         $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('The tag id cannot be an empty string.');
         (new TestTag())->id('');
     }