Add Text alias for StringText with usage example

- Introduced `StringText` class for MariaDB TEXT strings, enforcing a maximum length of 65,535 characters.
- Added `fromString` and `tryFromString` methods, returning `Undefined` for inputs exceeding the length limit.
- Created alias `Text` as a readonly extension of `StringText`.
- Updated `Usage` examples to demonstrate `StringText` and `Text` behavior.
- Included detailed unit tests to validate boundaries, exception handling, alias behavior, and `Undefined` returns for invalid cases.

Author: georgedeploy

src/String/Alias/Text.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String\Alias;
+
+use PhpTypedValues\String\MariaDb\StringText;
+
+/**
+ * @psalm-immutable
+ */
+readonly class Text extends StringText
+{
+}

src/String/MariaDb/StringText.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\String\MariaDb;
+
+use PhpTypedValues\Abstract\String\StrType;
+use PhpTypedValues\Exception\StringTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+use function mb_strlen;
+
+/**
+ * Database TEXT string.
+ *
+ * MySQL/MariaDB TEXT: up to 65,535 characters.
+ *
+ * Example "Lorem ipsum ..." (any string, including empty, length <= 65,535)
+ *
+ * @psalm-immutable
+ */
+readonly class StringText extends StrType
+{
+    protected string $value;
+
+    /**
+     * @throws StringTypeException
+     */
+    public function __construct(string $value)
+    {
+        if (mb_strlen($value) > 65535) {
+            throw new StringTypeException('String is too long, max 65535 chars allowed');
+        }
+
+        $this->value = $value;
+    }
+
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    /**
+     * @throws StringTypeException
+     */
+    public static function fromString(string $value): static
+    {
+        return new static($value);
+    }
+
+    public function value(): string
+    {
+        return $this->value;
+    }
+}

src/Usage/String.php

@@ -8,9 +8,11 @@
 use PhpTypedValues\String\Alias\NonEmptyStr;
 use PhpTypedValues\String\Alias\Str;
 use PhpTypedValues\String\Alias\StrType;
+use PhpTypedValues\String\Alias\Text;
 use PhpTypedValues\String\Alias\Url;
 use PhpTypedValues\String\Json;
 use PhpTypedValues\String\MariaDb\StringDecimal;
+use PhpTypedValues\String\MariaDb\StringText;
 use PhpTypedValues\String\MariaDb\StringVarChar255;
 use PhpTypedValues\String\StringCountryCode;
 use PhpTypedValues\String\StringEmail;
@@ -45,6 +47,14 @@
 echo StringUuidV7::tryFromString('01890f2a-5bcd-7def-8abc-1234567890ab')->toString() . \PHP_EOL;
 echo StringVarChar255::tryFromString('hi')->toString() . \PHP_EOL;
 
+// MariaDb TEXT
+echo Text::fromString('lorem ipsum')->toString() . \PHP_EOL;
+echo StringText::fromString('lorem ipsum')->toString() . \PHP_EOL;
+$text = StringText::tryFromString(str_repeat('a', 10));
+if (!($text instanceof Undefined)) {
+    echo $text->toString() . \PHP_EOL;
+}
+
 // JSON
 echo json_encode(JsonStr::fromString('{"a": 1, "b": "hi"}')->toArray(), \JSON_THROW_ON_ERROR) . \PHP_EOL;
 echo json_encode(Json::fromString('{"a": 1}')->toObject(), \JSON_THROW_ON_ERROR) . \PHP_EOL;

tests/Unit/String/MariaDb/StringText/StringTextTest.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Exception\StringTypeException;
+use PhpTypedValues\String\Alias\Text;
+use PhpTypedValues\String\MariaDb\StringText;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('accepts empty string and preserves value/toString', function (): void {
+    $s = new StringText('');
+    expect($s->value())->toBe('')
+        ->and($s->toString())->toBe('')
+        ->and((string) $s)->toBe('');
+});
+
+it('accepts 65535 ASCII characters (boundary) and preserves value', function (): void {
+    $str = str_repeat('x', 65535);
+    $s = StringText::fromString($str);
+    expect($s->value())->toBe($str)
+        ->and($s->toString())->toBe($str);
+});
+
+it('throws on 65536 ASCII characters (above boundary)', function (): void {
+    $str = str_repeat('y', 65536);
+    expect(fn() => new StringText($str))
+        ->toThrow(StringTypeException::class, 'String is too long, max 65535 chars allowed');
+});
+
+it('accepts 65535 multibyte characters (emoji) counted by mb_strlen', function (): void {
+    $str = str_repeat('🙂', 65535);
+    $s = new StringText($str);
+    expect($s->value())->toBe($str)
+        ->and($s->toString())->toBe($str);
+});
+
+it('throws on 65536 multibyte characters (emoji)', function (): void {
+    $str = str_repeat('🙂', 65536);
+    expect(fn() => StringText::fromString($str))
+        ->toThrow(StringTypeException::class, 'String is too long, max 65535 chars allowed');
+});
+
+it('StringText::tryFromString returns value when length <= 65535 and Undefined when > 65535', function (): void {
+    $ok = StringText::tryFromString(str_repeat('a', 10));
+    $tooLong = StringText::tryFromString(str_repeat('b', 65536));
+
+    expect($ok)
+        ->toBeInstanceOf(StringText::class)
+        ->and($ok->value())
+        ->toBe(str_repeat('a', 10))
+        ->and($tooLong)
+        ->toBeInstanceOf(Undefined::class);
+});
+
+it('Alias Text behaves the same as StringText', function (): void {
+    $alias = Text::fromString('alias');
+    expect($alias->value())->toBe('alias');
+});