Make doctrine/cache optional (#6740)

|      Q       |   A
|------------- | -----------
| Type         | improvement
| Fixed issues | N/A

#### Summary

We'd like to flag the the doctrine/cache package as abandoned which
means it needs to disappear from the list of mandatory dependencies of
DBAL. In DBAL 3.9, the doctrine/cache classes are used for deprecated
code paths only.

Note: This change could break downstream projects if they rely on DBAL
installing the Cache package for them.

Author: derrabus

.github/workflows/continuous-integration.yml

@@ -43,15 +43,16 @@ jobs:
         dependencies:
           - "highest"
         extension:
+          - "sqlite3"
           - "pdo_sqlite"
         include:
           - os: "ubuntu-20.04"
             php-version: "7.4"
             dependencies: "lowest"
             extension: "pdo_sqlite"
           - os: "ubuntu-22.04"
-            php-version: "7.4"
-            dependencies: "highest"
+            php-version: "8.4"
+            dependencies: "minimal"
             extension: "sqlite3"
 
     steps:
@@ -60,6 +61,10 @@ jobs:
         with:
           fetch-depth: 2
 
+      - name: "Remove optional dependencies"
+        run: "composer remove --no-update --dev doctrine/cache"
+        if: "${{ matrix.dependencies == 'minimal' }}"
+
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:
@@ -71,7 +76,7 @@ jobs:
         uses: "ramsey/composer-install@v3"
         with:
           composer-options: "--ignore-platform-req=php+"
-          dependency-versions: "${{ matrix.dependencies }}"
+          dependency-versions: "${{ matrix.dependencies == 'minimal' && 'highest' || matrix.dependencies }}"
 
       - name: "Print SQLite version"
         run: >

UPGRADE.md

@@ -6,6 +6,12 @@ awareness about deprecated code.
 - Use of our low-overhead runtime deprecation API, details:
   https://github.com/doctrine/deprecations/
 
+# Upgrade to 3.10
+
+The `doctrine/cache` package is now an optional dependency. If you are using the
+`Doctrine\DBAL\Cache` classes, you need to require the `doctrine/cache` package
+explicitly.
+
 # Upgrade to 3.8
 
 ## Deprecated lock-related `AbstractPlatform` methods

composer.json

@@ -33,13 +33,13 @@
     "require": {
         "php": "^7.4 || ^8.0",
         "composer-runtime-api": "^2",
-        "doctrine/cache": "^1.11|^2.0",
         "doctrine/deprecations": "^0.5.3|^1",
         "doctrine/event-manager": "^1|^2",
         "psr/cache": "^1|^2|^3",
         "psr/log": "^1|^2|^3"
     },
     "require-dev": {
+        "doctrine/cache": "^1.11|^2.0",
         "doctrine/coding-standard": "12.0.0",
         "fig/log-test": "^1",
         "jetbrains/phpstorm-stubs": "2023.1",
@@ -51,6 +51,9 @@
         "symfony/cache": "^5.4|^6.0|^7.0",
         "symfony/console": "^4.4|^5.4|^6.0|^7.0"
     },
+    "conflict": {
+        "doctrine/cache": "< 1.11"
+    },
     "suggest": {
         "symfony/console": "For helpful console commands such as SQL execution and import of files."
     },

src/Cache/QueryCacheProfile.php

@@ -8,8 +8,10 @@
 use Doctrine\DBAL\Types\Type;
 use Doctrine\Deprecations\Deprecation;
 use Psr\Cache\CacheItemPoolInterface;
+use RuntimeException;
 use TypeError;
 
+use function class_exists;
 use function get_class;
 use function hash;
 use function serialize;
@@ -82,7 +84,19 @@ public function getResultCacheDriver()
             __METHOD__,
         );
 
-        return $this->resultCache !== null ? DoctrineProvider::wrap($this->resultCache) : null;
+        if ($this->resultCache === null) {
+            return null;
+        }
+
+        if (! class_exists(DoctrineProvider::class)) {
+            throw new RuntimeException(sprintf(
+                'Calling %s() is not supported if the doctrine/cache package is not installed. '
+                    . 'Try running "composer require doctrine/cache" or migrate cache access to PSR-6.',
+                __METHOD__,
+            ));
+        }
+
+        return DoctrineProvider::wrap($this->resultCache);
     }
 
     /** @return int */

src/Configuration.php

@@ -10,8 +10,12 @@
 use Doctrine\DBAL\Schema\SchemaManagerFactory;
 use Doctrine\Deprecations\Deprecation;
 use Psr\Cache\CacheItemPoolInterface;
+use RuntimeException;
 
+use function class_exists;
 use function func_num_args;
+use function interface_exists;
+use function sprintf;
 
 /**
  * Configuration container for the Doctrine DBAL.
@@ -129,6 +133,14 @@ public function getResultCacheImpl(): ?Cache
             __METHOD__,
         );
 
+        if ($this->resultCache !== null && ! interface_exists(Cache::class)) {
+            throw new RuntimeException(sprintf(
+                'Calling %s() is not supported if the doctrine/cache package is not installed. '
+                . 'Try running "composer require doctrine/cache" or migrate cache access to PSR-6.',
+                __METHOD__,
+            ));
+        }
+
         return $this->resultCacheImpl;
     }
 
@@ -137,8 +149,11 @@ public function getResultCacheImpl(): ?Cache
      */
     public function setResultCache(CacheItemPoolInterface $cache): void
     {
-        $this->resultCacheImpl = DoctrineProvider::wrap($cache);
-        $this->resultCache     = $cache;
+        if (class_exists(DoctrineProvider::class)) {
+            $this->resultCacheImpl = DoctrineProvider::wrap($cache);
+        }
+
+        $this->resultCache = $cache;
     }
 
     /**

tests/Connection/CachedQueryTest.php

@@ -40,6 +40,10 @@ public function testCachedQueryLegacy(): void
 
     public function testCachedQueryLegacyWrapped(): void
     {
+        if (! class_exists(DoctrineProvider::class)) {
+            self::markTestSkipped('This test requires the doctrine/cache package.');
+        }
+
         $cache  = new ArrayAdapter();
         $legacy = DoctrineProvider::wrap($cache);
         $this->assertCachedQueryIsExecutedOnceAndYieldsTheSameResult($legacy, __FUNCTION__);