Merge 3.2.x into 3.3.x (#5068)

.github/workflows/continuous-integration.yml

@@ -38,10 +38,6 @@ jobs:
         with:
           fetch-depth: 2
 
-      - name: "Temporarily remove support for PSR Log 3 on PHP 8.1"
-        run: 'sed -i "s/\"psr\/log\": \"^1|^2|^3\"/\"psr\/log\": \"^1|^2\"/" composer.json'
-        if: "${{ matrix.php-version=='8.1' }}"
-
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:
@@ -86,10 +82,6 @@ jobs:
         with:
           fetch-depth: 2
 
-      - name: "Temporarily remove support for PSR Log 3 on PHP 8.1"
-        run: 'sed -i "s/\"psr\/log\": \"^1|^2|^3\"/\"psr\/log\": \"^1|^2\"/" composer.json'
-        if: "${{ matrix.php-version=='8.1' }}"
-
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:
@@ -133,10 +125,6 @@ jobs:
         with:
           fetch-depth: 2
 
-      - name: "Temporarily remove support for PSR Log 3 on PHP 8.1"
-        run: 'sed -i "s/\"psr\/log\": \"^1|^2|^3\"/\"psr\/log\": \"^1|^2\"/" composer.json'
-        if: "${{ matrix.php-version=='8.1' }}"
-
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:
@@ -192,10 +180,6 @@ jobs:
         with:
           fetch-depth: 2
 
-      - name: "Temporarily remove support for PSR Log 3 on PHP 8.1"
-        run: 'sed -i "s/\"psr\/log\": \"^1|^2|^3\"/\"psr\/log\": \"^1|^2\"/" composer.json'
-        if: "${{ matrix.php-version=='8.1' }}"
-
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:
@@ -258,10 +242,6 @@ jobs:
         with:
           fetch-depth: 2
 
-      - name: "Temporarily remove support for PSR Log 3 on PHP 8.1"
-        run: 'sed -i "s/\"psr\/log\": \"^1|^2|^3\"/\"psr\/log\": \"^1|^2\"/" composer.json'
-        if: "${{ matrix.php-version=='8.1' }}"
-
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:
@@ -350,10 +330,6 @@ jobs:
         with:
           fetch-depth: 2
 
-      - name: "Temporarily remove support for PSR Log 3 on PHP 8.1"
-        run: 'sed -i "s/\"psr\/log\": \"^1|^2|^3\"/\"psr\/log\": \"^1|^2\"/" composer.json'
-        if: "${{ matrix.php-version=='8.1' }}"
-
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:
@@ -422,10 +398,6 @@ jobs:
         with:
           fetch-depth: 2
 
-      - name: "Temporarily remove support for PSR Log 3 on PHP 8.1"
-        run: 'sed -i "s/\"psr\/log\": \"^1|^2|^3\"/\"psr\/log\": \"^1|^2\"/" composer.json'
-        if: "${{ matrix.php-version=='8.1' }}"
-
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:
@@ -483,10 +455,6 @@ jobs:
         with:
           fetch-depth: 2
 
-      - name: "Temporarily remove support for PSR Log 3 on PHP 8.1"
-        run: 'sed -i "s/\"psr\/log\": \"^1|^2|^3\"/\"psr\/log\": \"^1|^2\"/" composer.json'
-        if: "${{ matrix.php-version=='8.1' }}"
-
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:

UPGRADE.md

@@ -53,6 +53,14 @@ Call `getNativeConnection()` to access the underlying PDO or MySQLi connection.
 
 # Upgrade to 3.2
 
+## Minor BC Break: using cache keys with characters reserved by `psr/cache`
+
+We have been working on phasing out `doctrine/cache`, and 3.2.0 allows to use
+`psr/cache` instead. To help calling our own internal APIs in a unified way, we
+also wrap `doctrine/cache` implementations with a `psr/cache` adapter.
+Using cache keys containing characters reserved by `psr/cache` will result in
+an exception. The characters are the following: `{}()/\@`.
+
 ## Deprecated `SQLLogger` and its implementations.
 
 The `SQLLogger` and its implementations `DebugStack` and `LoggerChain` have been deprecated.

docs/en/explanation/dc2type-comments.rst

@@ -0,0 +1,39 @@
+Doctrine SQL comments
+=====================
+
+In some occasions DBAL generates ``DC2Type`` SQL comments in columns of
+the databases schemas that is maintained by Doctrine. These comments
+have a functional purpose in DBAL.
+
+``DC2`` is a shorthand for Doctrine 2, as opposed to `Doctrine 1
+<https://github.com/doctrine/doctrine1>`_,
+an ancestor that relied on `the active record pattern
+<https://en.wikipedia.org/wiki/Active_record_pattern>`_.
+
+These comments are here to help with reverse engineering. Inside the
+DBAL, the schema manager can leverage them to resolve ambiguities when
+it comes to determining the correct DBAL type for a given column.
+
+For instance: You are following a `Database First approach
+<https://www.doctrine-project.org/projects/doctrine-orm/en/current/tutorials/getting-started-database.html>`_,
+and want to use GUIDs in your application while using a platform that does not have a native type for
+this mapping.
+By commenting columns that hold GUIDs with ``(DC2Type:guid)``, you can
+let the DBAL know it is supposed to use ``Doctrine\DBAL\Types\GuidType``
+when dealing with that column.
+When using reverse engineering tools, this can be used to generate
+accurate information.
+For instance, if you use Doctrine ORM, there is `a reverse engineering example
+<https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/tools.html#reverse-engineering>`_
+to show how to generate a proper mapping.
+
+A table with such a column may have a declaration that looks as follows:
+
+.. code-block:: sql
+
+   CREATE TABLE "movies" (
+        uuid CHAR(36) NOT NULL, --(DC2Type:guid)
+        title varchar(255) NOT NULL
+        …,
+        PRIMARY KEY(uuid)
+   )

docs/en/sidebar.rst

@@ -20,4 +20,5 @@
     reference/upgrading
     reference/testing
 
+    explanation/dc2type-comments.rst
     explanation/implicit-indexes

src/Cache/ArrayResult.php

@@ -14,7 +14,7 @@
  */
 final class ArrayResult implements Result
 {
-    /** @var mixed[] */
+    /** @var list<array<string, mixed>> */
     private $data;
 
     /** @var int */
@@ -24,7 +24,7 @@ final class ArrayResult implements Result
     private $num = 0;
 
     /**
-     * @param mixed[] $data
+     * @param list<array<string, mixed>> $data
      */
     public function __construct(array $data)
     {
@@ -112,7 +112,7 @@ public function free(): void
     }
 
     /**
-     * @return mixed|false
+     * @return array<string, mixed>|false
      */
     private function fetch()
     {

src/Connection.php

@@ -75,7 +75,7 @@ class Connection
     protected $_eventManager;
 
     /**
-     * @deprecated Use {@link createExpressionBuilder()} instead.
+     * @deprecated Use {@see createExpressionBuilder()} instead.
      *
      * @var ExpressionBuilder
      */
@@ -134,7 +134,7 @@ class Connection
     /**
      * The schema manager.
      *
-     * @deprecated Use {@link createSchemaManager()} instead.
+     * @deprecated Use {@see createSchemaManager()} instead.
      *
      * @var AbstractSchemaManager|null
      */
@@ -294,7 +294,7 @@ public function createExpressionBuilder(): ExpressionBuilder
     /**
      * Gets the ExpressionBuilder for the connection.
      *
-     * @deprecated Use {@link createExpressionBuilder()} instead.
+     * @deprecated Use {@see createExpressionBuilder()} instead.
      *
      * @return ExpressionBuilder
      */
@@ -796,7 +796,7 @@ public function quoteIdentifier($str)
 
     /**
      * The usage of this method is discouraged. Use prepared statements
-     * or {@link AbstractPlatform::quoteStringLiteral()} instead.
+     * or {@see AbstractPlatform::quoteStringLiteral()} instead.
      *
      * @param mixed                $value
      * @param int|string|Type|null $type
@@ -1566,7 +1566,7 @@ public function createSchemaManager(): AbstractSchemaManager
      * Gets the SchemaManager that can be used to inspect or change the
      * database schema through the connection.
      *
-     * @deprecated Use {@link createSchemaManager()} instead.
+     * @deprecated Use {@see createSchemaManager()} instead.
      *
      * @return AbstractSchemaManager
      *

src/Driver/API/ExceptionConverter.php

@@ -14,12 +14,12 @@ interface ExceptionConverter
      * Converts a given driver-level exception into a DBAL-level driver exception.
      *
      * Implementors should use the vendor-specific error code and SQLSTATE of the exception
-     * and instantiate the most appropriate specialized {@link DriverException} subclass.
+     * and instantiate the most appropriate specialized {@see DriverException} subclass.
      *
      * @param Exception  $exception The driver exception to convert.
      * @param Query|null $query     The SQL query that triggered the exception, if any.
      *
-     * @return DriverException An instance of {@link DriverException} or one of its subclasses.
+     * @return DriverException An instance of {@see DriverException} or one of its subclasses.
      */
     public function convert(Exception $exception, ?Query $query): DriverException;
 }

src/Driver/AbstractDB2Driver.php

@@ -13,7 +13,7 @@
 use function assert;
 
 /**
- * Abstract base implementation of the {@link Driver} interface for IBM DB2 based drivers.
+ * Abstract base implementation of the {@see Driver} interface for IBM DB2 based drivers.
  */
 abstract class AbstractDB2Driver implements Driver
 {

src/Driver/AbstractException.php

@@ -8,7 +8,7 @@
 use Throwable;
 
 /**
- * Base implementation of the {@link Exception} interface.
+ * Base implementation of the {@see Exception} interface.
  *
  * @internal
  *

src/Driver/AbstractMySQLDriver.php

@@ -20,7 +20,7 @@
 use function version_compare;
 
 /**
- * Abstract base implementation of the {@link Driver} interface for MySQL based drivers.
+ * Abstract base implementation of the {@see Driver} interface for MySQL based drivers.
  */
 abstract class AbstractMySQLDriver implements VersionAwarePlatformDriver
 {

src/Driver/AbstractOracleDriver.php

@@ -14,7 +14,7 @@
 use function assert;
 
 /**
- * Abstract base implementation of the {@link Driver} interface for Oracle based drivers.
+ * Abstract base implementation of the {@see Driver} interface for Oracle based drivers.
  */
 abstract class AbstractOracleDriver implements Driver
 {

src/Driver/AbstractPostgreSQLDriver.php

@@ -18,7 +18,7 @@
 use function version_compare;
 
 /**
- * Abstract base implementation of the {@link Driver} interface for PostgreSQL based drivers.
+ * Abstract base implementation of the {@see Driver} interface for PostgreSQL based drivers.
  */
 abstract class AbstractPostgreSQLDriver implements VersionAwarePlatformDriver
 {

src/Driver/AbstractSQLServerDriver.php

@@ -13,7 +13,7 @@
 use function assert;
 
 /**
- * Abstract base implementation of the {@link Driver} interface for Microsoft SQL Server based drivers.
+ * Abstract base implementation of the {@see Driver} interface for Microsoft SQL Server based drivers.
  */
 abstract class AbstractSQLServerDriver implements Driver
 {

src/Driver/AbstractSQLiteDriver.php

@@ -13,7 +13,7 @@
 use function assert;
 
 /**
- * Abstract base implementation of the {@link Doctrine\DBAL\Driver} interface for SQLite based drivers.
+ * Abstract base implementation of the {@see Doctrine\DBAL\Driver} interface for SQLite based drivers.
  */
 abstract class AbstractSQLiteDriver implements Driver
 {

src/Driver/Connection.php

@@ -30,7 +30,7 @@ public function query(string $sql): Result;
      * Quotes a string for use in a query.
      *
      * The usage of this method is discouraged. Use prepared statements
-     * or {@link AbstractPlatform::quoteStringLiteral()} instead.
+     * or {@see AbstractPlatform::quoteStringLiteral()} instead.
      *
      * @param mixed $value
      * @param int   $type

src/Driver/ServerInfoAwareConnection.php

@@ -5,7 +5,7 @@
 /**
  * Contract for a connection that is able to provide information about the server it is connected to.
  *
- * @deprecated The methods defined in this interface will be made part of the {@link Driver} interface
+ * @deprecated The methods defined in this interface will be made part of the {@see Driver} interface
  * in the next major release.
  */
 interface ServerInfoAwareConnection extends Connection

src/Driver/Statement.php

@@ -20,7 +20,7 @@ interface Statement
      *                          this will be a parameter name of the form :name. For a prepared statement
      *                          using question mark placeholders, this will be the 1-indexed position of the parameter.
      * @param mixed      $value The value to bind to the parameter.
-     * @param int        $type  Explicit data type for the parameter using the {@link ParameterType}
+     * @param int        $type  Explicit data type for the parameter using the {@see ParameterType}
      *                          constants.
      *
      * @return bool TRUE on success or FALSE on failure.
@@ -31,7 +31,7 @@ public function bindValue($param, $value, $type = ParameterType::STRING);
 
     /**
      * Binds a PHP variable to a corresponding named (not supported by mysqli driver, see comment below) or question
-     * mark placeholder in the SQL statement that was use to prepare the statement. Unlike {@link bindValue()},
+     * mark placeholder in the SQL statement that was use to prepare the statement. Unlike {@see bindValue()},
      * the variable is bound as a reference and will only be evaluated at the time
      * that PDOStatement->execute() is called.
      *
@@ -47,7 +47,7 @@ public function bindValue($param, $value, $type = ParameterType::STRING);
      *                             this will be a parameter name of the form :name. For a prepared statement using
      *                             question mark placeholders, this will be the 1-indexed position of the parameter.
      * @param mixed      $variable Name of the PHP variable to bind to the SQL statement parameter.
-     * @param int        $type     Explicit data type for the parameter using the {@link ParameterType}
+     * @param int        $type     Explicit data type for the parameter using the {@see ParameterType}
      *                             constants.
      * @param int|null   $length   You must specify maxlength when using an OUT bind
      *                             so that PHP allocates enough memory to hold the returned value.
@@ -62,7 +62,7 @@ public function bindParam($param, &$variable, $type = ParameterType::STRING, $le
      * Executes a prepared statement
      *
      * If the prepared statement included parameter markers, you must either:
-     * call {@link bindParam()} to bind PHP variables to the parameter markers:
+     * call {@see bindParam()} to bind PHP variables to the parameter markers:
      * bound variables pass their value as input and receive the output value,
      * if any, of their associated parameter markers or pass an array of input-only
      * parameter values.