Change BigIntType Casting

UPGRADE.md

@@ -2389,3 +2389,14 @@ The constructor of `Doctrine\DBAL\Exception\DriverException` is now `@internal`.
 - all `Configuration` methods are now typed
 - `Configuration::setSchemaAssetsFilter()` now returns `void`
 - `Configuration::$_attributes` has been removed; use individual properties in subclasses instead
+
+## BC Break: BIGINT types are now converted to integers
+
+Before:
+
+BIGINT values retrieved from the database used to be converted to PHP string.
+
+After:
+
+BIGINT values are cast to a PHP integer if the value is within the PHP integer range.
+Otherwise, it converts to a string.

docs/en/reference/types.rst

@@ -83,22 +83,22 @@ bigint
 ++++++
 
 Maps and converts 8-byte integer values.
-Unsigned integer values have a range of **0** to **18446744073709551615** while signed
+Unsigned integer values have a range of **0** to **18446744073709551615**, while signed
 integer values have a range of **−9223372036854775808** to **9223372036854775807**.
 If you know the integer data you want to store always fits into one of these ranges
 you should consider using this type.
-Values retrieved from the database are always converted to PHP's ``string`` type
-or ``null`` if no data is present.
+Values retrieved from the database are always converted to PHP's ``integer`` type
+or ``string`` if the data exceeds PHP's integer safe limits.
+Otherwise, returns ``null`` if no data is present.
 
 .. note::
 
-    For compatibility reasons this type is not converted to an integer
-    as PHP can only represent big integer values as real integers on
-    systems with a 64-bit architecture and would fall back to approximated
-    float values otherwise which could lead to false assumptions in applications.
-
-    Not all of the database vendors support unsigned integers, so such an assumption
-    might not be propagated to the database.
+    Due to architectural differences, 32-bit PHP systems have a smaller
+    integer range than their 64-bit counterparts. On 32-bit systems,
+    values exceeding this range will be represented as strings instead
+    of integers. Bear in mind that not all database vendors
+    support unsigned integers, so schema configuration cannot be
+    enforced.
 
 Decimal types
 ^^^^^^^^^^^^^

src/Types/BigIntType.php

@@ -7,8 +7,11 @@
 use Doctrine\DBAL\ParameterType;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 
+use const PHP_INT_MAX;
+use const PHP_INT_MIN;
+
 /**
- * Type that maps a database BIGINT to a PHP string.
+ * Type that maps a database BIGINT to a PHP int.
  */
 class BigIntType extends Type implements PhpIntegerMappingType
 {
@@ -28,12 +31,23 @@ public function getBindingType(): ParameterType
     /**
      * @param T $value
      *
-     * @return (T is null ? null : string)
+     * @return (T is null ? null : int|string)
      *
      * @template T
      */
-    public function convertToPHPValue(mixed $value, AbstractPlatform $platform): ?string
+    public function convertToPHPValue(mixed $value, AbstractPlatform $platform): int|string|null
     {
-        return $value === null ? null : (string) $value;
+        if ($value === null) {
+            return null;
+        }
+
+        if (
+            ($value >= PHP_INT_MIN && $value < PHP_INT_MAX) ||
+            (string) $value === (string) PHP_INT_MAX
+        ) {
+            return (int) $value;
+        }
+
+        return (string) $value;
     }
 }

tests/Functional/BigIntConversionTest.php

