Trigger runtime deprecations for legacy API

doctrine · Mar 2, 2023 · aa5449e · aa5449e
1 parent 762d8bf
commit aa5449e
Show file tree

Hide file tree

Showing 5 changed files with 65 additions and 4 deletions.
diff --git a/psalm.xml.dist b/psalm.xml.dist
@@ -51,6 +51,7 @@
                 -->
                 <referencedClass name="Doctrine\DBAL\Driver\ServerInfoAwareConnection"/>
                 <referencedClass name="Doctrine\DBAL\VersionAwarePlatformDriver"/>
+                <referencedClass name="Doctrine\DBAL\FetchMode"/>
                 <!--
                     TODO: remove in 4.0.0
                 -->
@@ -604,6 +605,7 @@
         <InvalidArgument>
             <errorLevel type="suppress">
                 <!-- We're testing with invalid input here. -->
+                <file name="tests/Functional/LegacyAPITest.php"/>
                 <file name="tests/Platforms/AbstractPlatformTestCase.php"/>
             </errorLevel>
         </InvalidArgument>
@@ -748,6 +750,7 @@
 
                 <!-- We're checking for invalid input. -->
                 <directory name="src/Driver/PgSQL"/>
+                <file name="src/Result.php"/>
             </errorLevel>
         </RedundantConditionGivenDocblockType>
         <RedundantPropertyInitializationCheck>

diff --git a/src/Connection.php b/src/Connection.php
@@ -1953,20 +1953,34 @@ public function executeUpdate(string $sql, array $params = [], array $types = []
     /**
      * BC layer for a wide-spread use-case of old DBAL APIs
      *
-     * @deprecated This API is deprecated and will be removed after 2022
+     * @deprecated Use {@see executeQuery()} instead
      */
     public function query(string $sql): Result
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'TODO',
+            '%s is deprecated, please use executeQuery() instead.',
+            __METHOD__,
+        );
+
         return $this->executeQuery($sql);
     }
 
     /**
      * BC layer for a wide-spread use-case of old DBAL APIs
      *
-     * @deprecated This API is deprecated and will be removed after 2022
+     * @deprecated please use {@see executeStatement()} instead
      */
     public function exec(string $sql): int
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'TODO',
+            '%s is deprecated, please use executeStatement() instead.',
+            __METHOD__,
+        );
+
         return $this->executeStatement($sql);
     }
 }
diff --git a/src/FetchMode.php b/src/FetchMode.php
@@ -4,6 +4,8 @@
 
 /**
  * Legacy Class that keeps BC for using the legacy APIs fetch()/fetchAll().
+ *
+ * @deprecated Use the dedicated fetch*() methods for the desired fetch mode instead.
  */
 class FetchMode
 {

diff --git a/src/Result.php b/src/Result.php
@@ -7,6 +7,7 @@
 use Doctrine\DBAL\Driver\Exception as DriverException;
 use Doctrine\DBAL\Driver\Result as DriverResult;
 use Doctrine\DBAL\Exception\NoKeyValue;
+use Doctrine\Deprecations\Deprecation;
 use LogicException;
 use Traversable;
 
@@ -261,14 +262,23 @@ private function ensureHasKeyValue(): void
     /**
      * BC layer for a wide-spread use-case of old DBAL APIs
      *
-     * @deprecated This API is deprecated and will be removed after 2022
+     * @deprecated Use {@see fetchNumeric()}, {@see fetchAssociative()} or {@see fetchOne()} instead.
+     *
+     * @psalm-param FetchMode::* $mode
      *
      * @return mixed
      *
      * @throws Exception
      */
     public function fetch(int $mode = FetchMode::ASSOCIATIVE)
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'TODO',
+            '%s is deprecated, please use fetchNumeric(), fetchAssociative() or fetchOne() instead.',
+            __METHOD__,
+        );
+
         if (func_num_args() > 1) {
             throw new LogicException('Only invocations with one argument are still supported by this legacy API.');
         }
