Merge pull request #3560 from morozov/driver-types

Enforced parameter and return value types in Driver classes

UPGRADE.md

 # Upgrade to 3.0
 
+## BC BREAK: Changes in the `Doctrine\DBAL\Driver` API
+
+1. The `$username` and `$password` arguments of `::connect()` are no longer nullable. Use an empty string to indicate empty username or password.
+2. The return value of `::getDatabase()` has been documented as nullable since some of the drivers allow establishing a connection without selecting a database.
+
 ## BC BREAK: `Doctrine\DBAL\Driver::getName()` removed
 
 The `Doctrine\DBAL\Driver::getName()` has been removed.

lib/Doctrine/DBAL/Connection.php

@@ -330,8 +330,8 @@ class Connection implements DriverConnection
         }
 
         $driverOptions = $this->params['driverOptions'] ?? [];
-        $user          = $this->params['user'] ?? null;
-        $password      = $this->params['password'] ?? null;
+        $user          = $this->params['user'] ?? '';
+        $password      = $this->params['password'] ?? '';
 
         $this->_conn       = $this->_driver->connect($this->params, $user, $password, $driverOptions);
         $this->isConnected = true;

lib/Doctrine/DBAL/Connections/MasterSlaveConnection.php

@@ -192,8 +192,8 @@ class MasterSlaveConnection extends Connection
 
         $connectionParams = $this->chooseConnectionConfiguration($connectionName, $params);
 
-        $user     = $connectionParams['user'] ?? null;
-        $password = $connectionParams['password'] ?? null;
+        $user     = $connectionParams['user'] ?? '';
+        $password = $connectionParams['password'] ?? '';
 
         return $this->_driver->connect($connectionParams, $user, $password, $driverOptions);
     }

lib/Doctrine/DBAL/Driver.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Doctrine\DBAL;
 
+use Doctrine\DBAL\Driver\Connection as DriverConnection;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Schema\AbstractSchemaManager;
 
@@ -16,16 +17,19 @@ interface Driver
     /**
      * Attempts to create a connection with the database.
      *
-     * The usage of NULL to indicate empty username or password is deprecated. Use an empty string instead.
+     * @param mixed[] $params        All connection parameters passed by the user.
+     * @param string  $username      The username to use when connecting.
+     * @param string  $password      The password to use when connecting.
+     * @param mixed[] $driverOptions The driver options to use when connecting.
      *
-     * @param mixed[]     $params        All connection parameters passed by the user.
-     * @param string|null $username      The username to use when connecting.
-     * @param string|null $password      The password to use when connecting.
-     * @param mixed[]     $driverOptions The driver options to use when connecting.
-     *
-     * @return \Doctrine\DBAL\Driver\Connection The database connection.
+     * @return DriverConnection The database connection.
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = []);
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : DriverConnection;
 
     /**
      * Gets the DatabasePlatform instance that provides all the metadata about
@@ -33,20 +37,18 @@ interface Driver
      *
      * @return AbstractPlatform The database platform.
      */
-    public function getDatabasePlatform();
+    public function getDatabasePlatform() : AbstractPlatform;
 
     /**
      * Gets the SchemaManager that can be used to inspect and change the underlying
      * database schema of the platform this driver connects to.
-     *
-     * @return AbstractSchemaManager
      */
-    public function getSchemaManager(Connection $conn);
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager;
 
     /**
      * Gets the name of the database connected to for this driver.
      *
-     * @return string The name of the database.
+     * @return string The name of the database or NULL if no database is currently selected.
      */
-    public function getDatabase(Connection $conn);
+    public function getDatabase(Connection $conn) : ?string;
 }

lib/Doctrine/DBAL/Driver/AbstractDB2Driver.php

@@ -6,7 +6,9 @@ namespace Doctrine\DBAL\Driver;
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Platforms\DB2Platform;
+use Doctrine\DBAL\Schema\AbstractSchemaManager;
 use Doctrine\DBAL\Schema\DB2SchemaManager;
 
 /**
@@ -17,7 +19,7 @@ abstract class AbstractDB2Driver implements Driver
     /**
      * {@inheritdoc}
      */