@@ -0,0 +1,140 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tests\Functional;
+
+use Doctrine\DBAL\Schema\Table;
+use Doctrine\DBAL\Tests\FunctionalTestCase;
+use Doctrine\DBAL\Types\BigIntType;
+use Doctrine\DBAL\Types\Types;
+
+use const PHP_INT_MAX;
+use const PHP_INT_MIN;
+
+class BigIntConversionTest extends FunctionalTestCase
+{
+    private BigIntType $typeInstance;
+
+    protected function setUp(): void
+    {
+        $this->typeInstance = new BigIntType();
+
+        $table = new Table('bigint_conversion_test');
+        $table->addColumn('id', Types::SMALLINT, ['notnull' => true]);
+        $table->addColumn('signed_integer', Types::BIGINT, ['notnull' => false]);
+        $table->addColumn('unsigned_integer', Types::BIGINT, [
+            'notnull' => false,
+            'unsigned' => true,
+        ]);
+        $table->setPrimaryKey(['id']);
+        $this->dropAndCreateTable($table);
+    }
+
+    public function testShouldConvertToZeroInteger(): void
+    {
+        $this->connection->insert('bigint_conversion_test', [
+            'id' => 0,
+            'signed_integer' => 0,
+        ]);
+        $this->assertPHPValue(
+            0,
+            'SELECT signed_integer from bigint_conversion_test WHERE id = 0',
+        );
+    }
+
+    public function testShouldConvertToPhpMinimumInteger(): void
+    {
+        $this->connection->insert('bigint_conversion_test', [
+            'id' => 1,
+            'signed_integer' => PHP_INT_MIN,
+        ]);
+        $this->assertPHPValue(
+            PHP_INT_MIN,
+            'SELECT signed_integer from bigint_conversion_test WHERE id = 1',
+        );
+    }
+
+    public function testShouldConvertToPhpMaximumInteger(): void
+    {
+        $this->connection->insert('bigint_conversion_test', [
+            'id' => 2,
+            'signed_integer' => PHP_INT_MAX,
+        ]);
+        $this->assertPHPValue(
+            PHP_INT_MAX,
+            'SELECT signed_integer from bigint_conversion_test WHERE id = 2',
+        );
+    }
+
+    public function testShouldConvertToPositiveIntegerNumber(): void
+    {
+        $this->connection->insert('bigint_conversion_test', [
+            'id' => 3,
+            'signed_integer' => PHP_INT_MAX - 1,
+        ]);
+        $this->assertPHPValue(
+            PHP_INT_MAX - 1,
+            'SELECT signed_integer from bigint_conversion_test WHERE id = 3',
+        );
+    }
+
+    public function testShouldConvertToNegativeIntegerNumber(): void
+    {
+        $this->connection->insert('bigint_conversion_test', [
+            'id' => 4,
+            'signed_integer' => PHP_INT_MIN + 1,
+        ]);
+        $this->assertPHPValue(
+            PHP_INT_MIN + 1,
+            'SELECT signed_integer from bigint_conversion_test WHERE id = 4',
+        );
+    }
+
+    public function testShouldConvertSlightlyOutOfPhpIntegerRangeUnsignedValueToString(): void
+    {
+        $this->connection->insert('bigint_conversion_test', [
+            'id' => 5,
+            'unsigned_integer' => '9223372036854775808',
+        ]);
+        $this->assertPHPValue(
+            '9223372036854775808',
+            'SELECT unsigned_integer from bigint_conversion_test WHERE id = 5',
+        );
+    }
+
+    public function testShouldConvertMaximumUnsignedIntegerValueToString(): void
+    {
+        $this->connection->insert('bigint_conversion_test', [
+            'id' => 6,
+            'unsigned_integer' => '18446744073709551615',
+        ]);
+        $this->assertPHPValue(
+            '18446744073709551615',
+            'SELECT unsigned_integer from bigint_conversion_test WHERE id = 6',
+        );
+    }
+
+    public function testShouldConvertNearlyMaximumUnsignedIntegerValueToString(): void
+    {
+        $this->connection->insert('bigint_conversion_test', [
+            'id' => 7,
+            'unsigned_integer' => '18446744073709551610',
+        ]);
+        $this->assertPHPValue(
+            '18446744073709551610',
+            'SELECT unsigned_integer from bigint_conversion_test WHERE id = 7',
+        );
+    }
+
+    private function assertPHPValue(mixed $expected, string $sql): void
+    {
+        self::assertSame(
+            $expected,
+            $this->typeInstance->convertToPHPValue(
+                $this->connection->fetchOne($sql),
+                $this->connection->getDatabasePlatform(),
+            ),
+        );
+    }
+}

tests/Types/BigIntTypeTest.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tests\Types;
+
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Types\BigIntType;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+use const PHP_INT_MAX;
+use const PHP_INT_MIN;
+
+class BigIntTypeTest extends TestCase
+{
+    /** @var MockObject&AbstractPlatform */
+    private AbstractPlatform $platform;
+
+    private BigIntType $type;
+
+    protected function setUp(): void
+    {
+        $this->platform = $this->createMock(AbstractPlatform::class);
+        $this->type     = new BigIntType();
+    }
+
+    public function testShouldConvertPhpIntMinToInteger(): void
+    {
+        self::assertSame(
+            PHP_INT_MIN,
+            $this->type->convertToPHPValue(PHP_INT_MIN, $this->platform),
+        );
+    }
+
+    public function testShouldConvertPhpIntMaxToInteger(): void
+    {
+        self::assertSame(
+            PHP_INT_MAX,
+            $this->type->convertToPHPValue(PHP_INT_MAX, $this->platform),
+        );
+    }
+
+    public function testShouldConvertPhpIntMinAsStringToInteger(): void
+    {
+        self::assertSame(
+            PHP_INT_MIN,
+            $this->type->convertToPHPValue(
+                (string) PHP_INT_MIN,
+                $this->platform,
+            ),
+        );
+    }
+
+    public function testShouldConvertPhpIntMaxAsStringToInteger(): void
+    {
+        self::assertSame(
+            PHP_INT_MAX,
+            $this->type->convertToPHPValue(
+                (string) PHP_INT_MAX,
+                $this->platform,
+            ),
+        );
+    }
+
+    public function testShouldConvertZeroIntegerToInteger(): void
+    {
+        self::assertSame(0, $this->type->convertToPHPValue(0, $this->platform));
+    }
+
+    public function testShouldConvertZeroStringToInteger(): void
+    {
+        self::assertSame(
+            0,
+            $this->type->convertToPHPValue('0', $this->platform),
+        );
+    }
+
+    public function testShouldConvertSafeNegativeValueToInteger(): void
+    {
+        self::assertSame(
+            PHP_INT_MIN + 1,
+            $this->type->convertToPHPValue(PHP_INT_MIN + 1, $this->platform),
+        );
+    }
+
+    public function testShouldConvertSafePositiveValueToInteger(): void
+    {
+        self::assertSame(
+            PHP_INT_MAX - 1,
+            $this->type->convertToPHPValue(PHP_INT_MAX - 1, $this->platform),
+        );
+    }
+
+    public function testShouldConvertMaximumUnsignedIntegerValueToString(): void
+    {
+        self::assertSame(
+            '18446744073709551615',
+            $this->type->convertToPHPValue(
+                '18446744073709551615',
+                $this->platform,
+            ),
+        );
+    }
+}