Merge pull request #3708 from morozov/issues/3580

New deprecations for 2.10

UPGRADE.md

 # Upgrade to 2.10
 
+## Deprecated `Doctrine\DBAL\Event\ConnectionEventArgs` methods
+
+The usage of the `getDriver()`, `getDatabasePlatform()` and `getSchemaManager()` methods of the `ConnectionEventArgs` class has been deprecated. Obtain the underlying connection via `getConnection()` and call the corresponding methods on the connection instance.
+
+## Deprecated `Doctrine\DBAL\Event\SchemaColumnDefinitionEventArgs` methods
+
+The usage of the `getDatabasePlatform()` method of the `SchemaColumnDefinitionEventArgs` class has been deprecated. Obtain the underlying connection via `getConnection()` and call the corresponding method on the connection instance.
+
+## Deprecated `Doctrine\DBAL\Connection` methods
+
+The usage of the `getHost()`, `getPort()`, `getUsername()` and `getPassword()` methods of the `Connection` class has been deprecated as they leak implementation details.
+
+## Deprecated array of statements in `addSql()` of `SchemaEventArgs`-based classes.
+
+Passing multiple SQL statements as an array to `SchemaAlterTableAddColumnEventArgs::addSql()` and the same method in other `SchemaEventArgs`-based classes is deprecated. Pass each statement as an individual argument instead.
+
+## Deprecated calling `AbstractSchemaManager::tablesExist()` with a string argument.
+
+Instead of passing a string, pass a one-element array.
+
+## Deprecated calling `OracleSchemaManager::createDatabase()` without an argument or by passing NULL.
+
+In order to create a database, always pass the database name.
+
+## Deprecated unused schema manager methods.
+
+The following methods have been deprecated as unused:
+
+- `AbstractSchemaManager::_getPortableFunctionsList()`,
+- `AbstractSchemaManager::_getPortableFunctionDefinition()`,
+- `OracleSchemaManager::_getPortableFunctionDefinition()`,
+- `SqliteSchemaManager::_getPortableTableIndexDefinition()`.
+
+# Deprecations in `Doctrine\DBAL\Driver`
+
+- The usage of NULL to indicate empty `$username` or `$password` when calling `connect()` is deprecated. Use an empty string instead.
+
 ## Deprecated `Doctrine\DBAL\Platforms::_getAlterTableIndexForeignKeySQL()`
 
 Method `Doctrine\DBAL\Platforms::_getAlterTableIndexForeignKeySQL()` has been deprecated as no longer used.

lib/Doctrine/DBAL/Connection.php

@@ -242,6 +242,8 @@ class Connection implements DriverConnection
     /**
      * Gets the hostname of the currently connected database.
      *
+     * @deprecated
+     *
      * @return string|null
      */
     public function getHost()
@@ -252,6 +254,8 @@ class Connection implements DriverConnection
     /**
      * Gets the port of the currently connected database.
      *
+     * @deprecated
+     *
      * @return mixed
      */
     public function getPort()
@@ -262,6 +266,8 @@ class Connection implements DriverConnection
     /**
      * Gets the username used by this connection.
      *
+     * @deprecated
+     *
      * @return string|null
      */
     public function getUsername()
@@ -272,6 +278,8 @@ class Connection implements DriverConnection
     /**
      * Gets the password used by this connection.
      *
+     * @deprecated
+     *
      * @return string|null
      */
     public function getPassword()

lib/Doctrine/DBAL/Driver.php

@@ -14,6 +14,8 @@ 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|null $username      The username to use when connecting.
      * @param string|null $password      The password to use when connecting.

lib/Doctrine/DBAL/Event/ConnectionEventArgs.php

@@ -30,6 +30,8 @@ class ConnectionEventArgs extends EventArgs
     }
 
     /**
+     * @deprecated Use ConnectionEventArgs::getConnection() and Connection::getDriver() instead.
+     *
      * @return Driver
      */
     public function getDriver()
@@ -38,6 +40,8 @@ class ConnectionEventArgs extends EventArgs
     }
 
     /**
+     * @deprecated Use ConnectionEventArgs::getConnection() and Connection::getDatabasePlatform() instead.
+     *
      * @return AbstractPlatform
      */
     public function getDatabasePlatform()
@@ -46,6 +50,8 @@ class ConnectionEventArgs extends EventArgs
     }
 
     /**
+     * @deprecated Use ConnectionEventArgs::getConnection() and Connection::getSchemaManager() instead.
+     *
      * @return AbstractSchemaManager
      */
     public function getSchemaManager()

