Merge branch '4.3.x' into 5.0.x

UPGRADE.md

@@ -213,6 +213,24 @@ all drivers and middleware.
 
 # Upgrade to 4.3
 
+## Deprecated handling of modified indexes in `TableDiff`
+
+Passing a non-empty `$modifiedIndexes` value to the `TableDiff` constructor is deprecated. Instead, pass dropped
+indexes via `$droppedIndexes` and added indexes via `$addedIndexes`.
+
+The `TableDiff::getModifiedIndexes()` method has been deprecated. The old version of the index is included in the return
+value of `TableDiff::getDroppedIndexes()`, the new version is included in the return value of
+`TableDiff::getAddedIndexes()`.
+
+## Deprecated handling of modified foreign keys in `TableDiff`
+
+Passing a non-empty `$modifiedForeignKeys` value to the `TableDiff` constructor is deprecated. Instead, pass dropped
+constraints via `$droppedForeignKeys` and added constraints via `$addedForeignKeys`.
+
+The `TableDiff::getModifiedForeignKeys()` method has been deprecated. The old version of the foreign key constraint is
+included in the return value of `TableDiff::getDroppedForeignKeys()`, the new version is included in the return value of
+`TableDiff::getAddedForeignKeys()`.
+
 ## Deprecated not passing `$options` to `AbstractPlatform::_getCreateTableSQL()`
 
 Not passing the `$options` argument or any of its following keys to the `AbstractPlatform::_getCreateTableSQL()` method

phpstan.neon.dist

@@ -7,9 +7,29 @@ parameters:
         - tests
     treatPhpDocTypesAsCertain: false
     reportUnmatchedIgnoredErrors: false
+    exceptions:
+        check:
+            missingCheckedExceptionInThrows: true
+        uncheckedExceptionClasses:
+            - ErrorException
+            - LogicException
+            - RuntimeException
     ignoreErrors:
         - identifier: missingType.generics
 
+        # Ignore missing declarations of checked exceptions in tests
+        -
+            identifier: missingType.checkedException
+            paths:
+                - static-analysis
+                - tests
+
+        # PHPStan reports these errors in the methods that call BackedEnum::from() even if the line is annotated with
+        # @phpstan-ignore missingType.checkedException.
+        -
+            message: '~^Method .* throws checked exception (Type|Value)Error but it''s missing from the PHPDoc @throws tag.~'
+
+
         # https://github.com/phpstan/phpstan-strict-rules/issues/103
         -
             message: '~^Construct empty\(\) is not allowed. Use more strict comparison\.~'

src/Connection.php

@@ -20,6 +20,7 @@
 use Doctrine\DBAL\Exception\DriverException;
 use Doctrine\DBAL\Exception\ForeignKeyConstraintViolationException;
 use Doctrine\DBAL\Exception\NoActiveTransaction;
+use Doctrine\DBAL\Exception\ParseError;
 use Doctrine\DBAL\Exception\SavepointsNotSupported;
 use Doctrine\DBAL\Exception\TransactionRolledBack;
 use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
@@ -268,8 +269,7 @@ public function isAutoCommit(): bool
      *
      * @see isAutoCommit
      *
-     * @throws ConnectionException
-     * @throws DriverException
+     * @throws Exception
      */
     public function setAutoCommit(bool $autoCommit): void
     {
@@ -555,6 +555,8 @@ public function quoteSingleIdentifier(string $identifier): string
     /**
      * The usage of this method is discouraged. Use prepared statements
      * or {@see AbstractPlatform::quoteStringLiteral()} instead.
+     *
+     * @throws Exception
      */
     public function quote(string $value): string
     {
@@ -801,6 +803,7 @@ public function executeCacheQuery(string $sql, array $params, array $types, Quer
 
         [$cacheKey, $realKey] = $qcp->generateCacheKeys($sql, $params, $types, $connectionParams);
 
+        // @phpstan-ignore missingType.checkedException
         $item = $resultCache->getItem($cacheKey);
 
         if ($item->isHit()) {
@@ -1056,6 +1059,7 @@ public function commit(): void
         }
     }
 
+    /** @throws Exception */
     private function updateTransactionStateAfterCommit(): void
     {
         if ($this->transactionNestingLevel !== 0) {
@@ -1283,7 +1287,11 @@ private function bindParameters(DriverStatement $stmt, array $params, array $typ
                     $bindingType = ParameterType::STRING;
                 }
 
-                $stmt->bindValue($bindIndex, $value, $bindingType);
+                try {
+                    $stmt->bindValue($bindIndex, $value, $bindingType);
+                } catch (Driver\Exception $e) {
+                    throw $this->convertException($e);
+                }
 
                 ++$bindIndex;
             }
@@ -1297,7 +1305,11 @@ private function bindParameters(DriverStatement $stmt, array $params, array $typ
                     $bindingType = ParameterType::STRING;
                 }
 
-                $stmt->bindValue($name, $value, $bindingType);
+                try {
+                    $stmt->bindValue($name, $value, $bindingType);
+                } catch (Driver\Exception $e) {
+                    throw $this->convertException($e);
+                }
             }
         }
     }
