Add tryFromString method to string types with tests and usage updates

georgedeploy · georgedeploy · commit db1e98bbdf15 · 2025-12-07T16:17:22.000+01:00
- Implemented `tryFromString` in `StringNonEmpty`, `StringStandard`, `StringUuidV4`, `StringUuidV7`, `Json`, and `StringVarChar255` to return `Undefined` for invalid input.
- Updated relevant interfaces and refactored exception handling for string parsing logic.
- Added comprehensive unit tests for valid and invalid cases.
- Modified `composer.json` scripts and `Usage` examples to include `tryFromString` methods.
diff --git a/composer.json b/composer.json
@@ -58,6 +58,9 @@
     "test": [
       "./vendor/bin/pest"
     ],
+    "usage": [
+      "php ./src/Usage/AllTypes.php"
+    ],
     "type": [
       "./vendor/bin/pest --type-coverage --min=100 --do-not-cache-result"
     ],
diff --git a/src/Abstract/String/StrTypeInterface.php b/src/Abstract/String/StrTypeInterface.php
@@ -4,6 +4,8 @@
 
 namespace PhpTypedValues\Abstract\String;
 
+use PhpTypedValues\Undefined\Alias\Undefined;
+
 /**
  * @psalm-immutable
  */
@@ -13,6 +15,8 @@ public function value(): string;
 
     public static function fromString(string $value): static;
 
+    public static function tryFromString(string $value): static|Undefined;
+
     public function toString(): string;
 
     public function __toString(): string;
diff --git a/src/String/Json.php b/src/String/Json.php
@@ -9,6 +9,8 @@
 use JsonException;
 use PhpTypedValues\Abstract\String\StrType;
 use PhpTypedValues\Exception\JsonStringTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 use function json_decode;
 use function sprintf;