lib/Doctrine/DBAL/Event/SchemaAlterTableAddColumnEventArgs.php

@@ -6,6 +6,7 @@ use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Schema\Column;
 use Doctrine\DBAL\Schema\TableDiff;
 use function array_merge;
+use function func_get_args;
 use function is_array;
 
 /**
@@ -57,17 +58,15 @@ class SchemaAlterTableAddColumnEventArgs extends SchemaEventArgs
     }
 
     /**
+     * Passing multiple SQL statements as an array is deprecated. Pass each statement as an individual argument instead.
+     *
      * @param string|string[] $sql
      *
      * @return \Doctrine\DBAL\Event\SchemaAlterTableAddColumnEventArgs
      */
     public function addSql($sql)
     {
-        if (is_array($sql)) {
-            $this->sql = array_merge($this->sql, $sql);
-        } else {
-            $this->sql[] = $sql;
-        }
+        $this->sql = array_merge($this->sql, is_array($sql) ? $sql : func_get_args());
 
         return $this;
     }

lib/Doctrine/DBAL/Event/SchemaAlterTableChangeColumnEventArgs.php

@@ -6,6 +6,7 @@ use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Schema\ColumnDiff;
 use Doctrine\DBAL\Schema\TableDiff;
 use function array_merge;
+use function func_get_args;
 use function is_array;
 
 /**
@@ -57,17 +58,15 @@ class SchemaAlterTableChangeColumnEventArgs extends SchemaEventArgs
     }
 
     /**
+     * Passing multiple SQL statements as an array is deprecated. Pass each statement as an individual argument instead.
+     *
      * @param string|string[] $sql
      *
      * @return \Doctrine\DBAL\Event\SchemaAlterTableChangeColumnEventArgs
      */
     public function addSql($sql)
     {
-        if (is_array($sql)) {
-            $this->sql = array_merge($this->sql, $sql);
-        } else {
-            $this->sql[] = $sql;
-        }
+        $this->sql = array_merge($this->sql, is_array($sql) ? $sql : func_get_args());
 
         return $this;
     }

lib/Doctrine/DBAL/Event/SchemaAlterTableEventArgs.php

@@ -5,6 +5,7 @@ namespace Doctrine\DBAL\Event;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Schema\TableDiff;
 use function array_merge;
+use function func_get_args;
 use function is_array;
 
 /**
@@ -44,17 +45,15 @@ class SchemaAlterTableEventArgs extends SchemaEventArgs
     }
 
     /**
+     * Passing multiple SQL statements as an array is deprecated. Pass each statement as an individual argument instead.
+     *
      * @param string|string[] $sql
      *
      * @return \Doctrine\DBAL\Event\SchemaAlterTableEventArgs
      */
     public function addSql($sql)
     {
-        if (is_array($sql)) {
-            $this->sql = array_merge($this->sql, $sql);
-        } else {
-            $this->sql[] = $sql;
-        }
+        $this->sql = array_merge($this->sql, is_array($sql) ? $sql : func_get_args());
 
         return $this;
     }

lib/Doctrine/DBAL/Event/SchemaAlterTableRemoveColumnEventArgs.php

@@ -6,6 +6,7 @@ use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Schema\Column;
 use Doctrine\DBAL\Schema\TableDiff;
 use function array_merge;
+use function func_get_args;
 use function is_array;
 
 /**
@@ -57,17 +58,15 @@ class SchemaAlterTableRemoveColumnEventArgs extends SchemaEventArgs
     }
 
     /**
+     * Passing multiple SQL statements as an array is deprecated. Pass each statement as an individual argument instead.
+     *
      * @param string|string[] $sql
      *
      * @return \Doctrine\DBAL\Event\SchemaAlterTableRemoveColumnEventArgs
      */
     public function addSql($sql)
     {
-        if (is_array($sql)) {
-            $this->sql = array_merge($this->sql, $sql);
-        } else {
-            $this->sql[] = $sql;
-        }
+        $this->sql = array_merge($this->sql, is_array($sql) ? $sql : func_get_args());
 
         return $this;
     }

lib/Doctrine/DBAL/Event/SchemaAlterTableRenameColumnEventArgs.php

@@ -6,6 +6,7 @@ use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Schema\Column;
 use Doctrine\DBAL\Schema\TableDiff;
 use function array_merge;
