Merge pull request #3560 from morozov/driver-types

Enforced parameter and return value types in Driver classes
doctrine · Jun 13, 2019 · ed18784 · ed18784
2 parents 6d02914 + 3fb9eb6
commit ed18784
Show file tree

Hide file tree

Showing 29 changed files with 247 additions and 154 deletions.
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,5 +1,10 @@
 # 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.

diff --git a/lib/Doctrine/DBAL/Connection.php b/lib/Doctrine/DBAL/Connection.php
@@ -322,8 +322,8 @@ public function connect() : void
         }
 
         $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;

diff --git a/lib/Doctrine/DBAL/Connections/MasterSlaveConnection.php b/lib/Doctrine/DBAL/Connections/MasterSlaveConnection.php
@@ -192,8 +192,8 @@ protected function connectTo($connectionName)
 
         $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);
     }

diff --git a/lib/Doctrine/DBAL/Driver.php b/lib/Doctrine/DBAL/Driver.php
@@ -4,6 +4,7 @@
 
 namespace Doctrine\DBAL;
 
+use Doctrine\DBAL\Driver\Connection as DriverConnection;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Schema\AbstractSchemaManager;
 
@@ -16,35 +17,38 @@ interface Driver
     /**
      * Attempts to create a connection with the database.
      *
-     * @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.
+     * @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.
      *
-     * @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
      * the platform this driver connects to.
      *
      * @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;
 }
diff --git a/lib/Doctrine/DBAL/Driver/AbstractDB2Driver.php b/lib/Doctrine/DBAL/Driver/AbstractDB2Driver.php
@@ -6,7 +6,9 @@
 
 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,15 +29,15 @@ public function getDatabase(Connection $conn)
     /**
      * {@inheritdoc}
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new DB2Platform();
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new DB2SchemaManager($conn);
     }

diff --git a/lib/Doctrine/DBAL/Driver/AbstractMySQLDriver.php b/lib/Doctrine/DBAL/Driver/AbstractMySQLDriver.php
@@ -7,12 +7,16 @@
 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,15 +110,15 @@ public function convertException($message, DriverException $exception)
                 return new Exception\NotNullConstraintViolationException($message, $exception);
         }
 
-        return new Exception\DriverException($message, $exception);
+        return new DriverException($message, $exception);
     }
 
     /**
      * {@inheritdoc}
      *
      * @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 @@ private function getMariaDbMysqlVersionNumber(string $versionString) : string
     /**
      * {@inheritdoc}
      */
-    public function getDatabase(Connection $conn)
+    public function getDatabase(Connection $conn) : ?string
     {
         $params = $conn->getParams();
 
@@ -204,7 +208,7 @@ public function getDatabase(Connection $conn)
      *
      * @return MySqlPlatform
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new MySqlPlatform();
     }
@@ -214,7 +218,7 @@ public function getDatabasePlatform()
      *
      * @return MySqlSchemaManager
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new MySqlSchemaManager($conn);
     }

diff --git a/lib/Doctrine/DBAL/Driver/AbstractOracleDriver.php b/lib/Doctrine/DBAL/Driver/AbstractOracleDriver.php
@@ -7,8 +7,12 @@
 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 @@ public function convertException($message, DriverException $exception)
                 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,15 +76,15 @@ public function getDatabase(Connection $conn)
     /**
      * {@inheritdoc}
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new OraclePlatform();
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new OracleSchemaManager($conn);
     }
@@ -89,10 +93,8 @@ public function getSchemaManager(Connection $conn)
      * 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);
     }

diff --git a/lib/Doctrine/DBAL/Driver/AbstractPostgreSQLDriver.php b/lib/Doctrine/DBAL/Driver/AbstractPostgreSQLDriver.php
@@ -6,11 +6,15 @@
 
 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 @@ public function convertException($message, DriverException $exception)
             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 @@ public function createDatabasePlatformForVersion($version)
     /**
      * {@inheritdoc}
      */
-    public function getDatabase(Connection $conn)
+    public function getDatabase(Connection $conn) : ?string
     {
         $params = $conn->getParams();
 
@@ -116,15 +120,15 @@ public function getDatabase(Connection $conn)
     /**
      * {@inheritdoc}
      */
-    public function getDatabasePlatform()
+    public function getDatabasePlatform() : AbstractPlatform
     {
         return new PostgreSqlPlatform();
     }
 
     /**
      * {@inheritdoc}
      */
-    public function getSchemaManager(Connection $conn)
+    public function getSchemaManager(Connection $conn) : AbstractSchemaManager
     {
         return new PostgreSqlSchemaManager($conn);
     }