fix(str): add invariant to avoid unexpected errors when parsing an invalid UTF8 string

docs/component/str.md

@@ -53,7 +53,7 @@
 - [range](./../../src/Psl/Str/range.php#L41)
 - [repeat](./../../src/Psl/Str/repeat.php#L26)
 - [replace](./../../src/Psl/Str/replace.php#L15)
-- [replace_ci](./../../src/Psl/Str/replace_ci.php#L16)
+- [replace_ci](./../../src/Psl/Str/replace_ci.php#L20)
 - [replace_every](./../../src/Psl/Str/replace_every.php#L15)
 - [replace_every_ci](./../../src/Psl/Str/replace_every_ci.php#L15)
 - [reverse](./../../src/Psl/Str/reverse.php#L14)
@@ -69,9 +69,9 @@
 - [strip_prefix](./../../src/Psl/Str/strip_prefix.php#L13)
 - [strip_suffix](./../../src/Psl/Str/strip_suffix.php#L13)
 - [to_int](./../../src/Psl/Str/to_int.php#L12)
-- [trim](./../../src/Psl/Str/trim.php#L18)
-- [trim_left](./../../src/Psl/Str/trim_left.php#L18)
-- [trim_right](./../../src/Psl/Str/trim_right.php#L18)
+- [trim](./../../src/Psl/Str/trim.php#L22)
+- [trim_left](./../../src/Psl/Str/trim_left.php#L22)
+- [trim_right](./../../src/Psl/Str/trim_right.php#L22)
 - [truncate](./../../src/Psl/Str/truncate.php#L25)
 - [uppercase](./../../src/Psl/Str/uppercase.php#L14)
 - [width](./../../src/Psl/Str/width.php#L14)

src/Psl/Encoding/Base64/Internal/Base64.php

@@ -102,6 +102,8 @@ public static function decode(string $base64, bool $explicit_padding = true): st
         if ($explicit_padding && $base64_length % 4 !== 0) {
             throw new Exception\IncorrectPaddingException('The given base64 string has incorrect padding.');
         }
+
+        /** @psalm-suppress MissingThrowsDocblock */
         $base64 = Str\trim_right($base64, '=');
         $base64_length = Str\length($base64, encoding: Str\Encoding::ASCII_8BIT);
 

src/Psl/Str/replace_ci.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Str;
 
+use Psl;
+
 use function preg_quote;
 use function preg_split;
 
@@ -12,12 +14,16 @@
  * `$replacement` (case-insensitive).
  *
  * @pure
+ *
+ * @throws Psl\Exception\InvariantViolationException if $needle is not a valid UTF-8 string.
  */
 function replace_ci(string $haystack, string $needle, string $replacement, Encoding $encoding = Encoding::UTF_8): string
 {
     if ('' === $needle || null === search_ci($haystack, $needle, 0, $encoding)) {
         return $haystack;
     }
 
+    Psl\invariant(is_utf8($needle), 'Expected $needle to be a valid UTF-8 string.');
+
     return join(preg_split('{' . preg_quote($needle, '/') . '}iu', $haystack), $replacement);
 }

src/Psl/Str/trim.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Str;
 
+use Psl;
+
 use function preg_quote;
 use function preg_replace;
 
@@ -14,9 +16,13 @@
  * be stripped: space, tab, newline, carriage return, NUL byte, vertical tab.
  *
  * @pure
+ *
+ * @throws Psl\Exception\InvariantViolationException if $string is not a valid UTF-8 string.
  */
 function trim(string $string, ?string $char_mask = null): string
 {
+    Psl\invariant(is_utf8($string), 'Expected $string to be a valid UTF-8 string.');
+
     $char_mask ??= " \t\n\r\0\x0B\x0C\u{A0}\u{FEFF}";
     $char_mask   = preg_quote($char_mask, null);
 

src/Psl/Str/trim_left.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Str;
 
+use Psl;
+
 use function preg_quote;
 use function preg_replace;
 
@@ -14,9 +16,13 @@
  * be stripped: space, tab, newline, carriage return, NUL byte, vertical tab.
  *
  * @pure
+ *
+ * @throws Psl\Exception\InvariantViolationException if $string is not a valid UTF-8 string.
  */
 function trim_left(string $string, ?string $char_mask = null): string
 {
+    Psl\invariant(is_utf8($string), 'Expected $string to be a valid UTF-8 string.');
+
     $char_mask ??= " \t\n\r\0\x0B\x0C\u{A0}\u{FEFF}";
     $char_mask   = preg_quote($char_mask, null);
 

src/Psl/Str/trim_right.php

@@ -4,6 +4,8 @@
 
 namespace Psl\Str;
 
+use Psl;
+
 use function preg_quote;
 use function preg_replace;
 
@@ -14,9 +16,13 @@
  * be stripped: space, tab, newline, carriage return, NUL byte, vertical tab.
  *
  * @pure
+ *
+ * @throws Psl\Exception\InvariantViolationException if $string is not a valid UTF-8 string.
  */
 function trim_right(string $string, ?string $char_mask = null): string
 {
+    Psl\invariant(is_utf8($string), 'Expected $string to be a valid UTF-8 string.');
+
     $char_mask ??= " \t\n\r\0\x0B\x0C\u{A0}\u{FEFF}";
     $char_mask   = preg_quote($char_mask, null);
 

src/Psl/Type/Internal/LiteralScalarType.php

@@ -122,6 +122,7 @@ public function toString(): string
         }
 
         if (Type\float()->matches($value)) {
+            /** @psalm-suppress MissingThrowsDocblock */
             $string_representation = Str\trim_right(Str\format('%.14F', $value), '0');
             /** @psalm-suppress MissingThrowsDocblock */
             if (Str\ends_with($string_representation, '.')) {

src/Psl/Type/Internal/PositiveIntType.php

@@ -4,6 +4,7 @@
 
 namespace Psl\Type\Internal;
 
+use Psl\Exception\InvariantViolationException;
 use Psl\Str;
 use Psl\Type;
 use Psl\Type\Exception\AssertException;
@@ -47,8 +48,13 @@ public function coerce(mixed $value): int
                 return $int;
             }
 
-            $trimmed = Str\trim_left($str, '0');
-            $int     = Str\to_int($trimmed);
+            try {
+                $trimmed = Str\trim_left($str, '0');
+            } catch (InvariantViolationException $e) {
+                throw CoercionException::withValue($value, $this->toString(), $this->getTrace());
+            }
+
+            $int = Str\to_int($trimmed);
             if (null !== $int && $int > 0) {
                 return $int;
             }

tests/unit/Str/ReplaceCiTest.php

@@ -5,6 +5,7 @@
 namespace Psl\Tests\Unit\Str;
 
 use PHPUnit\Framework\TestCase;
+use Psl\Exception\InvariantViolationException;
 use Psl\Str;
 
 final class ReplaceCiTest extends TestCase
@@ -26,4 +27,36 @@ public function provideData(): array
             ['foo', 'foo', 'bar', 'baz'],
         ];
     }
+
+    /**
+     * @dataProvider provideBadUtf8Data
+     */
+    public function testBadUtf8(string $string, string $expectedException, string $expectedExceptionMessage): void
+    {
+        $this->expectException($expectedException);
+        $this->expectExceptionMessage($expectedExceptionMessage);
+
+        Str\replace_ci($string, $string, $string);
+    }
+
+    public function provideBadUtf8Data(): iterable
+    {
+        yield [
+            "\xc1\xbf",
+            InvariantViolationException::class,
+            'Expected $needle to be a valid UTF-8 string.',
+        ];
+
+        yield [
+            "\xe0\x81\xbf",
+            InvariantViolationException::class,
+            'Expected $needle to be a valid UTF-8 string.',
+        ];
+
+        yield [
+            "\xf0\x80\x81\xbf",
+            InvariantViolationException::class,
+            'Expected $needle to be a valid UTF-8 string.',
+        ];
+    }
 }

tests/unit/Str/TrimLeftTest.php

@@ -5,6 +5,7 @@
 namespace Psl\Tests\Unit\Str;
 
 use PHPUnit\Framework\TestCase;
+use Psl;
 use Psl\Str;
 
 final class TrimLeftTest extends TestCase
@@ -47,4 +48,36 @@ public function provideData(): array
             ],
         ];
     }
+
+    /**
+     * @dataProvider provideBadUtf8Data
+     */
+    public function testBadUtf8(string $string, string $expectedException, string $expectedExceptionMessage): void
+    {
+        $this->expectException($expectedException);
+        $this->expectExceptionMessage($expectedExceptionMessage);
+
+        Str\trim_left($string);
+    }
+
+    public function provideBadUtf8Data(): iterable
+    {
+        yield [
+            "\xc1\xbf",
+            Psl\Exception\InvariantViolationException::class,
+            'Expected $string to be a valid UTF-8 string.',
+        ];
+
+        yield [
+            "\xe0\x81\xbf",
+            Psl\Exception\InvariantViolationException::class,
+            'Expected $string to be a valid UTF-8 string.',
+        ];
+
+        yield [
+            "\xf0\x80\x81\xbf",
+            Psl\Exception\InvariantViolationException::class,
+            'Expected $string to be a valid UTF-8 string.',
+        ];
+    }
 }

tests/unit/Str/TrimRightTest.php

@@ -5,6 +5,7 @@
 namespace Psl\Tests\Unit\Str;
 
 use PHPUnit\Framework\TestCase;
+use Psl;
 use Psl\Str;
 
 final class TrimRightTest extends TestCase
@@ -57,4 +58,36 @@ public function provideData(): array
             ],
         ];
     }
+
+    /**
+     * @dataProvider provideBadUtf8Data
+     */
+    public function testBadUtf8(string $string, string $expectedException, string $expectedExceptionMessage): void
+    {
+        $this->expectException($expectedException);
+        $this->expectExceptionMessage($expectedExceptionMessage);
+
+        Str\trim_right($string);
+    }
+
+    public function provideBadUtf8Data(): iterable
+    {
+        yield [
+            "\xc1\xbf",
+            Psl\Exception\InvariantViolationException::class,
+            'Expected $string to be a valid UTF-8 string.',
+        ];
+
+        yield [
+            "\xe0\x81\xbf",
+            Psl\Exception\InvariantViolationException::class,
+            'Expected $string to be a valid UTF-8 string.',
+        ];
+
+        yield [
+            "\xf0\x80\x81\xbf",
+            Psl\Exception\InvariantViolationException::class,
+            'Expected $string to be a valid UTF-8 string.',
+        ];
+    }
 }

tests/unit/Str/TrimTest.php

@@ -5,6 +5,7 @@
 namespace Psl\Tests\Unit\Str;
 
 use PHPUnit\Framework\TestCase;
+use Psl;
 use Psl\Str;
 
 final class TrimTest extends TestCase
@@ -52,4 +53,36 @@ public function provideData(): array
             ],
         ];
     }
+
+    /**
+     * @dataProvider provideBadUtf8Data
+     */
+    public function testBadUtf8(string $string, string $expectedException, string $expectedExceptionMessage): void
+    {
+        $this->expectException($expectedException);
+        $this->expectExceptionMessage($expectedExceptionMessage);
+
+        Str\trim($string);
+    }
+
+    public function provideBadUtf8Data(): iterable
+    {
+        yield [
+            "\xc1\xbf",
+            Psl\Exception\InvariantViolationException::class,
+            'Expected $string to be a valid UTF-8 string.',
+        ];
+
+        yield [
+            "\xe0\x81\xbf",
+            Psl\Exception\InvariantViolationException::class,
+            'Expected $string to be a valid UTF-8 string.',
+        ];
+
+        yield [
+            "\xf0\x80\x81\xbf",
+            Psl\Exception\InvariantViolationException::class,
+            'Expected $string to be a valid UTF-8 string.',
+        ];
+    }
 }

tests/unit/Type/PositiveIntTypeTest.php

@@ -59,6 +59,7 @@ public function getInvalidCoercions(): iterable
         yield [$this->stringable('-9223372036854775809')];
         yield ['0xFF'];
         yield ['-0xFF'];
+        yield ["\xc1\xbf"];
         yield [''];
     }