Refactor integer validation to enforce strict integer parsing and enhance exception handling

- Replaced `integerish` with strict `integer` validation in `Assert` to prevent unexpected conversions.
- Updated integer type tests (`PositiveInt`, `NonNegativeInt`, `WeekDayInt`, `IntegerBasic`) to verify exceptions for non-strict integer strings.
- Refined `IntType` to use strict checks and improved error messaging.
- Removed redundant examples from `psalmTest.php` and adjusted invalid input scenarios.
- Enhanced documentation and inline comments for clarity.

Author: georgedeploy

src/Code/Assert/Assert.php

@@ -8,6 +8,7 @@
 use PhpTypedValues\Code\Exception\StringTypeException;
 
 use function is_numeric;
+use function sprintf;
 
 final class Assert
 {
@@ -32,16 +33,19 @@ public static function lessThanEq(int|float $value, int|float $max, string $mess
     }
 
     /**
-     * Assert that the given value looks like an integer ("integerish").
-     * Accepts numeric strings that represent an integer value (e.g., '5', '5.0'),
-     * but rejects non-numeric strings and floats with a fractional part (e.g., '5.5').
+     * Assert that the given value looks like an integer.
+     * Accepts numeric strings that represent an integer value (e.g., '5', '-5'),
+     * but rejects non-numeric strings and floats with a fractional part (e.g., '5.5', '05').
      *
      * @throws NumericTypeException
      */
-    public static function integerish(mixed $value, string $message = ''): void
+    public static function integer(mixed $value, string $message = ''): void
     {
-        if (!is_numeric($value) || $value != (int) $value) {
-            throw new NumericTypeException($message !== '' ? $message : 'Expected an "integerish" value');
+        // Strict check, avoid unexpected string conversion
+        $value = (string) $value;
+        $convertedValue = (string) ((int) $value);
+        if ($value !== $convertedValue) {
+            throw new NumericTypeException($message !== '' ? $message : sprintf('Unexpected conversions possible, "%s" !== "%s"', $value, $convertedValue));
         }
     }
 

src/Code/Integer/IntType.php

@@ -17,7 +17,7 @@
      */
     protected static function assertNumericString(string $value): void
     {
-        Assert::integerish($value, 'String has no valid integer');
+        Assert::integer($value, 'String has no valid integer');
     }
 
     public function toString(): string

src/psalmTest.php

@@ -55,13 +55,6 @@
 $dt = DateTimeAtom::fromString('2025-01-02T03:04:05+00:00')->value();
 echo DateTimeAtom::fromDateTime($dt)->toString() . \PHP_EOL;
 
-try {
-    $dt = DateTimeAtom::fromString('2025-12-02T03:04:05+ 00:00')->value();
-    echo DateTimeAtom::fromDateTime($dt)->toString() . \PHP_EOL;
-} catch (Throwable $e) {
-    var_export($e);
-}
-
 /**
  * Artificial functions.
  */

tests/Unit/Code/Assert/AssertTest.php

@@ -38,20 +38,20 @@
     expect(true)->toBeTrue();
 });
 
-it('integerish throws with default message when empty', function (): void {
-    expect(fn() => Assert::integerish('5.5', ''))
-        ->toThrow(NumericTypeException::class, 'Expected an "integerish" value');
+it('integer throws with default message when empty', function (): void {
+    expect(fn() => Assert::integer('5.5', ''))
+        ->toThrow(NumericTypeException::class, 'Unexpected conversions possible, "5.5" !== "5"');
 });
 
 it('integerish throws with custom message when provided', function (): void {
-    expect(fn() => Assert::integerish('foo', 'custom integerish message'))
+    expect(fn() => Assert::integer('foo', 'custom integerish message'))
         ->toThrow(NumericTypeException::class, 'custom integerish message');
 });
 
-it('integerish does not throw for integerish values', function (): void {
-    Assert::integerish('5', '');
-    Assert::integerish('5.0', '');
-    Assert::integerish(5, '');
+it('integer does not throw for integer values', function (): void {
+    Assert::integer('5', '');
+    Assert::integer('-5', '');
+    Assert::integer(5, '');
     expect(true)->toBeTrue();
 });
 

tests/Unit/Code/Integer/IntTypeTest.php

@@ -17,15 +17,12 @@
 
 it('fromString parses valid integer strings including negatives and leading zeros', function (): void {
     expect(IntegerBasic::fromString('-15')->value())->toBe(-15)
-        ->and(IntegerBasic::fromString('0007')->value())->toBe(7)
-        ->and(IntegerBasic::fromString('+5')->value())->toBe(5)
-        ->and(IntegerBasic::fromString(' 5')->value())->toBe(5)
-        ->and(IntegerBasic::fromString('5 ')->value())->toBe(5)
+        ->and(IntegerBasic::fromString('0')->toString())->toBe('0')
         ->and(IntegerBasic::fromString('42')->toString())->toBe('42');
 });
 
 it('fromString rejects non-integer strings', function (): void {
-    $invalid = ['5a', 'a5', '', 'abc', '--5', '3.14'];
+    $invalid = ['5a', 'a5', '', 'abc', ' 5', '5 ', '+5', '05', '--5', '3.14'];
     foreach ($invalid as $str) {
         expect(fn() => IntegerBasic::fromString($str))->toThrow(NumericTypeException::class);
     }

tests/Unit/Integer/IntegerTypeTest.php

@@ -14,7 +14,7 @@
 });
 
 it('fails on "integer-ish" float string', function (): void {
-    expect(IntegerBasic::fromString('5.0')->value())->toBe(5);
+    expect(fn() => IntegerBasic::fromString('5.'))->toThrow(NumericTypeException::class);
 });
 
 it('fails on float string', function (): void {

tests/Unit/Integer/NonNegativeIntTypeTest.php

@@ -17,8 +17,8 @@
     expect(NonNegativeInt::fromString('0')->value())->toBe(0);
 });
 
-it('creates NonNegativeInt from integerish string', function (): void {
-    expect(NonNegativeInt::fromString('5.0')->value())->toBe(5);
+it('fails NonNegativeInt from integerish string', function (): void {
+    expect(fn() => NonNegativeInt::fromString('5.0'))->toThrow(NumericTypeException::class);
 });
 
 it('fails creating NonNegativeInt from negative string', function (): void {

tests/Unit/Integer/PositiveIntTypeTest.php

@@ -21,8 +21,8 @@
     expect(PositiveInt::fromString('1')->value())->toBe(1);
 });
 
-it('creates PositiveInt from integerish string', function (): void {
-    expect(PositiveInt::fromString('5.0')->value())->toBe(5);
+it('fails PositiveInt from integerish string', function (): void {
+    expect(fn() => PositiveInt::fromString('5.0'))->toThrow(NumericTypeException::class);
 });
 
 it('fails creating PositiveInt from string 0', function (): void {

tests/Unit/Integer/WeekDayIntTypeTest.php

@@ -27,7 +27,7 @@
 });
 
 it('creates WeekDayInt from integerish string', function (): void {
-    expect(WeekDayInt::fromString('5.0')->value())->toBe(5);
+    expect(fn() => WeekDayInt::fromString('5.0'))->toThrow(NumericTypeException::class);
 });
 
 it('fails creating WeekDayInt from out-of-range strings', function (): void {