Clarify psalm types for Html::generateId() and Tag::id() (#220)

vjik · web-flow · commit d5659fbf491d · 2024-10-18T09:49:11.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,8 @@
 
 ## 3.7.1 under development
 
-- no changes in this release.
+- Enh #220: Add `non-empty-string` psalm type of `Html::generateId()` method result (@vjik)
+- Enh #220: Add `non-empty-string|null` psalm type of `Tag::id()` method parameter (@vjik)
 
 ## 3.7.0 September 18, 2024
 
diff --git a/src/Html.php b/src/Html.php
@@ -155,6 +155,8 @@ final class Html
      * Returns an autogenerated sequential ID.
      *
      * @return string Autogenerated ID.
+     *
+     * @psalm-return non-empty-string
      */
     public static function generateId(string $prefix = 'i'): string
     {
diff --git a/src/Tag/Base/Tag.php b/src/Tag/Base/Tag.php
@@ -68,6 +68,8 @@ 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
     {
diff --git a/src/Tag/Input/Range.php b/src/Tag/Input/Range.php
@@ -24,6 +24,10 @@ final class Range extends InputTag
      */
     private string $outputTag = 'span';
     private array $outputAttributes = [];
+
+    /**
+     * @psalm-var non-empty-string|null
+     */
     private ?string $outputId = null;
 
     /**
@@ -111,7 +115,7 @@ protected function prepareAttributes(): void
         $this->attributes['type'] = 'range';
 
         if ($this->showOutput) {
-            $this->outputId = (string) ($this->outputAttributes['id'] ?? Html::generateId('rangeOutput'));
+            $this->fillOutputId();
             $this->attributes['oninput'] = 'document.getElementById("' . $this->outputId . '").innerHTML=this.value';
         }
     }
@@ -128,4 +132,13 @@ protected function after(): string
                 ->id($this->outputId)
                 ->render();
     }
+
+    /**
+     * @psalm-assert non-empty-string $this->outputId
+     */
+    private function fillOutputId(): void
+    {
+        $id = (string) ($this->outputAttributes['id'] ?? '');
+        $this->outputId = $id === '' ? Html::generateId('rangeOutput') : $id;
+    }
 }

Original file line number	Diff line number	Diff line change
`@@ -155,6 +155,8 @@ final class Html`
`155`	`155`	`* Returns an autogenerated sequential ID.`
`156`	`156`	`*`
`157`	`157`	`* @return string Autogenerated ID.`
	`158`	`+ *`
	`159`	`+ * @psalm-return non-empty-string`
`158`	`160`	`*/`
`159`	`161`	`public static function generateId(string $prefix = 'i'): string`
`160`	`162`	`{`
Original file line number	Diff line number	Diff line change
`@@ -68,6 +68,8 @@ final public function attribute(string $name, mixed $value): static`
`68`	`68`	`* Set tag ID.`
`69`	`69`	`*`
`70`	`70`	`* @param string\|null $id Tag ID.`
	`71`	`+ *`
	`72`	`+ * @psalm-param non-empty-string\|null $id`
`71`	`73`	`*/`
`72`	`74`	`final public function id(?string $id): static`
`73`	`75`	`{`