@@ -291,14 +301,23 @@ public function fetch(int $mode = FetchMode::ASSOCIATIVE)
     /**
      * BC layer for a wide-spread use-case of old DBAL APIs
      *
-     * @deprecated This API is deprecated and will be removed after 2022
+     * @deprecated Use {@see fetchAllNumeric()}, {@see fetchAllAssociative()} or {@see fetchFirstColumn()} instead.
+     *
+     * @psalm-param FetchMode::* $mode
      *
      * @return list<mixed>
      *
      * @throws Exception
      */
     public function fetchAll(int $mode = FetchMode::ASSOCIATIVE): array
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'TODO',
+            '%s is deprecated, please use fetchAllNumeric(), fetchAllAssociative() or fetchFirstColumn() instead.',
+            __METHOD__,
+        );
+
         if (func_num_args() > 1) {
             throw new LogicException('Only invocations with one argument are still supported by this legacy API.');
         }

diff --git a/tests/Functional/LegacyAPITest.php b/tests/Functional/LegacyAPITest.php
@@ -5,6 +5,7 @@
 use Doctrine\DBAL\FetchMode;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Tests\FunctionalTestCase;
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use LogicException;
 
 use function array_change_key_case;
@@ -14,6 +15,8 @@
 
 class LegacyAPITest extends FunctionalTestCase
 {
+    use VerifyDeprecations;
+
     protected function setUp(): void
     {
         $table = new Table('legacy_table');
@@ -39,6 +42,9 @@ public function testFetchWithAssociativeMode(): void
         $sql = 'SELECT test_int FROM legacy_table WHERE test_int = 1';
 
         $stmt = $this->connection->executeQuery($sql);
+
+        $this->expectDeprecationWithIdentifier('TODO');
+
         $row  = array_change_key_case($stmt->fetch(FetchMode::ASSOCIATIVE), CASE_LOWER);
         self::assertEquals(1, $row['test_int']);
     }
@@ -48,6 +54,9 @@ public function testFetchWithNumericMode(): void
         $sql = 'SELECT test_int FROM legacy_table WHERE test_int = 1';
 
         $stmt = $this->connection->executeQuery($sql);
+
+        $this->expectDeprecationWithIdentifier('TODO');
+
         $row  = $stmt->fetch(FetchMode::NUMERIC);
         self::assertEquals(1, $row[0]);
     }
@@ -57,6 +66,9 @@ public function testFetchWithColumnMode(): void
         $sql = 'SELECT test_int FROM legacy_table WHERE test_int = 1';
 
         $stmt = $this->connection->executeQuery($sql);
+
+        $this->expectDeprecationWithIdentifier('TODO');
+
         $row  = $stmt->fetch(FetchMode::COLUMN);
         self::assertEquals(1, $row);
     }
@@ -89,6 +101,8 @@ public function testFetchAllWithAssociativeModes(): void
 
         $stmt = $this->connection->executeQuery($sql);
 
+        $this->expectDeprecationWithIdentifier('TODO');
+
         $rows = $stmt->fetchAll(FetchMode::ASSOCIATIVE);
         $rows = array_map(static function ($row) {
             return array_change_key_case($row, CASE_LOWER);
@@ -102,6 +116,9 @@ public function testFetchAllWithNumericModes(): void
         $sql = 'SELECT test_int FROM legacy_table WHERE test_int = 1';
 
         $stmt = $this->connection->executeQuery($sql);
+
+        $this->expectDeprecationWithIdentifier('TODO');
+
         $rows = $stmt->fetchAll(FetchMode::NUMERIC);
         self::assertEquals([[0 => 1]], $rows);
     }
@@ -111,6 +128,9 @@ public function testFetchAllWithColumnMode(): void
         $sql = 'SELECT test_int FROM legacy_table WHERE test_int = 1';
 
         $stmt = $this->connection->executeQuery($sql);
+
+        $this->expectDeprecationWithIdentifier('TODO');
+
         $rows = $stmt->fetchAll(FetchMode::COLUMN);
         self::assertEquals([1], $rows);
     }
@@ -148,6 +168,9 @@ public function testExecuteUpdate(): void
         $sql = 'SELECT test_string FROM legacy_table';
 
         $stmt = $this->connection->executeQuery($sql);
+
+        $this->expectDeprecationWithIdentifier('TODO');
+
         $rows = $stmt->fetchAll(FetchMode::COLUMN);
         self::assertEquals(['foo', 'bar'], $rows);
     }