-    public function getDatabase(Connection $conn)
+    public function getDatabase(Connection $conn) : ?string
     {
         $params = $conn->getParams();
 
@@ -27,7 +29,7 @@ abstract class AbstractDB2Driver implements Driver
     /**
      * {@inheritdoc}
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new DB2Platform();
     }
@@ -35,7 +37,7 @@ abstract class AbstractDB2Driver implements Driver
     /**
      * {@inheritdoc}
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new DB2SchemaManager($conn);
     }

lib/Doctrine/DBAL/Driver/AbstractMySQLDriver.php

@@ -7,12 +7,16 @@ namespace Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Driver\DriverException as DriverExceptionInterface;
 use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\Exception\DriverException;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Platforms\Exception\InvalidPlatformVersion;
 use Doctrine\DBAL\Platforms\MariaDb1027Platform;
 use Doctrine\DBAL\Platforms\MySQL57Platform;
 use Doctrine\DBAL\Platforms\MySQL80Platform;
 use Doctrine\DBAL\Platforms\MySqlPlatform;
+use Doctrine\DBAL\Schema\AbstractSchemaManager;
 use Doctrine\DBAL\Schema\MySqlSchemaManager;
 use Doctrine\DBAL\VersionAwarePlatformDriver;
 use function preg_match;
@@ -30,7 +34,7 @@ abstract class AbstractMySQLDriver implements Driver, ExceptionConverterDriver,
      * @link http://dev.mysql.com/doc/refman/5.7/en/error-messages-client.html
      * @link http://dev.mysql.com/doc/refman/5.7/en/error-messages-server.html
      */
-    public function convertException($message, DriverException $exception)
+    public function convertException(string $message, DriverExceptionInterface $exception) : DriverException
     {
         switch ($exception->getCode()) {
             case 1213:
@@ -106,7 +110,7 @@ abstract class AbstractMySQLDriver implements Driver, ExceptionConverterDriver,
                 return new Exception\NotNullConstraintViolationException($message, $exception);
         }
 
-        return new Exception\DriverException($message, $exception);
+        return new DriverException($message, $exception);
     }
 
     /**
@@ -114,7 +118,7 @@ abstract class AbstractMySQLDriver implements Driver, ExceptionConverterDriver,
      *
      * @throws DBALException
      */
-    public function createDatabasePlatformForVersion($version)
+    public function createDatabasePlatformForVersion(string $version) : AbstractPlatform
     {
         $mariadb = stripos($version, 'mariadb') !== false;
         if ($mariadb && version_compare($this->getMariaDbMysqlVersionNumber($version), '10.2.7', '>=')) {
@@ -192,7 +196,7 @@ abstract class AbstractMySQLDriver implements Driver, ExceptionConverterDriver,
     /**
      * {@inheritdoc}
      */
-    public function getDatabase(Connection $conn)
+    public function getDatabase(Connection $conn) : ?string
     {
         $params = $conn->getParams();
 
@@ -204,7 +208,7 @@ abstract class AbstractMySQLDriver implements Driver, ExceptionConverterDriver,
      *
      * @return MySqlPlatform
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new MySqlPlatform();
     }
@@ -214,7 +218,7 @@ abstract class AbstractMySQLDriver implements Driver, ExceptionConverterDriver,
      *
      * @return MySqlSchemaManager
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new MySqlSchemaManager($conn);
     }

lib/Doctrine/DBAL/Driver/AbstractOracleDriver.php

@@ -7,8 +7,12 @@ namespace Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Driver\AbstractOracleDriver\EasyConnectString;
+use Doctrine\DBAL\Driver\DriverException as DriverExceptionInterface;
 use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\Exception\DriverException;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Platforms\OraclePlatform;
+use Doctrine\DBAL\Schema\AbstractSchemaManager;
 use Doctrine\DBAL\Schema\OracleSchemaManager;
 
 /**
@@ -19,7 +23,7 @@ abstract class AbstractOracleDriver implements Driver, ExceptionConverterDriver
     /**
      * {@inheritdoc}
      */
-    public function convertException($message, DriverException $exception)
+    public function convertException(string $message, DriverExceptionInterface $exception) : DriverException
     {
         switch ($exception->getCode()) {
             case 1:
@@ -56,13 +60,13 @@ abstract class AbstractOracleDriver implements Driver, ExceptionConverterDriver
                 return new Exception\ForeignKeyConstraintViolationException($message, $exception);
         }
 
-        return new Exception\DriverException($message, $exception);
+        return new DriverException($message, $exception);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getDatabase(Connection $conn)
+    public function getDatabase(Connection $conn) : ?string
     {
         $params = $conn->getParams();
 
@@ -72,7 +76,7 @@ abstract class AbstractOracleDriver implements Driver, ExceptionConverterDriver
     /**
      * {@inheritdoc}
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new OraclePlatform();
     }
@@ -80,7 +84,7 @@ abstract class AbstractOracleDriver implements Driver, ExceptionConverterDriver
     /**
      * {@inheritdoc}
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new OracleSchemaManager($conn);
     }
@@ -89,10 +93,8 @@ abstract class AbstractOracleDriver implements Driver, ExceptionConverterDriver
      * Returns an appropriate Easy Connect String for the given parameters.
      *
      * @param mixed[] $params The connection parameters to return the Easy Connect String for.
-     *
-     * @return string
      */
-    protected function getEasyConnectString(array $params)
+    protected function getEasyConnectString(array $params) : string
     {
         return (string) EasyConnectString::fromConnectionParameters($params);
     }

lib/Doctrine/DBAL/Driver/AbstractPostgreSQLDriver.php

@@ -6,11 +6,15 @@ namespace Doctrine\DBAL\Driver;
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Driver\DriverException as DriverExceptionInterface;
 use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\Exception\DriverException;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Platforms\Exception\InvalidPlatformVersion;
 use Doctrine\DBAL\Platforms\PostgreSQL100Platform;
 use Doctrine\DBAL\Platforms\PostgreSQL94Platform;
 use Doctrine\DBAL\Platforms\PostgreSqlPlatform;
+use Doctrine\DBAL\Schema\AbstractSchemaManager;
 use Doctrine\DBAL\Schema\PostgreSqlSchemaManager;
 use Doctrine\DBAL\VersionAwarePlatformDriver;
 use function preg_match;
@@ -27,7 +31,7 @@ abstract class AbstractPostgreSQLDriver implements Driver, ExceptionConverterDri
      *
      * @link http://www.postgresql.org/docs/9.3/static/errcodes-appendix.html
      */
-    public function convertException($message, DriverException $exception)
+    public function convertException(string $message, DriverExceptionInterface $exception) : DriverException
     {
         switch ($exception->getSQLState()) {
             case '40001':
@@ -73,13 +77,13 @@ abstract class AbstractPostgreSQLDriver implements Driver, ExceptionConverterDri
             return new Exception\ConnectionException($message, $exception);
         }
 
-        return new Exception\DriverException($message, $exception);
+        return new DriverException($message, $exception);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function createDatabasePlatformForVersion($version)
+    public function createDatabasePlatformForVersion(string $version) : AbstractPlatform
     {
         if (! preg_match('/^(?P<major>\d+)(?:\.(?P<minor>\d+)(?:\.(?P<patch>\d+))?)?/', $version, $versionParts)) {
             throw InvalidPlatformVersion::new(
@@ -106,7 +110,7 @@ abstract class AbstractPostgreSQLDriver implements Driver, ExceptionConverterDri
     /**
      * {@inheritdoc}
      */
-    public function getDatabase(Connection $conn)
+    public function getDatabase(Connection $conn) : ?string
     {
         $params = $conn->getParams();
 
@@ -116,7 +120,7 @@ abstract class AbstractPostgreSQLDriver implements Driver, ExceptionConverterDri
     /**
      * {@inheritdoc}
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new PostgreSqlPlatform();
     }
@@ -124,7 +128,7 @@ abstract class AbstractPostgreSQLDriver implements Driver, ExceptionConverterDri
     /**
      * {@inheritdoc}
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new PostgreSqlSchemaManager($conn);
     }

lib/Doctrine/DBAL/Driver/AbstractSQLAnywhereDriver.php

@@ -6,9 +6,13 @@ namespace Doctrine\DBAL\Driver;
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Driver\DriverException as DriverExceptionInterface;
 use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\Exception\DriverException;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Platforms\Exception\InvalidPlatformVersion;
 use Doctrine\DBAL\Platforms\SQLAnywherePlatform;
+use Doctrine\DBAL\Schema\AbstractSchemaManager;
 use Doctrine\DBAL\Schema\SQLAnywhereSchemaManager;
 use Doctrine\DBAL\VersionAwarePlatformDriver;
 use function preg_match;
@@ -23,7 +27,7 @@ abstract class AbstractSQLAnywhereDriver implements Driver, ExceptionConverterDr
      *
      * @link http://dcx.sybase.com/index.html#sa160/en/saerrors/sqlerror.html
      */
-    public function convertException($message, DriverException $exception)
+    public function convertException(string $message, DriverExceptionInterface $exception) : DriverException
     {
         switch ($exception->getCode()) {
             case -306:
@@ -60,13 +64,13 @@ abstract class AbstractSQLAnywhereDriver implements Driver, ExceptionConverterDr
                 return new Exception\TableNotFoundException($message, $exception);
         }
 
-        return new Exception\DriverException($message, $exception);
+        return new DriverException($message, $exception);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function createDatabasePlatformForVersion($version)
+    public function createDatabasePlatformForVersion(string $version) : AbstractPlatform
     {
         if (! preg_match(
             '/^(?P<major>\d+)(?:\.(?P<minor>\d+)(?:\.(?P<patch>\d+)(?:\.(?P<build>\d+))?)?)?/',
@@ -88,7 +92,7 @@ abstract class AbstractSQLAnywhereDriver implements Driver, ExceptionConverterDr
     /**
      * {@inheritdoc}
      */
-    public function getDatabase(Connection $conn)
+    public function getDatabase(Connection $conn) : ?string
     {
         $params = $conn->getParams();
 
@@ -98,7 +102,7 @@ abstract class AbstractSQLAnywhereDriver implements Driver, ExceptionConverterDr
     /**
      * {@inheritdoc}
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new SQLAnywherePlatform();
     }
@@ -106,7 +110,7 @@ abstract class AbstractSQLAnywhereDriver implements Driver, ExceptionConverterDr
     /**
      * {@inheritdoc}
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new SQLAnywhereSchemaManager($conn);
     }

lib/Doctrine/DBAL/Driver/AbstractSQLServerDriver.php

@@ -6,9 +6,11 @@ namespace Doctrine\DBAL\Driver;
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Platforms\Exception\InvalidPlatformVersion;
 use Doctrine\DBAL\Platforms\SQLServer2012Platform;
 use Doctrine\DBAL\Platforms\SQLServerPlatform;
+use Doctrine\DBAL\Schema\AbstractSchemaManager;
 use Doctrine\DBAL\Schema\SQLServerSchemaManager;
 use Doctrine\DBAL\VersionAwarePlatformDriver;
 use function preg_match;
@@ -22,7 +24,7 @@ abstract class AbstractSQLServerDriver implements Driver, VersionAwarePlatformDr
     /**
      * {@inheritdoc}
      */
-    public function createDatabasePlatformForVersion($version)
+    public function createDatabasePlatformForVersion(string $version) : AbstractPlatform
     {
         if (! preg_match(
             '/^(?P<major>\d+)(?:\.(?P<minor>\d+)(?:\.(?P<patch>\d+)(?:\.(?P<build>\d+))?)?)?/',
@@ -52,7 +54,7 @@ abstract class AbstractSQLServerDriver implements Driver, VersionAwarePlatformDr
     /**
      * {@inheritdoc}
      */
-    public function getDatabase(Connection $conn)
+    public function getDatabase(Connection $conn) : ?string
     {
         $params = $conn->getParams();
 
@@ -62,7 +64,7 @@ abstract class AbstractSQLServerDriver implements Driver, VersionAwarePlatformDr
     /**
      * {@inheritdoc}
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new SQLServerPlatform();
     }
@@ -70,7 +72,7 @@ abstract class AbstractSQLServerDriver implements Driver, VersionAwarePlatformDr
     /**
      * {@inheritdoc}
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new SQLServerSchemaManager($conn);
     }

lib/Doctrine/DBAL/Driver/AbstractSQLiteDriver.php

@@ -6,8 +6,12 @@ namespace Doctrine\DBAL\Driver;
 
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Driver\DriverException as DriverExceptionInterface;
 use Doctrine\DBAL\Exception;
+use Doctrine\DBAL\Exception\DriverException;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Platforms\SqlitePlatform;
+use Doctrine\DBAL\Schema\AbstractSchemaManager;
 use Doctrine\DBAL\Schema\SqliteSchemaManager;
 use function strpos;
 
@@ -21,7 +25,7 @@ abstract class AbstractSQLiteDriver implements Driver, ExceptionConverterDriver
      *
      * @link http://www.sqlite.org/c3ref/c_abort.html
      */
-    public function convertException($message, DriverException $exception)
+    public function convertException(string $message, DriverExceptionInterface $exception) : DriverException
     {
         if (strpos($exception->getMessage(), 'database is locked') !== false) {
             return new Exception\LockWaitTimeoutException($message, $exception);
@@ -69,13 +73,13 @@ abstract class AbstractSQLiteDriver implements Driver, ExceptionConverterDriver
             return new Exception\ConnectionException($message, $exception);
         }
 
-        return new Exception\DriverException($message, $exception);
+        return new DriverException($message, $exception);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getDatabase(Connection $conn)
+    public function getDatabase(Connection $conn) : ?string
     {
         $params = $conn->getParams();
 
@@ -85,7 +89,7 @@ abstract class AbstractSQLiteDriver implements Driver, ExceptionConverterDriver
     /**
      * {@inheritdoc}
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new SqlitePlatform();
     }
@@ -93,7 +97,7 @@ abstract class AbstractSQLiteDriver implements Driver, ExceptionConverterDriver
     /**
      * {@inheritdoc}
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new SqliteSchemaManager($conn);
     }

lib/Doctrine/DBAL/Driver/ExceptionConverterDriver.php

@@ -4,6 +4,9 @@ declare(strict_types=1);
 
 namespace Doctrine\DBAL\Driver;
 
+use Doctrine\DBAL\Driver\DriverException as DriverExceptionInterface;
+use Doctrine\DBAL\Exception\DriverException;
+
 /**
  * Contract for a driver that is capable of converting DBAL driver exceptions into standardized DBAL driver exceptions.
  */
@@ -15,10 +18,10 @@ interface ExceptionConverterDriver
      * It evaluates the vendor specific error code and SQLSTATE and transforms
      * it into a unified {@link Doctrine\DBAL\Exception\DriverException} subclass.
      *
-     * @param string          $message   The DBAL exception message to use.
-     * @param DriverException $exception The DBAL driver exception to convert.
+     * @param string                   $message   The DBAL exception message to use.
+     * @param DriverExceptionInterface $exception The DBAL driver exception to convert.
      *
-     * @return \Doctrine\DBAL\Exception\DriverException An instance of one of the DriverException subclasses.
+     * @return DriverException An instance of one of the DriverException subclasses.
      */
-    public function convertException($message, DriverException $exception);
+    public function convertException(string $message, DriverExceptionInterface $exception) : DriverException;
 }

lib/Doctrine/DBAL/Driver/IBMDB2/DB2Driver.php

@@ -5,6 +5,11 @@ declare(strict_types=1);
 namespace Doctrine\DBAL\Driver\IBMDB2;
 
 use Doctrine\DBAL\Driver\AbstractDB2Driver;
+use Doctrine\DBAL\Driver\Connection;
+use function array_keys;
+use function array_map;
+use function implode;
+use function sprintf;
 
 /**
  * IBM DB2 Driver.
@@ -14,28 +19,42 @@ class DB2Driver extends AbstractDB2Driver
     /**
      * {@inheritdoc}
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = [])
-    {
-        if (! isset($params['protocol'])) {
-            $params['protocol'] = 'TCPIP';
-        }
-
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : Connection {
         if ($params['host'] !== 'localhost' && $params['host'] !== '127.0.0.1') {
             // if the host isn't localhost, use extended connection params
-            $params['dbname'] = 'DRIVER={IBM DB2 ODBC DRIVER}' .
-                     ';DATABASE=' . $params['dbname'] .
-                     ';HOSTNAME=' . $params['host'] .
-                     ';PROTOCOL=' . $params['protocol'] .
-                     ';UID=' . $username .
-                     ';PWD=' . $password . ';';
-            if (isset($params['port'])) {
-                $params['dbname'] .= 'PORT=' . $params['port'];
-            }
-
-            $username = null;
-            $password = null;
+            $params['dbname'] = $this->buildConnectionString($params, $username, $password);
+
+            $username = $password = '';
+        }
+
+        return new DB2Connection($params, $username, $password, $driverOptions);
+    }
+
+    /**
+     * @param string[] $params
+     */
+    private function buildConnectionString(array $params, string $username, string $password) : string
+    {
+        $connectionParams = [
+            'DRIVER'   => '{IBM DB2 ODBC DRIVER}',
+            'DATABASE' => $params['dbname'],
+            'HOSTNAME' => $params['host'],
+            'PROTOCOL' => $params['protocol'] ?? 'TCPIP',
+            'UID'      => $username,
+            'PWD'      => $password,
+        ];
+
+        if (isset($params['port'])) {
+            $connectionParams['PORT'] = $params['port'];
         }
 
-        return new DB2Connection($params, (string) $username, (string) $password, $driverOptions);
+        return implode(';', array_map(static function (string $key, string $value) : string {
+            return sprintf('%s=%s', $key, $value);
+        }, array_keys($connectionParams), $connectionParams));
     }
 }

lib/Doctrine/DBAL/Driver/Mysqli/Driver.php

@@ -6,16 +6,21 @@ namespace Doctrine\DBAL\Driver\Mysqli;
 
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver\AbstractMySQLDriver;
+use Doctrine\DBAL\Driver\Connection;
 
 class Driver extends AbstractMySQLDriver
 {
     /**
      * {@inheritdoc}
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = [])
-    {
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : Connection {
         try {
-            return new MysqliConnection($params, (string) $username, (string) $password, $driverOptions);
+            return new MysqliConnection($params, $username, $password, $driverOptions);
         } catch (MysqliException $e) {
             throw DBALException::driverException($this, $e);
         }

lib/Doctrine/DBAL/Driver/OCI8/Driver.php

@@ -6,6 +6,7 @@ namespace Doctrine\DBAL\Driver\OCI8;
 
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver\AbstractOracleDriver;
+use Doctrine\DBAL\Driver\Connection;
 use const OCI_DEFAULT;
 
 /**
@@ -16,12 +17,16 @@ class Driver extends AbstractOracleDriver
     /**
      * {@inheritdoc}
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = [])
-    {
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : Connection {
         try {
             return new OCI8Connection(
-                (string) $username,
-                (string) $password,
+                $username,
+                $password,
                 $this->_constructDsn($params),
                 $params['charset'] ?? '',
                 $params['sessionMode'] ?? OCI_DEFAULT,
@@ -39,7 +44,7 @@ class Driver extends AbstractOracleDriver
      *
      * @return string The DSN.
      */
-    protected function _constructDsn(array $params)
+    protected function _constructDsn(array $params) : string
     {
         return $this->getEasyConnectString($params);
     }

lib/Doctrine/DBAL/Driver/PDOMySql/Driver.php

@@ -6,6 +6,7 @@ namespace Doctrine\DBAL\Driver\PDOMySql;
 
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver\AbstractMySQLDriver;
+use Doctrine\DBAL\Driver\Connection;
 use Doctrine\DBAL\Driver\PDOConnection;
 use Doctrine\DBAL\Driver\PDOException;
 use PDO;
@@ -18,8 +19,12 @@ class Driver extends AbstractMySQLDriver
     /**
      * {@inheritdoc}
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = [])
-    {
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : Connection {
         if (! empty($params['persistent'])) {
             $driverOptions[PDO::ATTR_PERSISTENT] = true;
         }
@@ -45,7 +50,7 @@ class Driver extends AbstractMySQLDriver
      *
      * @return string The DSN.
      */
-    protected function constructPdoDsn(array $params)
+    protected function constructPdoDsn(array $params) : string
     {
         $dsn = 'mysql:';
         if (isset($params['host']) && $params['host'] !== '') {

lib/Doctrine/DBAL/Driver/PDOOracle/Driver.php

@@ -6,6 +6,7 @@ namespace Doctrine\DBAL\Driver\PDOOracle;
 
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver\AbstractOracleDriver;
+use Doctrine\DBAL\Driver\Connection;
 use Doctrine\DBAL\Driver\PDOConnection;
 use Doctrine\DBAL\Driver\PDOException;
 use PDO;
@@ -23,8 +24,12 @@ class Driver extends AbstractOracleDriver
     /**
      * {@inheritdoc}
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = [])
-    {
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : Connection {
         if (! empty($params['persistent'])) {
             $driverOptions[PDO::ATTR_PERSISTENT] = true;
         }
@@ -48,7 +53,7 @@ class Driver extends AbstractOracleDriver
      *
      * @return string The DSN.
      */
-    private function constructPdoDsn(array $params)
+    private function constructPdoDsn(array $params) : string
     {
         $dsn = 'oci:dbname=' . $this->getEasyConnectString($params);
 

lib/Doctrine/DBAL/Driver/PDOPgSql/Driver.php

@@ -6,6 +6,7 @@ namespace Doctrine\DBAL\Driver\PDOPgSql;
 
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver\AbstractPostgreSQLDriver;
+use Doctrine\DBAL\Driver\Connection;
 use Doctrine\DBAL\Driver\PDOConnection;
 use Doctrine\DBAL\Driver\PDOException;
 use PDO;
@@ -19,8 +20,12 @@ class Driver extends AbstractPostgreSQLDriver
     /**
      * {@inheritdoc}
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = [])
-    {
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : Connection {
         if (! empty($params['persistent'])) {
             $driverOptions[PDO::ATTR_PERSISTENT] = true;
         }
@@ -62,7 +67,7 @@ class Driver extends AbstractPostgreSQLDriver
      *
      * @return string The DSN.
      */
-    private function _constructPdoDsn(array $params)
+    private function _constructPdoDsn(array $params) : string
     {
         $dsn = 'pgsql:';
 

lib/Doctrine/DBAL/Driver/PDOSqlite/Driver.php

@@ -6,6 +6,7 @@ namespace Doctrine\DBAL\Driver\PDOSqlite;
 
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver\AbstractSQLiteDriver;
+use Doctrine\DBAL\Driver\Connection;
 use Doctrine\DBAL\Driver\PDOConnection;
 use Doctrine\DBAL\Driver\PDOException;
 use Doctrine\DBAL\Platforms\SqlitePlatform;
@@ -26,8 +27,12 @@ class Driver extends AbstractSQLiteDriver
     /**
      * {@inheritdoc}
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = [])
-    {
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : Connection {
         if (isset($driverOptions['userDefinedFunctions'])) {
             $this->_userDefinedFunctions = array_merge(
                 $this->_userDefinedFunctions,
@@ -63,7 +68,7 @@ class Driver extends AbstractSQLiteDriver
      *
      * @return string The DSN.
      */
-    protected function _constructPdoDsn(array $params)
+    protected function _constructPdoDsn(array $params) : string
     {
         $dsn = 'sqlite:';
         if (isset($params['path'])) {

lib/Doctrine/DBAL/Driver/PDOSqlsrv/Driver.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Doctrine\DBAL\Driver\PDOSqlsrv;
 
 use Doctrine\DBAL\Driver\AbstractSQLServerDriver;
+use Doctrine\DBAL\Driver\Connection as DriverConnection;
 use PDO;
 use function is_int;
 use function sprintf;
@@ -17,8 +18,12 @@ class Driver extends AbstractSQLServerDriver
     /**
      * {@inheritdoc}
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = [])
-    {
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : DriverConnection {
         $pdoOptions = $dsnOptions = [];
 
         foreach ($driverOptions as $option => $value) {
@@ -49,7 +54,7 @@ class Driver extends AbstractSQLServerDriver
      *
      * @return string The DSN.
      */
-    private function _constructPdoDsn(array $params, array $connectionOptions)
+    private function _constructPdoDsn(array $params, array $connectionOptions) : string
     {
         $dsn = 'sqlsrv:server=';
 

lib/Doctrine/DBAL/Driver/SQLAnywhere/Driver.php

@@ -6,9 +6,12 @@ namespace Doctrine\DBAL\Driver\SQLAnywhere;
 
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver\AbstractSQLAnywhereDriver;
+use Doctrine\DBAL\Driver\Connection;
 use function array_keys;
 use function array_map;
+use function array_merge;
 use function implode;
+use function sprintf;
 
 /**
  * A Doctrine DBAL driver for the SAP Sybase SQL Anywhere PHP extension.
@@ -20,19 +23,15 @@ class Driver extends AbstractSQLAnywhereDriver
      *
      * @throws DBALException If there was a problem establishing the connection.
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = [])
-    {
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : Connection {
         try {
             return new SQLAnywhereConnection(
-                $this->buildDsn(
-                    $params['host'] ?? null,
-                    $params['port'] ?? null,
-                    $params['server'] ?? null,
-                    $params['dbname'] ?? null,
-                    $username,
-                    $password,
-                    $driverOptions
-                ),
+                $this->buildDsn($params, $username, $password, $driverOptions),
                 $params['persistent'] ?? false
             );
         } catch (SQLAnywhereException $e) {
@@ -43,37 +42,40 @@ class Driver extends AbstractSQLAnywhereDriver
     /**
      * Build the connection string for given connection parameters and driver options.
      *
-     * @param string  $host          Host address to connect to.
-     * @param int     $port          Port to use for the connection (default to SQL Anywhere standard port 2638).
-     * @param string  $server        Database server name on the host to connect to.
-     *                               SQL Anywhere allows multiple database server instances on the same host,
-     *                               therefore specifying the server instance name to use is mandatory.
-     * @param string  $dbname        Name of the database on the server instance to connect to.
+     * @param mixed[] $params        DBAL connection parameters
      * @param string  $username      User name to use for connection authentication.
      * @param string  $password      Password to use for connection authentication.
      * @param mixed[] $driverOptions Additional parameters to use for the connection.
-     *
-     * @return string
      */
-    private function buildDsn($host, $port, $server, $dbname, $username = null, $password = null, array $driverOptions = [])
+    private function buildDsn(array $params, string $username, string $password, array $driverOptions = []) : string
     {
-        $host = $host ?: 'localhost';
-        $port = $port ?: 2638;
+        $connectionParams = [];
+
+        if (isset($params['host'])) {
+            $host = $params['host'];
 
-        if (! empty($server)) {
-            $server = ';ServerName=' . $server;
+            if (isset($params['port'])) {
+                $host .= sprintf(':%d', $params['port']);
+            }
+
+            $connectionParams['HOST'] = $host;
         }
 
-        return 'HOST=' . $host . ':' . $port .
-            $server .
-            ';DBN=' . $dbname .
-            ';UID=' . $username .
-            ';PWD=' . $password .
-            ';' . implode(
-                ';',
-                array_map(static function ($key, $value) {
-                    return $key . '=' . $value;
-                }, array_keys($driverOptions), $driverOptions)
-            );
+        if (isset($params['server'])) {
+            $connectionParams['ServerName'] = $params['server'];
+        }
+
+        if (isset($params['dbname'])) {
+            $connectionParams['DBN'] = $params['dbname'];
+        }
+
+        $connectionParams['UID'] = $username;
+        $connectionParams['PWD'] = $password;
+
+        $connectionParams = array_merge($connectionParams, $driverOptions);
+
+        return implode(';', array_map(static function (string $key, string $value) : string {
+            return sprintf('%s=%s', $key, $value);
+        }, array_keys($connectionParams), $connectionParams));
     }
 }

lib/Doctrine/DBAL/Driver/SQLSrv/Driver.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Doctrine\DBAL\Driver\SQLSrv;
 
 use Doctrine\DBAL\Driver\AbstractSQLServerDriver;
+use Doctrine\DBAL\Driver\Connection;
 
 /**
  * Driver for ext/sqlsrv.
@@ -14,8 +15,12 @@ class Driver extends AbstractSQLServerDriver
     /**
      * {@inheritdoc}
      */
-    public function connect(array $params, $username = null, $password = null, array $driverOptions = [])
-    {
+    public function connect(
+        array $params,
+        string $username = '',
+        string $password = '',
+        array $driverOptions = []
+    ) : Connection {
         if (! isset($params['host'])) {
             throw new SQLSrvException('Missing "host" in configuration for sqlsrv driver.');
         }
@@ -33,11 +38,11 @@ class Driver extends AbstractSQLServerDriver
             $driverOptions['CharacterSet'] = $params['charset'];
         }
 
-        if ($username !== null) {
+        if ($username !== '') {
             $driverOptions['UID'] = $username;
         }
 
-        if ($password !== null) {
+        if ($password !== '') {
             $driverOptions['PWD'] = $password;
         }
 

lib/Doctrine/DBAL/Sharding/PoolingShardConnection.php

@@ -218,8 +218,8 @@ class PoolingShardConnection extends Connection
 
         $connectionParams = $this->connectionParameters[$shardId];
 
-        $user     = $connectionParams['user'] ?? null;
-        $password = $connectionParams['password'] ?? null;
+        $user     = $connectionParams['user'] ?? '';
+        $password = $connectionParams['password'] ?? '';
 
         return $this->_driver->connect($connectionParams, $user, $password, $driverOptions);
     }

lib/Doctrine/DBAL/VersionAwarePlatformDriver.php

@@ -22,9 +22,7 @@ interface VersionAwarePlatformDriver
      * @param string $version The platform/server version string to evaluate. This should be given in the notation
      *                        the underlying database vendor uses.
      *
-     * @return AbstractPlatform
-     *
      * @throws DBALException If the given version string could not be evaluated.
      */
-    public function createDatabasePlatformForVersion($version);
+    public function createDatabasePlatformForVersion(string $version) : AbstractPlatform;
 }

tests/Doctrine/Tests/DBAL/ConnectionTest.php

@@ -695,8 +695,8 @@ class ConnectionTest extends DbalTestCase
         /** @var Driver|VersionAwarePlatformDriver|MockObject $driverMock */
         $driverMock = $this->createMock([Driver::class, VersionAwarePlatformDriver::class]);
 
-        /** @var ServerInfoAwareConnection|MockObject $driverConnectionMock */
-        $driverConnectionMock = $this->createMock(ServerInfoAwareConnection::class);
+        /** @var DriverConnection|ServerInfoAwareConnection|MockObject $driverConnectionMock */
+        $driverConnectionMock = $this->createMock([DriverConnection::class, ServerInfoAwareConnection::class]);
 
         /** @var AbstractPlatform|MockObject $platformMock */
         $platformMock = $this->getMockForAbstractClass(AbstractPlatform::class);

tests/Doctrine/Tests/DBAL/Functional/Driver/AbstractDriverTest.php

@@ -33,8 +33,8 @@ abstract class AbstractDriverTest extends DbalFunctionalTestCase
         $params = $this->connection->getParams();
         unset($params['dbname']);
 
-        $user     = $params['user'] ?? null;
-        $password = $params['password'] ?? null;
+        $user     = $params['user'] ?? '';
+        $password = $params['password'] ?? '';
 
         $connection = $this->driver->connect($params, $user, $password);
 

tests/Doctrine/Tests/DBAL/Functional/Driver/PDOPgSql/DriverTest.php

@@ -79,8 +79,8 @@ class DriverTest extends AbstractDriverTest
         $parameters                     = $this->connection->getParams();
         $parameters['application_name'] = 'doctrine';
 
-        $user     = $parameters['user'] ?? null;
-        $password = $parameters['password'] ?? null;
+        $user     = $parameters['user'] ?? '';
+        $password = $parameters['password'] ?? '';
 
         $connection = $this->driver->connect($parameters, $user, $password);
 

tests/Doctrine/Tests/DBAL/Functional/Schema/SchemaManagerFunctionalTestCase.php

@@ -117,8 +117,8 @@ abstract class SchemaManagerFunctionalTestCase extends DbalFunctionalTestCase
             $params['dbname'] = 'test_drop_database';
         }
 
-        $user     = $params['user'] ?? null;
-        $password = $params['password'] ?? null;
+        $user     = $params['user'] ?? '';
+        $password = $params['password'] ?? '';
 
         $connection = $this->connection->getDriver()->connect($params, $user, $password);
 

tests/Doctrine/Tests/DBAL/Functional/Schema/SqliteSchemaManagerTest.php

@@ -51,8 +51,8 @@ class SqliteSchemaManagerTest extends SchemaManagerFunctionalTestCase
         $params           = $this->connection->getParams();
         $params['dbname'] = 'test_drop_database';
 
-        $user     = $params['user'] ?? null;
-        $password = $params['password'] ?? null;
+        $user     = $params['user'] ?? '';
+        $password = $params['password'] ?? '';
 
         $connection = $this->connection->getDriver()->connect($params, $user, $password);