Add tryFromString and tryFromInt methods across integer types and update tests

- Introduced `tryFromString` and `tryFromInt` methods returning `Undefined` on invalid input for `IntType` implementations.
- Updated interfaces to include `tryFromString` and `tryFromInt` declarations.
- Enhanced unit tests to verify `tryFromString` and `tryFromInt` behavior.
- Adjusted usage examples to demonstrate the new methods.

Author: georgedeploy

src/Abstract/Integer/IntTypeInterface.php

@@ -4,18 +4,24 @@
 
 namespace PhpTypedValues\Abstract\Integer;
 
+use PhpTypedValues\Undefined\Alias\Undefined;
+
 /**
  * @psalm-immutable
  */
 interface IntTypeInterface
 {
     public function value(): int;
 
+    public static function fromString(string $value): static;
+
     public static function fromInt(int $value): static;
 
-    public function toString(): string;
+    public static function tryFromString(string $value): static|Undefined;
 
-    public static function fromString(string $value): static;
+    public static function tryFromInt(int $value): static|Undefined;
+
+    public function toString(): string;
 
     public function __toString(): string;
 }

src/Integer/IntegerNonNegative.php

@@ -6,6 +6,8 @@
 
 use PhpTypedValues\Abstract\Integer\IntType;
 use PhpTypedValues\Exception\IntegerTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 use function sprintf;
 
@@ -33,6 +35,24 @@ public function __construct(int $value)
         $this->value = $value;
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    public static function tryFromInt(int $value): static|Undefined
+    {
+        try {
+            return static::fromInt($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     /**
      * @throws IntegerTypeException
      */

src/Integer/IntegerPositive.php

@@ -6,6 +6,8 @@
 
 use PhpTypedValues\Abstract\Integer\IntType;
 use PhpTypedValues\Exception\IntegerTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 use function sprintf;
 
@@ -33,6 +35,24 @@ public function __construct(int $value)
         $this->value = $value;
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    public static function tryFromInt(int $value): static|Undefined
+    {
+        try {
+            return static::fromInt($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     /**
      * @throws IntegerTypeException
      */

src/Integer/IntegerStandard.php

@@ -6,6 +6,8 @@
 
 use PhpTypedValues\Abstract\Integer\IntType;
 use PhpTypedValues\Exception\IntegerTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
  * Represents any PHP integer.
@@ -23,6 +25,21 @@ public function __construct(int $value)
         $this->value = $value;
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    public static function tryFromInt(int $value): static|Undefined
+    {
+        // IntegerStandard accepts any PHP int, so construction cannot fail.
+        return new static($value);
+    }
+
     public static function fromInt(int $value): static
     {
         return new static($value);

src/Integer/IntegerWeekDay.php

@@ -6,6 +6,8 @@
 
 use PhpTypedValues\Abstract\Integer\IntType;
 use PhpTypedValues\Exception\IntegerTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 use function sprintf;
 
@@ -45,6 +47,24 @@ public function value(): int
         return $this->value;
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    public static function tryFromInt(int $value): static|Undefined
+    {
+        try {
+            return static::fromInt($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     /**
      * @throws IntegerTypeException
      */

src/Integer/MariaDb/IntTiny.php

@@ -6,6 +6,8 @@
 
 use PhpTypedValues\Abstract\Integer\IntType;
 use PhpTypedValues\Exception\IntegerTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 use function sprintf;
 
@@ -33,6 +35,24 @@ public function __construct(int $value)
         $this->value = $value;
     }
 
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    public static function tryFromInt(int $value): static|Undefined
+    {
+        try {
+            return static::fromInt($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
     /**
      * @throws IntegerTypeException
      */

src/Usage/integer.php

@@ -24,13 +24,14 @@
 echo TinyInt::fromInt(-5)->toString() . \PHP_EOL;
 echo IntTiny::fromInt(-5)->toString() . \PHP_EOL;
 echo IntTiny::fromString('127')->toString() . \PHP_EOL;
-
 echo NonNegativeInt::fromString('10')->toString() . \PHP_EOL;
 echo PositiveInt::fromString('10')->toString() . \PHP_EOL;
 echo IntegerStandard::fromString('10')->toString() . \PHP_EOL;
 echo Id::fromString('10')->toString() . \PHP_EOL;
 echo IntType::fromString('10')->toString() . \PHP_EOL;
 echo Integer::fromString('10')->toString() . \PHP_EOL;
+echo Integer::tryFromString('127')->toString() . \PHP_EOL;
+echo Integer::tryFromInt(127)->toString() . \PHP_EOL;
 
 /**
  * Artificial functions.

tests/Unit/Integer/MariaDb/IntTinyTest.php

@@ -4,6 +4,7 @@
 
 use PhpTypedValues\Exception\IntegerTypeException;
 use PhpTypedValues\Integer\MariaDb\IntTiny;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 it('accepts values within signed tinyint range and preserves value', function (): void {
     $a = new IntTiny(-128);
@@ -38,3 +39,37 @@
     expect(fn() => IntTiny::fromString('12.3'))
         ->toThrow(IntegerTypeException::class, 'String "12.3" has no valid strict integer value');
 });
+
+it('IntTiny::tryFromString returns value within -128..127', function (): void {
+    $vMin = IntTiny::tryFromString('-128');
+    $v0 = IntTiny::tryFromString('0');
+    $vMax = IntTiny::tryFromString('127');
+
+    expect($vMin)
+        ->toBeInstanceOf(IntTiny::class)
+        ->and($vMin->value())->toBe(-128)
+        ->and($v0)
+        ->toBeInstanceOf(IntTiny::class)
+        ->and($v0->value())->toBe(0)
+        ->and($vMax)
+        ->toBeInstanceOf(IntTiny::class)
+        ->and($vMax->value())->toBe(127);
+});
+
+it('IntTiny::tryFromString returns Undefined outside range and for non-integer strings', function (): void {
+    expect(IntTiny::tryFromString('128'))
+        ->toBeInstanceOf(Undefined::class)
+        ->and(IntTiny::tryFromString('5.0'))
+        ->toBeInstanceOf(Undefined::class);
+});
+
+it('IntTiny::tryFromInt returns value within range and Undefined otherwise', function (): void {
+    $ok = IntTiny::tryFromInt(-5);
+    $bad = IntTiny::tryFromInt(200);
+
+    expect($ok)
+        ->toBeInstanceOf(IntTiny::class)
+        ->and($ok->value())->toBe(-5)
+        ->and($bad)
+        ->toBeInstanceOf(Undefined::class);
+});