@@ -1366,6 +1378,8 @@ final public function convertException(Driver\Exception $e): DriverException
      *     list<mixed>|array<string, mixed>,
      *     array<int<0, max>, string|ParameterType|Type>|array<string, string|ParameterType|Type>
      * }
+     *
+     * @throws Exception
      */
     private function expandArrayParameters(string $sql, array $params, array $types): array
     {
@@ -1392,7 +1406,11 @@ private function expandArrayParameters(string $sql, array $params, array $types)
         $this->parser ??= $this->getDatabasePlatform()->createSQLParser();
         $visitor        = new ExpandArrayParameters($params, $types);
 
-        $this->parser->parse($sql, $visitor);
+        try {
+            $this->parser->parse($sql, $visitor);
+        } catch (Parser\Exception $e) {
+            throw ParseError::fromParserException($e);
+        }
 
         return [
             $visitor->getSQL(),

src/Connections/PrimaryReadReplicaConnection.php

@@ -141,6 +141,7 @@ public function connect(?string $connectionName = null): DriverConnection
         return $this->performConnect();
     }
 
+    /** @throws Exception */
     protected function performConnect(?string $connectionName = null): DriverConnection
     {
         $requestedConnectionChange = ($connectionName !== null);
@@ -192,6 +193,8 @@ protected function performConnect(?string $connectionName = null): DriverConnect
      * Connects to the primary node of the database cluster.
      *
      * All following statements after this will be executed against the primary node.
+     *
+     * @throws Exception
      */
     public function ensureConnectedToPrimary(): void
     {
@@ -204,6 +207,8 @@ public function ensureConnectedToPrimary(): void
      * All following statements after this will be executed against the replica node,
      * unless the keepReplica option is set to false and a primary connection
      * was already opened.
+     *
+     * @throws Exception
      */
     public function ensureConnectedToReplica(): void
     {

src/Driver.php

@@ -8,6 +8,7 @@
 use Doctrine\DBAL\Driver\Connection as DriverConnection;
 use Doctrine\DBAL\Driver\Exception;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Platforms\Exception\PlatformException;
 use SensitiveParameter;
 
 /**
@@ -38,6 +39,8 @@ public function connect(
      * the platform this driver connects to.
      *
      * @return AbstractPlatform The database platform.
+     *
+     * @throws PlatformException
      */
     public function getDatabasePlatform(ServerVersionProvider $versionProvider): AbstractPlatform;
 

src/Driver/PDO/Result.php

@@ -75,6 +75,7 @@ public function columnCount(): int
         }
     }
 
+    /** @throws Exception */
     public function getColumnName(int $index): string
     {
         try {

src/Driver/PgSQL/Connection.php

@@ -41,6 +41,8 @@ public function __destruct()
     public function prepare(string $sql): Statement
     {
         $visitor = new ConvertParameters();
+
+        /** @phpstan-ignore missingType.checkedException */
         $this->parser->parse($sql, $visitor);
 
         $statementName = uniqid('dbal', true);

src/Exception/ParseError.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Exception;
+
+use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\SQL\Parser;
+
+/** @internal */
+final class ParseError extends \Exception implements Exception
+{
+    public static function fromParserException(Parser\Exception $exception): self
+    {
+        return new self('Unable to parse query.', 0, $exception);
+    }
+}

src/Platforms/AbstractMySQLPlatform.php

@@ -5,7 +5,6 @@
 namespace Doctrine\DBAL\Platforms;
 
 use Doctrine\DBAL\Connection;
-use Doctrine\DBAL\Exception;
 use Doctrine\DBAL\Exception\InvalidColumnType\ColumnValuesRequired;
 use Doctrine\DBAL\Schema\AbstractAsset;
 use Doctrine\DBAL\Schema\ForeignKeyConstraint;
@@ -461,11 +460,7 @@ protected function getPreAlterTableIndexForeignKeySQL(TableDiff $diff): array
         );
     }
 
-    /**
-     * @return list<string>
-     *
-     * @throws Exception
-     */
+    /** @return list<string> */
     private function getPreAlterTableAlterPrimaryKeySQL(TableDiff $diff, Index $index): array
     {
         if (! $index->isPrimary()) {
@@ -506,8 +501,6 @@ private function getPreAlterTableAlterPrimaryKeySQL(TableDiff $diff, Index $inde
      * @param TableDiff $diff The table diff to gather the SQL for.
      *
      * @return list<string>
-     *
-     * @throws Exception
      */
     private function getPreAlterTableAlterIndexForeignKeySQL(TableDiff $diff): array
     {

src/Platforms/AbstractPlatform.php

@@ -40,6 +40,7 @@
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types;
 use Doctrine\DBAL\Types\Exception\TypeNotFound;
+use Doctrine\DBAL\Types\Exception\TypesException;
 use Doctrine\DBAL\Types\Type;
 
 use function addcslashes;
@@ -134,6 +135,8 @@ abstract protected function initializeDoctrineTypeMappings(): void;
     /**
      * Initializes Doctrine Type Mappings with the platform defaults
      * and with all additional type mappings.
+     *
+     * @throws TypesException
      */
     private function initializeAllDoctrineTypeMappings(): void
     {
@@ -345,6 +348,8 @@ public function registerDoctrineTypeMapping(string $dbType, string $doctrineType
 
     /**
      * Gets the Doctrine type that is mapped for the given database column type.
+     *
+     * @throws TypesException
      */
     public function getDoctrineTypeMapping(string $dbType): string
     {
@@ -367,6 +372,8 @@ public function getDoctrineTypeMapping(string $dbType): string
 
     /**
      * Checks if a database type is currently supported by this platform.
+     *
+     * @throws TypesException
      */
     public function hasDoctrineTypeMappingFor(string $dbType): bool
     {

src/Platforms/PostgreSQLPlatform.php

@@ -356,14 +356,14 @@ public function getDropForeignKeySQL(string $foreignKey, string $table): string
 
     public function getDropIndexSQL(string $name, string $table): string
     {
-        if ($name === '"primary"') {
-            if (str_ends_with($table, '"')) {
-                $constraintName = substr($table, 0, -1) . '_pkey"';
-            } else {
-                $constraintName = $table . '_pkey';
-            }
+        if (str_ends_with($table, '"')) {
+            $primaryKeyName = substr($table, 0, -1) . '_pkey"';
+        } else {
+            $primaryKeyName = $table . '_pkey';
+        }
 
-            return $this->getDropConstraintSQL($constraintName, $table);
+        if ($name === '"primary"' || $name === $primaryKeyName) {
+            return $this->getDropConstraintSQL($primaryKeyName, $table);
         }
 
         if (str_contains($table, '.')) {

src/Platforms/SQLitePlatform.php

@@ -5,7 +5,6 @@
 namespace Doctrine\DBAL\Platforms;
 
 use Doctrine\DBAL\Connection;
-use Doctrine\DBAL\Exception;
 use Doctrine\DBAL\Platforms\Exception\NotSupported;
 use Doctrine\DBAL\Schema\Column;
 use Doctrine\DBAL\Schema\Exception\ColumnDoesNotExist;
@@ -685,8 +684,6 @@ public function getAlterTableSQL(TableDiff $diff): array
      * @param array<string,Column> $columns
      *
      * @return array<string,Column>
-     *
-     * @throws Exception
      */
     private function replaceColumn(string $tableName, array $columns, string $columnName, Column $column): array
     {
@@ -705,11 +702,7 @@ private function replaceColumn(string $tableName, array $columns, string $column
         return array_combine($keys, $values);
     }
 
-    /**
-     * @return list<string>|false
-     *
-     * @throws Exception
-     */
+    /** @return list<string>|false */
     private function getSimpleAlterTableSQL(TableDiff $diff): array|false
     {
         if (

src/Portability/Driver.php

@@ -7,7 +7,9 @@
 use Doctrine\DBAL\ColumnCase;
 use Doctrine\DBAL\Driver as DriverInterface;
 use Doctrine\DBAL\Driver\Connection as ConnectionInterface;
+use Doctrine\DBAL\Driver\Exception;
 use Doctrine\DBAL\Driver\Middleware\AbstractDriverMiddleware;
+use Doctrine\DBAL\Platforms\Exception\PlatformException;
 use PDO;
 use SensitiveParameter;
 
@@ -26,6 +28,9 @@ public function __construct(
 
     /**
      * {@inheritDoc}
+     *
+     * @throws PlatformException
+     * @throws Exception
      */
     public function connect(
         #[SensitiveParameter]

src/Query/CommonTableExpression.php

@@ -10,7 +10,11 @@
 /** @internal */
 final class CommonTableExpression
 {
-    /** @param string[]|null $columns */
+    /**
+     * @param string[]|null $columns
+     *
+     * @throws QueryException
+     */
     public function __construct(
         public readonly string $name,
         public readonly string|QueryBuilder $query,

src/Query/Expression/ExpressionBuilder.php

@@ -5,6 +5,7 @@
 namespace Doctrine\DBAL\Query\Expression;
 
 use Doctrine\DBAL\Connection;
+use Doctrine\DBAL\Exception;
 
 use function implode;
 use function sprintf;
@@ -236,6 +237,8 @@ public function notIn(string $x, string|array $y): string
      *
      * The usage of this method is discouraged. Use prepared statements
      * or {@see AbstractPlatform::quoteStringLiteral()} instead.
+     *
+     * @throws Exception
      */
     public function literal(string $input): string
     {