[SCA] Restrict the possible values for the casing options under the Portability\ NS

Author: phansys

src/Portability/Converter.php

@@ -10,6 +10,9 @@
 use function is_string;
 use function rtrim;
 
+use const CASE_LOWER;
+use const CASE_UPPER;
+
 final class Converter
 {
     /** @var callable */
@@ -35,6 +38,8 @@ final class Converter
      * @param bool     $rightTrimString          Whether each string should right-trimmed
      * @param int|null $case                     Convert the case of the column names
      *                                           (one of {@see CASE_LOWER} and {@see CASE_UPPER})
+     *
+     * @phpstan-param CASE_LOWER|CASE_UPPER|null $case
      */
     public function __construct(bool $convertEmptyStringToNull, bool $rightTrimString, ?int $case)
     {
@@ -185,6 +190,8 @@ private function createConvertValue(bool $convertEmptyStringToNull, bool $rightT
      * @param callable|null $function The function that will convert each value
      * @param int|null      $case     Column name case
      *
+     * @phpstan-param CASE_LOWER|CASE_UPPER|null $case
+     *
      * @return callable|null The resulting function or NULL if no conversion is needed
      */
     private function createConvertRow(?callable $function, ?int $case): ?callable

src/Portability/Driver.php

@@ -18,8 +18,10 @@ final class Driver extends AbstractDriverMiddleware
 {
     private int $mode;
 
+    /** @phpstan-var 0|ColumnCase::LOWER|ColumnCase::UPPER */
     private int $case;
 
+    /** @phpstan-param 0|ColumnCase::LOWER|ColumnCase::UPPER $case */
     public function __construct(DriverInterface $driver, int $mode, int $case)
     {
         parent::__construct($driver);
@@ -55,6 +57,8 @@ public function connect(
 
             if ($nativeConnection instanceof PDO) {
                 $portability &= ~Connection::PORTABILITY_FIX_CASE;
+                // @todo: Create a mapping in order to handle the values for `PDO::ATTR_CASE` in a proper way, using the `PDO::CASE_*` constants.
+                // @see: https://www.php.net/manual/en/pdo.setattribute.php.
                 $nativeConnection->setAttribute(PDO::ATTR_CASE, $this->case);
             } else {
                 $case = $this->case === ColumnCase::LOWER ? CASE_LOWER : CASE_UPPER;

src/Portability/Middleware.php

@@ -4,15 +4,18 @@
 
 namespace Doctrine\DBAL\Portability;
 
+use Doctrine\DBAL\ColumnCase;
 use Doctrine\DBAL\Driver as DriverInterface;
 use Doctrine\DBAL\Driver\Middleware as MiddlewareInterface;
 
 final class Middleware implements MiddlewareInterface
 {
     private int $mode;
 
+    /** @phpstan-var 0|ColumnCase::LOWER|ColumnCase::UPPER */
     private int $case;
 
+    /** @phpstan-param 0|ColumnCase::LOWER|ColumnCase::UPPER $case */
     public function __construct(int $mode, int $case)
     {
         $this->mode = $mode;

src/Portability/OptimizeFlags.php

@@ -17,7 +17,7 @@ final class OptimizeFlags
      * Platform-specific portability flags that need to be excluded from the user-provided mode
      * since the platform already operates in this mode to avoid unnecessary conversion overhead.
      *
-     * @var array<string,int>
+     * @var array<class-string, int>
      */
     private static array $platforms = [
         DB2Platform::class        => 0,

tests/Functional/PortabilityTest.php

@@ -46,7 +46,8 @@ public function testFullFetchMode(): void
     }
 
     /**
-     * @param list<string> $expected
+     * @param 0|ColumnCase::LOWER|ColumnCase::UPPER $case
+     * @param list<string>                          $expected
      *
      * @dataProvider caseProvider
      */
@@ -61,7 +62,7 @@ public function testCaseConversion(int $case, array $expected): void
         self::assertSame($expected, array_keys($row));
     }
 
-    /** @return iterable<string, array{int, list<string>}> */
+    /** @return iterable<string, array{ColumnCase::LOWER|ColumnCase::UPPER, list<string>}> */
     public static function caseProvider(): iterable
     {
         yield 'lower' => [ColumnCase::LOWER, ['test_int', 'test_string', 'test_null']];
@@ -137,6 +138,7 @@ public function testGetDatabaseName(): void
         self::assertNotNull($this->connection->getDatabase());
     }
 
+     /** @phpstan-param 0|ColumnCase::LOWER|ColumnCase::UPPER $case */
     private function connectWithPortability(int $mode, int $case): void
     {
         // closing the default connection prior to 4.0.0 to prevent connection leak

tests/Portability/ConnectionTest.php

@@ -9,6 +9,8 @@
 use LogicException;
 use PHPUnit\Framework\TestCase;
 
+use const CASE_LOWER;
+
 class ConnectionTest extends TestCase
 {
     public function testGetServerVersion(): void
@@ -18,7 +20,7 @@ public function testGetServerVersion(): void
             ->method('getServerVersion')
             ->willReturn('1.2.3');
 
-        $connection = new Connection($driverConnection, new Converter(false, false, 0));
+        $connection = new Connection($driverConnection, new Converter(false, false, CASE_LOWER));
 
         self::assertSame('1.2.3', $connection->getServerVersion());
     }
@@ -27,7 +29,7 @@ public function testGetServerVersionFailsWithLegacyConnection(): void
     {
         $connection = new Connection(
             $this->createMock(DriverConnection::class),
-            new Converter(false, false, 0),
+            new Converter(false, false, CASE_LOWER),
         );
 
         $this->expectException(LogicException::class);
@@ -43,7 +45,7 @@ public function testGetNativeConnection(): void
         $driverConnection->method('getNativeConnection')
             ->willReturn($nativeConnection);
 
-        $connection = new Connection($driverConnection, new Converter(false, false, 0));
+        $connection = new Connection($driverConnection, new Converter(false, false, CASE_LOWER));
 
         self::assertSame($nativeConnection, $connection->getNativeConnection());
     }
@@ -52,7 +54,7 @@ public function testGetNativeConnectionFailsWithLegacyConnection(): void
     {
         $connection = new Connection(
             $this->createMock(DriverConnection::class),
-            new Converter(false, false, 0),
+            new Converter(false, false, CASE_LOWER),
         );
 
         $this->expectException(LogicException::class);

tests/Portability/ConverterTest.php

@@ -6,6 +6,7 @@
 use PHPUnit\Framework\TestCase;
 
 use const CASE_LOWER;
+use const CASE_UPPER;
 
 class ConverterTest extends TestCase
 {
@@ -64,6 +65,8 @@ public static function convertNumericProvider(): iterable
      * @param array<string,mixed>|false $row
      * @param array<string,mixed>|false $expected
      *
+     * @phpstan-param CASE_LOWER|CASE_UPPER|null $case
+     *
      * @dataProvider convertAssociativeProvider
      */
     public function testConvertAssociative(
@@ -279,6 +282,8 @@ public static function convertAllNumericProvider(): iterable
      * @param list<array<string,mixed>> $row
      * @param list<array<string,mixed>> $expected
      *
+     * @phpstan-param CASE_LOWER|CASE_UPPER|null $case
+     *
      * @dataProvider convertAllAssociativeProvider
      */
     public function testConvertAllAssociative(
@@ -499,6 +504,7 @@ public static function convertFirstColumnProvider(): iterable
         ];
     }
 
+    /** @phpstan-param CASE_LOWER|CASE_UPPER|null $case */
     private function createConverter(bool $convertEmptyStringToNull, bool $rightTrimString, ?int $case): Converter
     {
         return new Converter($convertEmptyStringToNull, $rightTrimString, $case);