Deep analysis and fixes for StringAssertions: corrected PHPDoc @param types, fixed @return types, added @var assertions for Psalm type safety

Author: k2gl

src/Traits/StringAssertions.php

@@ -23,10 +23,10 @@ trait StringAssertions
      * fact('abc123')->matchesRegularExpression('/^[a-z]+\d+$/'); // Passes
      * fact('123abc')->matchesRegularExpression('/^[a-z]+\d+$/'); // Fails
      *
-     * @param non-empty-string $pattern The regular expression pattern to match against.
-     * @param string $message Optional custom error message.
-     *
-     * @return self|fluentAssertions Enables fluent chaining of assertion methods.
+      * @param string $pattern The regular expression pattern to match against.
+      * @param string $message Optional custom error message.
+      *
+      * @return self Enables fluent chaining of assertion methods.
      */
     public function matchesRegularExpression(string $pattern, string $message = ''): self
     {
@@ -44,10 +44,10 @@ public function matchesRegularExpression(string $pattern, string $message = ''):
      * fact('123abc')->notMatchesRegularExpression('/^[a-z]+\d+$/'); // Passes
      * fact('abc123')->notMatchesRegularExpression('/^[a-z]+\d+$/'); // Fails
      *
-     * @param non-empty-string $pattern The regular expression pattern that should not match.
-     * @param string $message Optional custom error message.
-     *
-     * @return self|fluentAssertions Enables fluent chaining of assertion methods.
+      * @param string $pattern The regular expression pattern that should not match.
+      * @param string $message Optional custom error message.
+      *
+      * @return self Enables fluent chaining of assertion methods.
      */
     public function notMatchesRegularExpression(string $pattern, string $message = ''): self
     {
@@ -69,10 +69,10 @@ public function notMatchesRegularExpression(string $pattern, string $message = '
      * fact('hello world')->containsString('world'); // Passes
      * fact('hello world')->containsString('foo'); // Fails
      *
-     * @param non-empty-string $string The substring to search for.
-     * @param string $message Optional custom error message.
-     *
-     * @return self|fluentAssertions Enables fluent chaining of assertion methods.
+      * @param string $string The substring to search for.
+      * @param string $message Optional custom error message.
+      *
+      * @return self Enables fluent chaining of assertion methods.
      */
     public function containsString(string $string, string $message = ''): self
     {
@@ -160,18 +160,19 @@ public function notContainsStringIgnoringCase(string $string, string $message =
       * @param string $prefix The prefix to check for (must not be empty).
       * @param string $message Optional custom error message.
       *
-      * @return self|fluentAssertions Enables fluent chaining of assertion methods.
-      *
-      * Example usage:
-      * fact('hello world')->startsWith('hello'); // Passes
-      * fact('world hello')->startsWith('hello'); // Fails
-      */
-    public function startsWith(string $prefix, string $message = ''): self
+       * @return self Enables fluent chaining of assertion methods.
+       *
+       * Example usage:
+       * fact('hello world')->startsWith('hello'); // Passes
+       * fact('world hello')->startsWith('hello'); // Fails
+       */
+     public function startsWith(string $prefix, string $message = ''): self
     {
         if (strlen($prefix) === 0) {
             Assert::fail('Prefix cannot be an empty string.');
         }
 
+        /** @var non-empty-string $prefix */
         Assert::assertStringStartsWith($prefix, $this->variable, $message);
 
         return $this;
@@ -185,17 +186,19 @@ public function startsWith(string $prefix, string $message = ''): self
       * @param string $suffix The suffix to check for (must not be empty).
       * @param string $message Optional custom error message.
       *
-      * @return self|fluentAssertions Enables fluent chaining of assertion methods.
-      *
-      * Example usage:
-      * fact('file.txt')->endsWith('.txt'); // Passes
-      * fact('txt.file')->endsWith('.txt'); // Fails
-      */
-    public function endsWith(string $suffix, string $message = ''): self
+       * @return self Enables fluent chaining of assertion methods.
+       *
+       * Example usage:
+       * fact('file.txt')->endsWith('.txt'); // Passes
+       * fact('txt.file')->endsWith('.txt'); // Fails
+       */
+     public function endsWith(string $suffix, string $message = ''): self
     {
         if (strlen($suffix) === 0) {
             Assert::fail('Suffix cannot be an empty string.');
         }
+
+        /** @var non-empty-string $suffix */
         Assert::assertStringEndsWith($suffix, $this->variable, $message);
 
         return $this;
@@ -205,40 +208,40 @@ public function endsWith(string $suffix, string $message = ''): self
 
     // region Length Methods
 
-    /**
-     * Asserts that a string has a specific length.
-     *
-     * This method checks if the length of the actual string equals the expected length.
-     *
-     * @param int $length The expected length.
-     * @param string $message Optional custom error message.
-     *
-     * @return self|fluentAssertions Enables fluent chaining of assertion methods.
-     *
-     * Example usage:
-     * fact('abc')->hasLength(3); // Passes
-     * fact('abcd')->hasLength(3); // Fails
-     */
+     /**
+      * Asserts that a string has a specific length.
+      *
+      * This method checks if the length of the actual string equals the expected length.
+      *
+      * @param int $length The expected length.
+      * @param string $message Optional custom error message.
+      *
+      * @return self Enables fluent chaining of assertion methods.
+      *
+      * Example usage:
+      * fact('abc')->hasLength(3); // Passes
+      * fact('abcd')->hasLength(3); // Fails
+      */
     public function hasLength(int $length, string $message = ''): self
     {
         Assert::assertEquals($length, strlen($this->variable), $message);
 
         return $this;
     }
 
-    /**
-     * Asserts that a string is empty.
-     *
-     * This method checks if the actual value is an empty string.
-     *
-     * @param string $message Optional custom error message.
-     *
-     * @return self|fluentAssertions Enables fluent chaining of assertion methods.
-     *
-     * Example usage:
-     * fact('')->isEmptyString(); // Passes
-     * fact('hello')->isEmptyString(); // Fails
-     */
+     /**
+      * Asserts that a string is empty.
+      *
+      * This method checks if the actual value is an empty string.
+      *
+      * @param string $message Optional custom error message.
+      *
+      * @return self Enables fluent chaining of assertion methods.
+      *
+      * Example usage:
+      * fact('')->isEmptyString(); // Passes
+      * fact('hello')->isEmptyString(); // Fails
+      */
     public function isEmptyString(string $message = ''): self
     {
         Assert::assertEmpty($this->variable, $message);