[DBAL-3079] Added type hints to query-related method parameters and return values

lib/Doctrine/DBAL/Cache/ResultCacheStatement.php

@@ -202,7 +202,7 @@ class ResultCacheStatement implements IteratorAggregate, ResultStatement
      *
      * @return int The number of rows.
      */
-    public function rowCount()
+    public function rowCount() : int
     {
         assert($this->statement instanceof Statement);
 

lib/Doctrine/DBAL/Connection.php

@@ -846,18 +846,16 @@ class Connection implements DriverConnection
     /**
      * Prepares an SQL statement.
      *
-     * @param string $statement The SQL statement to prepare.
-     *
-     * @return DriverStatement The prepared statement.
+     * @param string $sql The SQL statement to prepare.
      *
      * @throws DBALException
      */
-    public function prepare($statement)
+    public function prepare(string $sql) : DriverStatement
     {
         try {
-            $stmt = new Statement($statement, $this);
+            $stmt = new Statement($sql, $this);
         } catch (Throwable $ex) {
-            throw DBALException::driverExceptionDuringQuery($this->_driver, $ex, $statement);
+            throw DBALException::driverExceptionDuringQuery($this->_driver, $ex, $sql);
         }
 
         $stmt->setFetchMode($this->defaultFetchMode);
@@ -880,7 +878,7 @@ class Connection implements DriverConnection
      *
      * @throws DBALException
      */
-    public function executeQuery($query, array $params = [], $types = [], ?QueryCacheProfile $qcp = null)
+    public function executeQuery(string $query, array $params = [], $types = [], ?QueryCacheProfile $qcp = null) : ResultStatement
     {
         if ($qcp !== null) {
             return $this->executeCacheQuery($query, $params, $types, $qcp);
@@ -928,11 +926,9 @@ class Connection implements DriverConnection
      * @param int[]|string[]    $types  The types the previous parameters are in.
      * @param QueryCacheProfile $qcp    The query cache profile.
      *
-     * @return ResultStatement
-     *
      * @throws CacheException
      */
-    public function executeCacheQuery($query, $params, $types, QueryCacheProfile $qcp)
+    public function executeCacheQuery($query, $params, $types, QueryCacheProfile $qcp) : ResultStatement
     {
         $resultCache = $qcp->getResultCacheDriver() ?? $this->_config->getResultCacheImpl();
 
@@ -995,7 +991,7 @@ class Connection implements DriverConnection
     /**
      * {@inheritDoc}
      */
-    public function query(string $sql)
+    public function query(string $sql) : ResultStatement
     {
         $connection = $this->getWrappedConnection();
 
@@ -1029,11 +1025,9 @@ class Connection implements DriverConnection
      * @param mixed[]        $params The query parameters.
      * @param int[]|string[] $types  The parameter types.
      *
-     * @return int The number of affected rows.
-     *
      * @throws DBALException
      */
-    public function executeUpdate($query, array $params = [], array $types = [])
+    public function executeUpdate(string $query, array $params = [], array $types = []) : int
     {
         $connection = $this->getWrappedConnection();
 
@@ -1070,15 +1064,9 @@ class Connection implements DriverConnection
     }
 
     /**
-     * Executes an SQL statement and return the number of affected rows.
-     *
-     * @param string $statement
-     *
-     * @return int The number of affected rows.
-     *
-     * @throws DBALException
+     * {@inheritDoc}
      */
-    public function exec($statement)
+    public function exec(string $statement) : int
     {
         $connection = $this->getWrappedConnection();
 
@@ -1520,13 +1508,11 @@ class Connection implements DriverConnection
      * @internal Duck-typing used on the $stmt parameter to support driver statements as well as
      *           raw PDOStatement instances.
      *
-     * @param \Doctrine\DBAL\Driver\Statement $stmt   The statement to bind the values to.
+     * @param DriverStatement $stmt   The statement to bind the values to.
      * @param mixed[]         $params The map/list of named/positional parameters.
      * @param int[]|string[]  $types  The parameter types (PDO binding types or DBAL mapping types).
-     *
-     * @return void
      */
-    private function _bindTypedValues($stmt, array $params, array $types)
+    private function _bindTypedValues(DriverStatement $stmt, array $params, array $types) : void
     {
         // Check whether parameters are positional or named. Mixing is not allowed, just like in PDO.
         if (is_int(key($params))) {

lib/Doctrine/DBAL/Connections/MasterSlaveConnection.php

@@ -7,6 +7,8 @@ use Doctrine\DBAL\Configuration;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Driver\Connection as DriverConnection;
+use Doctrine\DBAL\Driver\ResultStatement;
+use Doctrine\DBAL\Driver\Statement;
 use Doctrine\DBAL\Event\ConnectionEventArgs;
 use Doctrine\DBAL\Events;
 use InvalidArgumentException;
@@ -218,7 +220,7 @@ class MasterSlaveConnection extends Connection
     /**
      * {@inheritDoc}
      */
-    public function executeUpdate($query, array $params = [], array $types = [])
+    public function executeUpdate(string $query, array $params = [], array $types = []) : int
     {
         $this->connect('master');
 
@@ -301,7 +303,7 @@ class MasterSlaveConnection extends Connection
     /**
      * {@inheritDoc}
      */
-    public function exec($statement)
+    public function exec(string $statement) : int
     {
         $this->connect('master');
 
@@ -341,7 +343,7 @@ class MasterSlaveConnection extends Connection
     /**
      * {@inheritDoc}
      */
-    public function query(string $sql)
+    public function query(string $sql) : ResultStatement
     {
         $this->connect('master');
         assert($this->_conn instanceof DriverConnection);
@@ -365,10 +367,10 @@ class MasterSlaveConnection extends Connection
     /**
      * {@inheritDoc}
      */
-    public function prepare($statement)
+    public function prepare(string $sql) : Statement
     {
         $this->connect('master');
 
-        return parent::prepare($statement);
+        return parent::prepare($sql);
     }
 }

lib/Doctrine/DBAL/Driver/Connection.php

@@ -15,21 +15,15 @@ interface Connection
 {
     /**
      * Prepares a statement for execution and returns a Statement object.
-     *
-     * @param string $prepareString
-     *
-     * @return Statement
      */
-    public function prepare($prepareString);
+    public function prepare(string $sql) : Statement;
 
     /**
      * Executes an SQL statement, returning a result set as a Statement object.
      *
-     * @return Statement
-     *
      * @throws DBALException
      */
-    public function query(string $sql);
+    public function query(string $sql) : ResultStatement;
 
     /**
      * Quotes a string for use in a query.
@@ -44,11 +38,9 @@ interface Connection
     /**
      * Executes an SQL statement and return the number of affected rows.
      *
-     * @param string $statement
-     *
-     * @return int
+     * @throws DBALException
      */
-    public function exec($statement);
+    public function exec(string $statement) : int;
 
     /**
      * Returns the ID of the last inserted row or sequence value.

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

@@ -3,7 +3,9 @@
 namespace Doctrine\DBAL\Driver\IBMDB2;
 
 use Doctrine\DBAL\Driver\Connection;
+use Doctrine\DBAL\Driver\ResultStatement;
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
+use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use Doctrine\DBAL\ParameterType;
 use stdClass;
 use const DB2_AUTOCOMMIT_OFF;
@@ -75,7 +77,7 @@ class DB2Connection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritdoc}
      */
-    public function prepare($sql)
+    public function prepare(string $sql) : DriverStatement
     {
         $stmt = @db2_prepare($this->conn, $sql);
         if (! $stmt) {
@@ -88,7 +90,7 @@ class DB2Connection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritdoc}
      */
-    public function query(string $sql)
+    public function query(string $sql) : ResultStatement
     {
         $stmt = $this->prepare($sql);
         $stmt->execute();
@@ -113,7 +115,7 @@ class DB2Connection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritdoc}
      */
-    public function exec($statement)
+    public function exec(string $statement) : int
     {
         $stmt = @db2_exec($this->conn, $statement);
 

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

@@ -344,7 +344,7 @@ class DB2Statement implements IteratorAggregate, Statement
     /**
      * {@inheritdoc}
      */
-    public function rowCount()
+    public function rowCount() : int
     {
         return @db2_num_rows($this->stmt) ? : 0;
     }

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

@@ -4,7 +4,9 @@ namespace Doctrine\DBAL\Driver\Mysqli;
 
 use Doctrine\DBAL\Driver\Connection;
 use Doctrine\DBAL\Driver\PingableConnection;
+use Doctrine\DBAL\Driver\ResultStatement;
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
+use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use Doctrine\DBAL\ParameterType;
 use mysqli;
 use const MYSQLI_INIT_COMMAND;
@@ -125,15 +127,15 @@ class MysqliConnection implements Connection, PingableConnection, ServerInfoAwar
     /**
      * {@inheritdoc}
      */
-    public function prepare($prepareString)
+    public function prepare(string $sql) : DriverStatement
     {
-        return new MysqliStatement($this->conn, $prepareString);
+        return new MysqliStatement($this->conn, $sql);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function query(string $sql)
+    public function query(string $sql) : ResultStatement
     {
         $stmt = $this->prepare($sql);
         $stmt->execute();
@@ -152,7 +154,7 @@ class MysqliConnection implements Connection, PingableConnection, ServerInfoAwar
     /**
      * {@inheritdoc}
      */
-    public function exec($statement)
+    public function exec(string $statement) : int
     {
         if ($this->conn->query($statement) === false) {
             throw new MysqliException($this->conn->error, $this->conn->sqlstate, $this->conn->errno);

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

@@ -415,7 +415,7 @@ class MysqliStatement implements IteratorAggregate, Statement
     /**
      * {@inheritdoc}
      */
-    public function rowCount()
+    public function rowCount() : int
     {
         if ($this->_columnNames === false) {
             return $this->_stmt->affected_rows;

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

@@ -3,7 +3,9 @@
 namespace Doctrine\DBAL\Driver\OCI8;
 
 use Doctrine\DBAL\Driver\Connection;
+use Doctrine\DBAL\Driver\ResultStatement;
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
+use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use Doctrine\DBAL\ParameterType;
 use UnexpectedValueException;
 use const OCI_COMMIT_ON_SUCCESS;
@@ -102,15 +104,15 @@ class OCI8Connection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritdoc}
      */
-    public function prepare($prepareString)
+    public function prepare(string $sql) : DriverStatement
     {
-        return new OCI8Statement($this->dbh, $prepareString, $this);
+        return new OCI8Statement($this->dbh, $sql, $this);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function query(string $sql)
+    public function query(string $sql) : ResultStatement
     {
         $stmt = $this->prepare($sql);
         $stmt->execute();
@@ -134,7 +136,7 @@ class OCI8Connection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritdoc}
      */
-    public function exec($statement)
+    public function exec(string $statement) : int
     {
         $stmt = $this->prepare($statement);
         $stmt->execute();

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

@@ -529,7 +529,7 @@ class OCI8Statement implements IteratorAggregate, Statement
     /**
      * {@inheritdoc}
      */
-    public function rowCount()
+    public function rowCount() : int
     {
         return oci_num_rows($this->_sth) ?: 0;
     }

lib/Doctrine/DBAL/Driver/PDOConnection.php

@@ -37,7 +37,7 @@ class PDOConnection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritdoc}
      */
-    public function exec($statement)
+    public function exec(string $statement) : int
     {
         try {
             return $this->connection->exec($statement);
@@ -57,11 +57,11 @@ class PDOConnection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritdoc}
      */
-    public function prepare($prepareString)
+    public function prepare(string $sql) : Statement
     {
         try {
             return $this->createStatement(
-                $this->connection->prepare($prepareString)
+                $this->connection->prepare($sql)
             );
         } catch (\PDOException $exception) {
             throw new PDOException($exception);
@@ -71,7 +71,7 @@ class PDOConnection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritdoc}
      */
-    public function query(string $sql)
+    public function query(string $sql) : ResultStatement
     {
         try {
             $stmt = $this->connection->query($sql);

lib/Doctrine/DBAL/Driver/PDOStatement.php

@@ -127,7 +127,7 @@ class PDOStatement implements IteratorAggregate, Statement
         }
     }
 
-    public function rowCount()
+    public function rowCount() : int
     {
         return $this->stmt->rowCount();
     }

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

@@ -3,7 +3,9 @@
 namespace Doctrine\DBAL\Driver\SQLAnywhere;
 
 use Doctrine\DBAL\Driver\Connection;
+use Doctrine\DBAL\Driver\ResultStatement;
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
+use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use Doctrine\DBAL\ParameterType;
 use function assert;
 use function is_float;
@@ -106,7 +108,7 @@ class SQLAnywhereConnection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritdoc}
      */
-    public function exec($statement)
+    public function exec(string $statement) : int
     {
         if (sasql_real_query($this->connection, $statement) === false) {
             throw SQLAnywhereException::fromSQLAnywhereError($this->connection);
@@ -142,15 +144,15 @@ class SQLAnywhereConnection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritdoc}
      */
-    public function prepare($prepareString)
+    public function prepare(string $sql) : DriverStatement
     {
-        return new SQLAnywhereStatement($this->connection, $prepareString);
+        return new SQLAnywhereStatement($this->connection, $sql);
     }
 
     /**
      * {@inheritdoc}
      */
-    public function query(string $sql)
+    public function query(string $sql) : ResultStatement
     {
         $stmt = $this->prepare($sql);
         $stmt->execute();

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

@@ -297,7 +297,7 @@ class SQLAnywhereStatement implements IteratorAggregate, Statement
     /**
      * {@inheritdoc}
      */
-    public function rowCount()
+    public function rowCount() : int
     {
         return sasql_stmt_affected_rows($this->stmt);
     }

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

@@ -3,7 +3,9 @@
 namespace Doctrine\DBAL\Driver\SQLSrv;
 
 use Doctrine\DBAL\Driver\Connection;
+use Doctrine\DBAL\Driver\ResultStatement;
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
+use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use Doctrine\DBAL\ParameterType;
 use const SQLSRV_ERR_ERRORS;
 use function is_float;
@@ -74,7 +76,7 @@ class SQLSrvConnection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritDoc}
      */
-    public function prepare($sql)
+    public function prepare(string $sql) : DriverStatement
     {
         return new SQLSrvStatement($this->conn, $sql, $this->lastInsertId);
     }
@@ -82,7 +84,7 @@ class SQLSrvConnection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritDoc}
      */
-    public function query(string $sql)
+    public function query(string $sql) : ResultStatement
     {
         $stmt = $this->prepare($sql);
         $stmt->execute();
@@ -109,7 +111,7 @@ class SQLSrvConnection implements Connection, ServerInfoAwareConnection
     /**
      * {@inheritDoc}
      */
-    public function exec($statement)
+    public function exec(string $statement) : int
     {
         $stmt = sqlsrv_query($this->conn, $statement);
 

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

@@ -418,7 +418,7 @@ class SQLSrvStatement implements IteratorAggregate, Statement
     /**
      * {@inheritdoc}
      */
-    public function rowCount()
+    public function rowCount() : int
     {
         if ($this->stmt === null) {
             return 0;

lib/Doctrine/DBAL/Driver/Statement.php

@@ -100,5 +100,5 @@ interface Statement extends ResultStatement
      *
      * @return int The number of rows.
      */
-    public function rowCount();
+    public function rowCount() : int;
 }

lib/Doctrine/DBAL/Portability/Connection.php

@@ -5,6 +5,8 @@ namespace Doctrine\DBAL\Portability;
 use Doctrine\DBAL\Cache\QueryCacheProfile;
 use Doctrine\DBAL\ColumnCase;
 use Doctrine\DBAL\Driver\PDOConnection;
+use Doctrine\DBAL\Driver\ResultStatement;
+use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use PDO;
 use const CASE_LOWER;
 use const CASE_UPPER;
@@ -96,7 +98,7 @@ class Connection extends \Doctrine\DBAL\Connection
     /**
      * {@inheritdoc}
      */
-    public function executeQuery($query, array $params = [], $types = [], ?QueryCacheProfile $qcp = null)
+    public function executeQuery(string $query, array $params = [], $types = [], ?QueryCacheProfile $qcp = null) : ResultStatement
     {
         $stmt = new Statement(parent::executeQuery($query, $params, $types, $qcp), $this);
         $stmt->setFetchMode($this->defaultFetchMode);
@@ -107,9 +109,9 @@ class Connection extends \Doctrine\DBAL\Connection
     /**
      * {@inheritdoc}
      */
-    public function prepare($statement)
+    public function prepare(string $sql) : DriverStatement
     {
-        $stmt = new Statement(parent::prepare($statement), $this);
+        $stmt = new Statement(parent::prepare($sql), $this);
         $stmt->setFetchMode($this->defaultFetchMode);
 
         return $stmt;
@@ -118,7 +120,7 @@ class Connection extends \Doctrine\DBAL\Connection
     /**
      * {@inheritdoc}
      */
-    public function query(string $sql)
+    public function query(string $sql) : ResultStatement
     {
         $connection = $this->getWrappedConnection();
 

lib/Doctrine/DBAL/Portability/Statement.php

@@ -233,7 +233,7 @@ class Statement implements IteratorAggregate, DriverStatement
     /**
      * {@inheritdoc}
      */
-    public function rowCount()
+    public function rowCount() : int
     {
         assert($this->stmt instanceof DriverStatement);
 

lib/Doctrine/DBAL/Statement.php

@@ -256,7 +256,7 @@ class Statement implements IteratorAggregate, DriverStatement
      *
      * @return int The number of affected rows.
      */
-    public function rowCount()
+    public function rowCount() : int
     {
         return $this->stmt->rowCount();
     }

tests/Doctrine/Tests/DBAL/Functional/Driver/SQLSrv/StatementTest.php

@@ -27,7 +27,7 @@ class StatementTest extends DbalFunctionalTestCase
     public function testFailureToPrepareResultsInException() : void
     {
         // use the driver connection directly to avoid having exception wrapped
-        $stmt = $this->connection->getWrappedConnection()->prepare(null);
+        $stmt = $this->connection->getWrappedConnection()->prepare('');
 
         // it's impossible to prepare the statement without bound variables for SQL Server,
         // so the preparation happens before the first execution when variables are already in place

tests/Doctrine/Tests/DBAL/StatementTest.php

@@ -7,6 +7,7 @@ use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\Driver;
 use Doctrine\DBAL\Driver\Connection as DriverConnection;
+use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use Doctrine\DBAL\Logging\SQLLogger;
 use Doctrine\DBAL\ParameterType;
 use Doctrine\DBAL\Statement;
@@ -23,18 +24,15 @@ class StatementTest extends DbalTestCase
     private $configuration;
 
     /** @var PDOStatement */
-    private $pdoStatement;
+    private $driverStatement;
 
     protected function setUp() : void
     {
-        $this->pdoStatement = $this->getMockBuilder(PDOStatement::class)
-            ->onlyMethods(['execute', 'bindParam', 'bindValue'])
-            ->getMock();
+        $this->driverStatement = $this->createMock(DriverStatement::class);
 
-        $driverConnection = $this->createMock(DriverConnection::class);
-        $driverConnection->expects($this->any())
-                ->method('prepare')
-                ->will($this->returnValue($this->pdoStatement));
+        $driverConnection = $this->createConfiguredMock(DriverConnection::class, [
+            'prepare' => $this->driverStatement,
+        ]);
 
         $driver = $this->createMock(Driver::class);
 
@@ -140,7 +138,7 @@ class StatementTest extends DbalTestCase
         $logger->expects($this->once())
             ->method('stopQuery');
 
-        $this->pdoStatement->expects($this->once())
+        $this->driverStatement->expects($this->once())
             ->method('execute')
             ->will($this->throwException(new Exception('Mock test exception')));