@@ -42,6 +44,15 @@ public static function fromString(string $value): static
         return new static($value);
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     public function value(): string
     {
         return $this->value;
@@ -52,7 +63,6 @@ public function value(): string
      */
     public function toObject(): object
     {
-        // Use named arguments and omit depth literal to avoid integer-mutation issues
         return json_decode(json: $this->value, associative: false, flags: JSON_THROW_ON_ERROR);
     }
 
@@ -61,7 +71,6 @@ public function toObject(): object
      */
     public function toArray(): array
     {
-        // Use named arguments and omit depth literal to avoid integer-mutation issues
         return json_decode(json: $this->value, associative: true, flags: JSON_THROW_ON_ERROR);
     }
 
diff --git a/src/String/MariaDb/StringVarChar255.php b/src/String/MariaDb/StringVarChar255.php
@@ -6,6 +6,8 @@
 
 use PhpTypedValues\Abstract\String\StrType;
 use PhpTypedValues\Exception\StringTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
  * Database VARCHAR(255) string.
@@ -30,6 +32,15 @@ public function __construct(string $value)
         $this->value = $value;
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     /**
      * @throws StringTypeException
      */
diff --git a/src/String/StringNonEmpty.php b/src/String/StringNonEmpty.php
@@ -6,6 +6,8 @@
 
 use PhpTypedValues\Abstract\String\StrType;
 use PhpTypedValues\Exception\StringTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 use function sprintf;
 
@@ -33,6 +35,15 @@ public function __construct(string $value)
         $this->value = $value;
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     /**
      * @throws StringTypeException
      */
diff --git a/src/String/StringStandard.php b/src/String/StringStandard.php
@@ -5,6 +5,7 @@
 namespace PhpTypedValues\String;
 
 use PhpTypedValues\Abstract\String\StrType;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
  * Represents any PHP string.
@@ -22,6 +23,11 @@ public function __construct(string $value)
         $this->value = $value;
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        return static::fromString($value);
+    }
+
     public static function fromString(string $value): static
     {
         return new static($value);
diff --git a/src/String/StringUuidV4.php b/src/String/StringUuidV4.php
@@ -5,7 +5,9 @@
 namespace PhpTypedValues\String;
 
 use PhpTypedValues\Abstract\String\StrType;
+use PhpTypedValues\Exception\TypeException;
 use PhpTypedValues\Exception\UuidStringTypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 use function preg_match;
 use function sprintf;
@@ -45,6 +47,15 @@ public function __construct(string $value)
         $this->value = $normalized;
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     /**
      * @throws UuidStringTypeException
      */
diff --git a/src/String/StringUuidV7.php b/src/String/StringUuidV7.php
@@ -5,7 +5,9 @@
 namespace PhpTypedValues\String;
 
 use PhpTypedValues\Abstract\String\StrType;
+use PhpTypedValues\Exception\TypeException;
 use PhpTypedValues\Exception\UuidStringTypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 use function preg_match;
 use function sprintf;
@@ -45,6 +47,15 @@ public function __construct(string $value)
         $this->value = $normalized;
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     /**
      * @throws UuidStringTypeException
      */
diff --git a/src/Usage/String.php b/src/Usage/String.php
@@ -5,8 +5,11 @@
 use PhpTypedValues\String\Alias\Str;
 use PhpTypedValues\String\Alias\StrType;
 use PhpTypedValues\String\Json;
+use PhpTypedValues\String\MariaDb\StringVarChar255;
 use PhpTypedValues\String\StringNonEmpty;
 use PhpTypedValues\String\StringStandard;
+use PhpTypedValues\String\StringUuidV4;
+use PhpTypedValues\String\StringUuidV7;
 
 /**
  * String.
@@ -18,10 +21,16 @@
 echo NonEmptyStr::fromString('hi')->toString() . \PHP_EOL;
 echo StrType::fromString('hi')->toString() . \PHP_EOL;
 echo Str::fromString('hi')->toString() . \PHP_EOL;
+echo StringNonEmpty::tryFromString('hi')->toString() . \PHP_EOL;
+echo StringStandard::tryFromString('hi')->toString() . \PHP_EOL;
+echo StringUuidV4::tryFromString('550e8400-e29b-41d4-a716-446655440000')->toString() . \PHP_EOL;
+echo StringUuidV7::tryFromString('01890f2a-5bcd-7def-8abc-1234567890ab')->toString() . \PHP_EOL;
+echo StringVarChar255::tryFromString('hi')->toString() . \PHP_EOL;
 
 // JSON
-echo json_encode(JsonStr::fromString('{"a": 1, "b": "hi"}')->toArray(), \JSON_THROW_ON_ERROR);
-echo json_encode(Json::fromString('{"a": 1, "b": "hi"}')->toObject(), \JSON_THROW_ON_ERROR);
+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;
+echo Json::tryFromString('{}')->toString() . \PHP_EOL;
 
 /**
  * Artificial functions.
diff --git a/tests/Unit/String/Json/JsonTest.php b/tests/Unit/String/Json/JsonTest.php
@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\String\Json;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('Json::tryFromString returns value for valid JSON string', function (): void {
+    $json = '{"a":1}';
+    $v = Json::tryFromString($json);
+
+    expect($v)
+        ->toBeInstanceOf(Json::class)
+        ->and($v->value())
+        ->toBe($json);
+});
+
+it('Json::tryFromString returns Undefined for invalid JSON string', function (): void {
+    $u = Json::tryFromString('{invalid');
+
+    expect($u)->toBeInstanceOf(Undefined::class);
+});
+
+it('Json::toObject decodes valid JSON object and throws on invalid internal state', function (): void {
+    $jsonText = '{"a":1,"b":2}';
+    $j = Json::tryFromString($jsonText);
+
+    // success branch
+    \assert($j instanceof Json);
+    $obj = $j->toObject();
+    expect($obj)->toBeObject()
+        ->and($obj->a)->toBe(1)
+        ->and($obj->b)->toBe(2);
+});
+
+it('Json::toArray decodes valid JSON object as array and throws on invalid internal state', function (): void {
+    $jsonText = '{"x":10,"y":20}';
+    $j = Json::tryFromString($jsonText);
+    \assert($j instanceof Json);
+
+    // success branch
+    $arr = $j->toArray();
+    expect($arr)->toBeArray()
+        ->and($arr['x'])->toBe(10)
+        ->and($arr['y'])->toBe(20);
+});
diff --git a/tests/Unit/String/MariaDb/StringVarChar255Test.php b/tests/Unit/String/MariaDb/StringVarChar255Test.php
@@ -4,6 +4,7 @@
 
 use PhpTypedValues\Exception\StringTypeException;
 use PhpTypedValues\String\MariaDb\StringVarChar255;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 it('accepts empty string and preserves value', function (): void {
     $s = new StringVarChar255('');
@@ -36,3 +37,20 @@
     expect(fn() => StringVarChar255::fromString($str))
         ->toThrow(StringTypeException::class, 'String is too long, max 255 chars allowed');
 });
+
+it('StringVarChar255::tryFromString returns value when length <= 255', function (): void {
+    $short = str_repeat('a', 255);
+    $v = StringVarChar255::tryFromString($short);
+
+    expect($v)
+        ->toBeInstanceOf(StringVarChar255::class)
+        ->and($v->value())
+        ->toBe($short);
+});
+
+it('StringVarChar255::tryFromString returns Undefined when length > 255', function (): void {
+    $long = str_repeat('b', 256);
+    $u = StringVarChar255::tryFromString($long);
+
+    expect($u)->toBeInstanceOf(Undefined::class);
+});
diff --git a/tests/Unit/String/StringNonEmpty/StringNonEmptyTest.php b/tests/Unit/String/StringNonEmpty/StringNonEmptyTest.php
@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\String\StringNonEmpty;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('StringNonEmpty::tryFromString returns value for non-empty string', function (): void {
+    $v = StringNonEmpty::tryFromString('abc');
+
+    expect($v)
+        ->toBeInstanceOf(StringNonEmpty::class)
+        ->and($v->value())
+        ->toBe('abc');
+});
+
+it('StringNonEmpty::tryFromString returns Undefined for empty string', function (): void {
+    $u = StringNonEmpty::tryFromString('');
+
+    expect($u)->toBeInstanceOf(Undefined::class);
+});
diff --git a/tests/Unit/String/StringStandard/StringStandardTest.php b/tests/Unit/String/StringStandard/StringStandardTest.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\String\StringStandard;
+
+it('StringStandard::tryFromString returns instance for any string', function (): void {
+    $v = StringStandard::tryFromString('hello');
+
+    expect($v)
+        ->toBeInstanceOf(StringStandard::class)
+        ->and($v->value())
+        ->toBe('hello')
+        ->and($v->toString())
+        ->toBe('hello');
+});
diff --git a/tests/Unit/String/StringUuidV4/StringUuidV4Test.php b/tests/Unit/String/StringUuidV4/StringUuidV4Test.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\String\StringUuidV4;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('StringUuidV4::tryFromString returns value for valid UUID v4 (case-insensitive) and normalizes to lowercase', function (): void {
+    $input = '550E8400-E29B-41D4-A716-446655440000'; // uppercase
+    $v = StringUuidV4::tryFromString($input);
+
+    expect($v)
+        ->toBeInstanceOf(StringUuidV4::class)
+        ->and($v->value())
+        ->toBe(strtolower($input));
+});
+
+it('StringUuidV4::tryFromString returns Undefined for non-v4 or invalid UUID', function (): void {
+    // v1 example (13th char = 1), should fail for v4 type
+    $u1 = StringUuidV4::tryFromString('550e8400-e29b-11d4-a716-446655440000');
+    $u2 = StringUuidV4::tryFromString('not-a-uuid');
+
+    expect($u1)->toBeInstanceOf(Undefined::class)
+        ->and($u2)->toBeInstanceOf(Undefined::class);
+});
diff --git a/tests/Unit/String/StringUuidV7/StringUuidV7Test.php b/tests/Unit/String/StringUuidV7/StringUuidV7Test.php
@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\String\StringUuidV7;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('StringUuidV7::tryFromString returns value for valid UUID v7 (case-insensitive) and normalizes to lowercase', function (): void {
+    $input = '01890F2A-5BCD-7DEF-8ABC-1234567890AB'; // uppercase
+    $v = StringUuidV7::tryFromString($input);
+
+    expect($v)
+        ->toBeInstanceOf(StringUuidV7::class)
+        ->and($v->value())
+        ->toBe(strtolower($input));
+});
+
+it('StringUuidV7::tryFromString returns Undefined for non-v7 or invalid UUID', function (): void {
+    // v4-like example (13th char = 4), should fail for v7 type
+    $u1 = StringUuidV7::tryFromString('550e8400-e29b-41d4-a716-446655440000');
+    $u2 = StringUuidV7::tryFromString('not-a-uuid');
+
+    expect($u1)->toBeInstanceOf(Undefined::class)
+        ->and($u2)->toBeInstanceOf(Undefined::class);
+});

Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,8 @@`
`9`	`9`	`use JsonException;`
`10`	`10`	`use PhpTypedValues\Abstract\String\StrType;`
`11`	`11`	`use PhpTypedValues\Exception\JsonStringTypeException;`
	`12`	`+use PhpTypedValues\Exception\TypeException;`
	`13`	`+use PhpTypedValues\Undefined\Alias\Undefined;`
`12`	`14`
`13`	`15`	`use function json_decode;`
`14`	`16`	`use function sprintf;`
`@@ -42,6 +44,15 @@ public static function fromString(string $value): static`
`42`	`44`	`return new static($value);`
`43`	`45`	`}`
`44`	`46`
	`47`	`+ public static function tryFromString(string $value): static\|Undefined`
	`48`	`+ {`
	`49`	`+ try {`
	`50`	`+ return static::fromString($value);`
	`51`	`+ } catch (TypeException) {`
	`52`	`+ return Undefined::create();`
	`53`	`+ }`
	`54`	`+ }`
	`55`	`+`
`45`	`56`	`public function value(): string`
`46`	`57`	`{`
`47`	`58`	`return $this->value;`
`@@ -52,7 +63,6 @@ public function value(): string`
`52`	`63`	`*/`
`53`	`64`	`public function toObject(): object`
`54`	`65`	`{`
`55`		`- // Use named arguments and omit depth literal to avoid integer-mutation issues`
`56`	`66`	`return json_decode(json: $this->value, associative: false, flags: JSON_THROW_ON_ERROR);`
`57`	`67`	`}`
`58`	`68`
`@@ -61,7 +71,6 @@ public function toObject(): object`
`61`	`71`	`*/`
`62`	`72`	`public function toArray(): array`
`63`	`73`	`{`
`64`		`- // Use named arguments and omit depth literal to avoid integer-mutation issues`
`65`	`74`	`return json_decode(json: $this->value, associative: true, flags: JSON_THROW_ON_ERROR);`
`66`	`75`	`}`
`67`	`76`