refactor: modernise the validation in active code and the associated tests for dealing with integer arrays

src/MartinGeorgiev/Doctrine/DBAL/Types/BaseIntegerArray.php

@@ -4,7 +4,8 @@
 
 namespace MartinGeorgiev\Doctrine\DBAL\Types;
 
-use Doctrine\DBAL\Types\ConversionException;
+use MartinGeorgiev\Doctrine\DBAL\Types\Exceptions\InvalidIntegerArrayItemForDatabaseException;
+use MartinGeorgiev\Doctrine\DBAL\Types\Exceptions\InvalidIntegerArrayItemForPHPException;
 
 /**
  * @see https://www.postgresql.org/docs/9.4/static/arrays.html
@@ -14,45 +15,74 @@
  */
 abstract class BaseIntegerArray extends BaseArray
 {
-    abstract protected function getMinValue(): string;
+    private const INTEGER_REGEX = '/^-?\d+$/';
 
-    abstract protected function getMaxValue(): string;
+    abstract protected function getMinValue(): int;
 
-    /**
-     * @param mixed $item
-     */
-    public function isValidArrayItemForDatabase($item): bool
+    abstract protected function getMaxValue(): int;
+
+    public function isValidArrayItemForDatabase(mixed $item): bool
     {
-        if (!\is_int($item) && !\is_string($item)) {
+        try {
+            $this->throwIfInvalidArrayItemForDatabase($item);
+        } catch (InvalidIntegerArrayItemForDatabaseException) {
             return false;
         }
 
-        if (!(bool) \preg_match('/^-?\d+$/', (string) $item)) {
-            return false;
+        return true;
+    }
+
+    private function throwIfInvalidArrayItemForDatabase(mixed $item): void
+    {
+        $isNotANumber = !\is_int($item) && !\is_string($item);
+        if ($isNotANumber) {
+            throw InvalidIntegerArrayItemForDatabaseException::isNotANumber($item);
         }
 
-        if ((string) $item < $this->getMinValue()) {
-            return false;
+        $stringValue = (string) $item;
+        if (!\preg_match(self::INTEGER_REGEX, $stringValue)) {
+            throw InvalidIntegerArrayItemForDatabaseException::doesNotMatchRegex($item);
+        }
+
+        $doesNotFitIntoPHPInteger = $stringValue !== (string) (int) $stringValue;
+        if ($doesNotFitIntoPHPInteger) {
+            throw InvalidIntegerArrayItemForDatabaseException::isOutOfRange($item);
         }
 
-        return (string) $item <= $this->getMaxValue();
+        $integerValue = (int) $item;
+        if ($integerValue < $this->getMinValue()) {
+            throw InvalidIntegerArrayItemForDatabaseException::isBelowMinValue($item);
+        }
+
+        if ($integerValue > $this->getMaxValue()) {
+            throw InvalidIntegerArrayItemForDatabaseException::isAboveMaxValue($item);
+        }
     }
 
-    /**
-     * @param int|string|null $item Whole number
-     */
-    public function transformArrayItemForPHP($item): ?int
+    public function transformArrayItemForPHP(mixed $item): ?int
     {
         if ($item === null) {
             return null;
         }
 
+        $isNotANumberCandidate = !\is_int($item) && !\is_string($item);
+        if ($isNotANumberCandidate) {
+            throw InvalidIntegerArrayItemForPHPException::forValueThatIsNotAValidPHPInteger($item, static::TYPE_NAME);
+        }
+
         $stringValue = (string) $item;
-        $isInvalidPHPInt = !(bool) \preg_match('/^-?\d+$/', $stringValue)
-            || $stringValue < $this->getMinValue()
-            || $stringValue > $this->getMaxValue();
-        if ($isInvalidPHPInt) {
-            throw new ConversionException(\sprintf('Given value of %s content cannot be transformed to valid PHP integer.', \var_export($item, true)));
+        if (!\preg_match(self::INTEGER_REGEX, $stringValue)) {
+            throw InvalidIntegerArrayItemForPHPException::forValueThatIsNotAValidPHPInteger($item, static::TYPE_NAME);
+        }
+
+        $doesNotFitIntoPHPInteger = $stringValue !== (string) (int) $stringValue;
+        if ($doesNotFitIntoPHPInteger) {
+            throw InvalidIntegerArrayItemForPHPException::forValueOutOfRangeInPHP($item, static::TYPE_NAME);
+        }
+
+        $doesNotFitIntoDatabaseInteger = $stringValue < $this->getMinValue() || $stringValue > $this->getMaxValue();
+        if ($doesNotFitIntoDatabaseInteger) {
+            throw InvalidIntegerArrayItemForPHPException::forValueOutOfRangeInDatabaseType($item, static::TYPE_NAME);
         }
 
         return (int) $item;

src/MartinGeorgiev/Doctrine/DBAL/Types/BigIntArray.php

@@ -19,13 +19,13 @@ class BigIntArray extends BaseIntegerArray
      */
     protected const TYPE_NAME = 'bigint[]';
 
-    protected function getMinValue(): string
+    protected function getMinValue(): int
     {
-        return '-9223372036854775807';
+        return PHP_INT_MIN;
     }
 
-    protected function getMaxValue(): string
+    protected function getMaxValue(): int
     {
-        return '9223372036854775807';
+        return PHP_INT_MAX;
     }
 }

src/MartinGeorgiev/Doctrine/DBAL/Types/Exceptions/InvalidIntegerArrayItemForDatabaseException.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\DBAL\Types\Exceptions;
+
+use Doctrine\DBAL\Types\ConversionException;
+
+/**
+ * @since 3.0
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+class InvalidIntegerArrayItemForDatabaseException extends ConversionException
+{
+    private static function create(string $message, mixed $value): self
+    {
+        return new self(\sprintf($message, \var_export($value, true)));
+    }
+
+    public static function isNotANumber(mixed $value): self
+    {
+        return self::create('Given value of %s is not a number.', $value);
+    }
+
+    public static function doesNotMatchRegex(mixed $value): self
+    {
+        return self::create('Given value of %s does not match integer regex.', $value);
+    }
+
+    public static function isBelowMinValue(mixed $value): self
+    {
+        return self::create('Given value of %s is below minimum value.', $value);
+    }
+
+    public static function isAboveMaxValue(mixed $value): self
+    {
+        return self::create('Given value of %s is above maximum value.', $value);
+    }
+
+    public static function isOutOfRange(mixed $value): self
+    {
+        return self::create('Given value of %s is out of range.', $value);
+    }
+}

src/MartinGeorgiev/Doctrine/DBAL/Types/Exceptions/InvalidIntegerArrayItemForPHPException.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MartinGeorgiev\Doctrine\DBAL\Types\Exceptions;
+
+use Doctrine\DBAL\Types\ConversionException;
+
+/**
+ * @since 3.0
+ *
+ * @author Martin Georgiev <martin.georgiev@gmail.com>
+ */
+class InvalidIntegerArrayItemForPHPException extends ConversionException
+{
+    private static function create(string $message, mixed $value, string $type): self
+    {
+        return new self(\sprintf($message, \var_export($value, true), $type));
+    }
+
+    public static function forValueThatIsNotAValidPHPInteger(mixed $value, string $type): self
+    {
+        return self::create('Given value of %s content cannot be transformed to valid PHP integer from PostgreSQL %s type', $value, $type);
+    }
+
+    public static function forValueOutOfRangeInPHP(mixed $value, string $type): self
+    {
+        return self::create('Given value of %s is out of range for PHP integer but appears valid for PostgreSQL %s type', $value, $type);
+    }
+
+    public static function forValueOutOfRangeInDatabaseType(mixed $value, string $type): self
+    {
+        return self::create('Given value of %s is out of range for PostgreSQL %s type', $value, $type);
+    }
+}

src/MartinGeorgiev/Doctrine/DBAL/Types/IntegerArray.php

@@ -19,13 +19,13 @@ class IntegerArray extends BaseIntegerArray
      */
     protected const TYPE_NAME = 'integer[]';
 
-    protected function getMinValue(): string
+    protected function getMinValue(): int
     {
-        return '-2147483648';
+        return -2147483648;
     }
 
-    protected function getMaxValue(): string
+    protected function getMaxValue(): int
     {
-        return '2147483647';
+        return 2147483647;
     }
 }

src/MartinGeorgiev/Doctrine/DBAL/Types/SmallIntArray.php

@@ -19,13 +19,13 @@ class SmallIntArray extends BaseIntegerArray
      */
     protected const TYPE_NAME = 'smallint[]';
 
-    protected function getMinValue(): string
+    protected function getMinValue(): int
     {
-        return '-32768';
+        return -32768;
     }
 
-    protected function getMaxValue(): string
+    protected function getMaxValue(): int
     {
-        return '32767';
+        return 32767;
     }
 }

tests/MartinGeorgiev/Doctrine/DBAL/Types/BaseIntegerArrayTestCase.php

@@ -5,14 +5,11 @@
 namespace Tests\MartinGeorgiev\Doctrine\DBAL\Types;
 
 use MartinGeorgiev\Doctrine\DBAL\Types\BaseIntegerArray;
-use PHPUnit\Framework\MockObject\MockObject;
+use MartinGeorgiev\Doctrine\DBAL\Types\Exceptions\InvalidIntegerArrayItemForPHPException;
 use PHPUnit\Framework\TestCase;
 
 abstract class BaseIntegerArrayTestCase extends TestCase
 {
-    /**
-     * @var BaseIntegerArray&MockObject
-     */
     protected BaseIntegerArray $fixture;
 
     /**
@@ -33,10 +30,14 @@ public static function provideInvalidTransformations(): array
         return [
             [true],
             [null],
-            [-0.1],
             ['string'],
             [[]],
             [new \stdClass()],
+            ['1.23'],
+            ['not_a_number'],
+            ['1e2'],
+            ['0xFF'],
+            ['123abc'],
         ];
     }
 
@@ -61,7 +62,28 @@ public function can_transform_to_php_value(int $phpValue, string $postgresValue)
     }
 
     /**
-     * @return list<array<string, int|string>>
+     * @return list<array{
+     *     phpValue: int,
+     *     postgresValue: string
+     * }>
      */
     abstract public static function provideValidTransformations(): array;
+
+    /**
+     * @test
+     *
+     * @dataProvider provideOutOfRangeValues
+     */
+    public function throws_domain_exception_when_value_exceeds_range(string $outOfRangeValue): void
+    {
+        $this->expectException(InvalidIntegerArrayItemForPHPException::class);
+        $this->expectExceptionMessage('is out of range for PostgreSQL');
+
+        $this->fixture->transformArrayItemForPHP($outOfRangeValue);
+    }
+
+    /**
+     * @return list<string>
+     */
+    abstract protected function provideOutOfRangeValues(): array;
 }

tests/MartinGeorgiev/Doctrine/DBAL/Types/BigIntArrayTest.php

@@ -5,14 +5,13 @@
 namespace Tests\MartinGeorgiev\Doctrine\DBAL\Types;
 
 use MartinGeorgiev\Doctrine\DBAL\Types\BigIntArray;
+use MartinGeorgiev\Doctrine\DBAL\Types\Exceptions\InvalidIntegerArrayItemForPHPException;
 
 class BigIntArrayTest extends BaseIntegerArrayTestCase
 {
     protected function setUp(): void
     {
-        parent::setUp();
-
-        $this->fixture = new BigIntArray(); // @phpstan-ignore-line
+        $this->fixture = new BigIntArray();
     }
 
     /**
@@ -25,26 +24,68 @@
 
     public static function provideInvalidTransformations(): array
     {
-        return \array_merge(parent::provideInvalidTransformations(), [['-9223372036854775807.01'], [-9_223_372_036_854_775_809.0]]);
+        return \array_merge(parent::provideInvalidTransformations(), [
+            ['9223372036854775808'],    // Greater than PHP_INT_MAX
+            ['-9223372036854775809'],   // Less than PHP_INT_MIN
+            ['1.23e10'],                // Scientific notation
+            ['12345.67890'],            // Decimal number
+        ]);
     }
 
     /**
-     * @return list<array{
-     *     phpValue: int,
-     *     postgresValue: string
-     * }>
+     * @return array<int, array{phpValue: int, postgresValue: string}>
      */
     public static function provideValidTransformations(): array
     {
         return [
             [
-                'phpValue' => -9_223_372_036_854_775_807,
-                'postgresValue' => '-9223372036854775807',
+                'phpValue' => PHP_INT_MAX,
+                'postgresValue' => (string) PHP_INT_MAX,
+            ],
+            [
+                'phpValue' => PHP_INT_MIN,
+                'postgresValue' => (string) PHP_INT_MIN,
+            ],
+            [
+                'phpValue' => 0,
+                'postgresValue' => '0',
+            ],
+            [
+                'phpValue' => 1,
+                'postgresValue' => '1',
+            ],
+            [
+                'phpValue' => -1,
+                'postgresValue' => '-1',
             ],
             [
                 'phpValue' => 9_223_372_036_854_775_807,
                 'postgresValue' => '9223372036854775807',
             ],
         ];
     }
+
+    /**
+     * @test
+     *
+     * @dataProvider provideOutOfRangeValues
+     */
+    public function throws_domain_exception_when_value_exceeds_range(string $outOfRangeValue): void
+    {
+        $this->expectException(InvalidIntegerArrayItemForPHPException::class);
+        $this->expectExceptionMessage('is out of range for PHP integer but appears valid for PostgreSQL');
+
+        $this->fixture->transformArrayItemForPHP($outOfRangeValue);
+    }
+
+    /**
+     * @return array<array{string}>
+     */
+    protected function provideOutOfRangeValues(): array
+    {
+        return [
+            ['9223372036854775808'], // PHP_INT_MAX + 1
+            ['-9223372036854775809'], // PHP_INT_MIN - 1
+        ];
+    }
 }