+use function func_get_args;
 use function is_array;
 
 /**
@@ -72,17 +73,15 @@ class SchemaAlterTableRenameColumnEventArgs extends SchemaEventArgs
     }
 
     /**
+     * Passing multiple SQL statements as an array is deprecated. Pass each statement as an individual argument instead.
+     *
      * @param string|string[] $sql
      *
      * @return \Doctrine\DBAL\Event\SchemaAlterTableRenameColumnEventArgs
      */
     public function addSql($sql)
     {
-        if (is_array($sql)) {
-            $this->sql = array_merge($this->sql, $sql);
-        } else {
-            $this->sql[] = $sql;
-        }
+        $this->sql = array_merge($this->sql, is_array($sql) ? $sql : func_get_args());
 
         return $this;
     }

lib/Doctrine/DBAL/Event/SchemaColumnDefinitionEventArgs.php

@@ -97,6 +97,8 @@ class SchemaColumnDefinitionEventArgs extends SchemaEventArgs
     }
 
     /**
+     * @deprecated Use SchemaColumnDefinitionEventArgs::getConnection() and Connection::getDatabasePlatform() instead.
+     *
      * @return AbstractPlatform
      */
     public function getDatabasePlatform()

lib/Doctrine/DBAL/Event/SchemaCreateTableColumnEventArgs.php

@@ -6,6 +6,7 @@ use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Schema\Column;
 use Doctrine\DBAL\Schema\Table;
 use function array_merge;
+use function func_get_args;
 use function is_array;
 
 /**
@@ -57,17 +58,15 @@ class SchemaCreateTableColumnEventArgs extends SchemaEventArgs
     }
 
     /**
+     * Passing multiple SQL statements as an array is deprecated. Pass each statement as an individual argument instead.
+     *
      * @param string|string[] $sql
      *
      * @return \Doctrine\DBAL\Event\SchemaCreateTableColumnEventArgs
      */
     public function addSql($sql)
     {
-        if (is_array($sql)) {
-            $this->sql = array_merge($this->sql, $sql);
-        } else {
-            $this->sql[] = $sql;
-        }
+        $this->sql = array_merge($this->sql, is_array($sql) ? $sql : func_get_args());
 
         return $this;
     }

lib/Doctrine/DBAL/Event/SchemaCreateTableEventArgs.php

@@ -5,6 +5,7 @@ namespace Doctrine\DBAL\Event;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Schema\Table;
 use function array_merge;
+use function func_get_args;
 use function is_array;
 
 /**
@@ -72,17 +73,15 @@ class SchemaCreateTableEventArgs extends SchemaEventArgs
     }
 
     /**
+     * Passing multiple SQL statements as an array is deprecated. Pass each statement as an individual argument instead.
+     *
      * @param string|string[] $sql
      *
      * @return \Doctrine\DBAL\Event\SchemaCreateTableEventArgs
      */
     public function addSql($sql)
     {
-        if (is_array($sql)) {
-            $this->sql = array_merge($this->sql, $sql);
-        } else {
-            $this->sql[] = $sql;
-        }
+        $this->sql = array_merge($this->sql, is_array($sql) ? $sql : func_get_args());
 
         return $this;
     }

lib/Doctrine/DBAL/Schema/AbstractSchemaManager.php

@@ -188,6 +188,8 @@ abstract class AbstractSchemaManager
     /**
      * Returns true if all the given tables exist.
      *
+     * The usage of a string $tableNames is deprecated. Pass a one-element array instead.
+     *
      * @param string|string[] $tableNames
      *
      * @return bool
@@ -683,6 +685,8 @@ abstract class AbstractSchemaManager
     }
 
     /**
+     * @deprecated
+     *
      * @param mixed[][] $functions
      *
      * @return mixed[][]
@@ -704,6 +708,8 @@ abstract class AbstractSchemaManager
     }
 
     /**
+     * @deprecated
+     *
      * @param mixed[] $function
      *
      * @return mixed

lib/Doctrine/DBAL/Schema/OracleSchemaManager.php

@@ -264,6 +264,8 @@ class OracleSchemaManager extends AbstractSchemaManager
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated
      */
     protected function _getPortableFunctionDefinition($function)
     {
@@ -284,6 +286,8 @@ class OracleSchemaManager extends AbstractSchemaManager
 
     /**
      * {@inheritdoc}
+     *
+     * Calling this method without an argument or by passing NULL is deprecated.
      */
     public function createDatabase($database = null)
     {

lib/Doctrine/DBAL/Schema/SqliteSchemaManager.php

@@ -224,6 +224,8 @@ class SqliteSchemaManager extends AbstractSchemaManager
 
     /**
      * {@inheritdoc}
+     *
+     * @deprecated
      */
     protected function _getPortableTableIndexDefinition($tableIndex)
     {