Merge pull request #4130 from morozov/missing-driver-exception-annotations

Missing driver exception annotations

UPGRADE.md

 # Upgrade to 3.0
 
+## BC BREAK: More driver-level methods are allowed to throw a Driver\Exception.
+
+The following driver-level methods are allowed to throw a Driver\Exception:
+
+- `Connection::prepare()`
+- `Connection::query()`
+- `Connection::exec()`
+- `Connection::lastInsertId()`
+- `Connection::beginTransaction()`
+- `Connection::commit()`
+- `Connection::rollBack()`
+- `ServerInfoAwareConnection::getServerVersion()`
+- `Statement::bindParam()`
+- `Statement::bindValue()`
+- `Result::rowCount()`
+- `Result::columnCount()`
+
+The driver-level implementations of `Connection::query()` and `Connection::exec()` may no longer throw a `DBALException`.
+
 ## The `ExceptionConverterDriver` interface is removed
 
 All drivers must implement the `convertException()` method which is now part of the `Driver` interface.

src/Driver/Connection.php

@@ -2,7 +2,6 @@
 
 namespace Doctrine\DBAL\Driver;
 
-use Doctrine\DBAL\DBALException;
 use Doctrine\DBAL\ParameterType;
 
 /**
@@ -15,13 +14,15 @@ interface Connection
 {
     /**
      * Prepares a statement for execution and returns a Statement object.
+     *
+     * @throws Exception
      */
     public function prepare(string $sql): Statement;
 
     /**
      * Executes an SQL statement, returning a result set as a Statement object.
      *
-     * @throws DBALException
+     * @throws Exception
      */
     public function query(string $sql): Result;
 
@@ -38,7 +39,7 @@ interface Connection
     /**
      * Executes an SQL statement and return the number of affected rows.
      *
-     * @throws DBALException
+     * @throws Exception
      */
     public function exec(string $statement): int;
 
@@ -48,6 +49,8 @@ interface Connection
      * @param string|null $name
      *
      * @return string
+     *
+     * @throws Exception
      */
     public function lastInsertId($name = null);
 
@@ -55,6 +58,8 @@ interface Connection
      * Initiates a transaction.
      *
      * @return bool TRUE on success or FALSE on failure.
+     *
+     * @throws Exception
      */
     public function beginTransaction();
 
@@ -62,6 +67,8 @@ interface Connection
      * Commits a transaction.
      *
      * @return bool TRUE on success or FALSE on failure.
+     *
+     * @throws Exception
      */
     public function commit();
 
@@ -69,6 +76,8 @@ interface Connection
      * Rolls back the current transaction, as initiated by beginTransaction().
      *
      * @return bool TRUE on success or FALSE on failure.
+     *
+     * @throws Exception
      */
     public function rollBack();
 }

src/Driver/Mysqli/Exception/UnknownType.php → src/Driver/Exception/UnknownParameterType.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Doctrine\DBAL\Driver\Mysqli\Exception;
+namespace Doctrine\DBAL\Driver\Exception;
 
 use Doctrine\DBAL\Driver\AbstractException;
 
@@ -13,13 +13,13 @@ use function sprintf;
  *
  * @psalm-immutable
  */
-final class UnknownType extends AbstractException
+final class UnknownParameterType extends AbstractException
 {
     /**
      * @param mixed $type
      */
     public static function new($type): self
     {
-        return new self(sprintf('Unknown type, %d given.', $type));
+        return new self(sprintf('Unknown parameter type, %d given.', $type));
     }
 }

src/Driver/Mysqli/Exception/FailedReadingStreamOffset.php

@@ -15,8 +15,8 @@ use function sprintf;
  */
 final class FailedReadingStreamOffset extends AbstractException
 {
-    public static function new(int $offset): self
+    public static function new(int $parameter): self
     {
-        return new self(sprintf('Failed reading the stream resource for parameter offset %d.', $offset));
+        return new self(sprintf('Failed reading the stream resource for parameter #%d.', $parameter));
     }
 }

src/Driver/Mysqli/Exception/NonStreamResourceUsedAsLargeObject.php

+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Driver\Mysqli\Exception;
+
+use Doctrine\DBAL\Driver\AbstractException;
+
+use function sprintf;
+
+/**
+ * @internal
+ *
+ * @psalm-immutable
+ */
+final class NonStreamResourceUsedAsLargeObject extends AbstractException
+{
+    public static function new(int $parameter): self
+    {
+        return new self(
+            sprintf('The resource passed as a LARGE_OBJECT parameter #%d must be of type "stream"', $parameter)
+        );
+    }
+}

src/Driver/Mysqli/Statement.php

@@ -3,13 +3,13 @@
 namespace Doctrine\DBAL\Driver\Mysqli;
 
 use Doctrine\DBAL\Driver\Exception;
+use Doctrine\DBAL\Driver\Exception\UnknownParameterType;
 use Doctrine\DBAL\Driver\Mysqli\Exception\ConnectionError;
 use Doctrine\DBAL\Driver\Mysqli\Exception\FailedReadingStreamOffset;
+use Doctrine\DBAL\Driver\Mysqli\Exception\NonStreamResourceUsedAsLargeObject;
 use Doctrine\DBAL\Driver\Mysqli\Exception\StatementError;
-use Doctrine\DBAL\Driver\Mysqli\Exception\UnknownType;
 use Doctrine\DBAL\Driver\Result as ResultInterface;
 use Doctrine\DBAL\Driver\Statement as StatementInterface;
-use Doctrine\DBAL\Exception\InvalidArgumentException;
 use Doctrine\DBAL\ParameterType;
 use mysqli;
 use mysqli_stmt;
@@ -91,7 +91,7 @@ final class Statement implements StatementInterface
         assert(is_int($column));
 
         if (! isset(self::$_paramTypeMap[$type])) {
-            throw UnknownType::new($type);
+            throw UnknownParameterType::new($type);
         }
 
         $this->_bindedValues[$column] =& $variable;
@@ -108,7 +108,7 @@ final class Statement implements StatementInterface
         assert(is_int($param));
 
         if (! isset(self::$_paramTypeMap[$type])) {
-            throw UnknownType::new($type);
+            throw UnknownParameterType::new($type);
         }
 
         $this->_values[$param]       = $value;
@@ -142,6 +142,8 @@ final class Statement implements StatementInterface
 
     /**
      * Binds parameters with known types previously bound to the statement
+     *
+     * @throws Exception
      */
     private function bindTypedParameters(): void
     {
@@ -158,7 +160,7 @@ final class Statement implements StatementInterface
             if ($types[$parameter - 1] === static::$_paramTypeMap[ParameterType::LARGE_OBJECT]) {
                 if (is_resource($value)) {
                     if (get_resource_type($value) !== 'stream') {
-                        throw new InvalidArgumentException('Resources passed with the LARGE_OBJECT parameter type must be stream resources.');
+                        throw NonStreamResourceUsedAsLargeObject::new($parameter);
                     }
 
                     $streams[$parameter] = $value;

src/Driver/OCI8/Connection.php

@@ -11,9 +11,9 @@ use Doctrine\DBAL\Driver\Result as ResultInterface;
 use Doctrine\DBAL\Driver\ServerInfoAwareConnection;
 use Doctrine\DBAL\Driver\Statement as DriverStatement;
 use Doctrine\DBAL\ParameterType;
-use UnexpectedValueException;
 
 use function addcslashes;
+use function assert;
 use function is_float;
 use function is_int;
 use function oci_commit;
@@ -22,7 +22,6 @@ use function oci_pconnect;
 use function oci_rollback;
 use function oci_server_version;
 use function preg_match;
-use function sprintf;
 use function str_replace;
 
 use const OCI_NO_AUTO_COMMIT;
@@ -69,9 +68,6 @@ final class Connection implements ConnectionInterface, ServerInfoAwareConnection
 
     /**
      * {@inheritdoc}
-     *
-     * @throws UnexpectedValueException If the version string returned by the database server
-     *                                  does not contain a parsable version number.
      */
     public function getServerVersion()
     {
@@ -81,15 +77,7 @@ final class Connection implements ConnectionInterface, ServerInfoAwareConnection
             throw Error::new($this->dbh);
         }
 
-        if (preg_match('/\s+(\d+\.\d+\.\d+\.\d+\.\d+)\s+/', $version, $matches) === 0) {
-            throw new UnexpectedValueException(
-                sprintf(
-                    'Unexpected database version string "%s". Cannot parse an appropriate version number from it. ' .
-                    'Please report this database version string to the Doctrine team.',
-                    $version
-                )
-            );
-        }
+        assert(preg_match('/\s+(\d+\.\d+\.\d+\.\d+\.\d+)\s+/', $version, $matches) === 1);
 
         return $matches[1];
     }

src/Driver/OCI8/Statement.php

@@ -2,6 +2,7 @@
 
 namespace Doctrine\DBAL\Driver\OCI8;
 
+use Doctrine\DBAL\Driver\Exception;
 use Doctrine\DBAL\Driver\OCI8\Exception\Error;
 use Doctrine\DBAL\Driver\OCI8\Exception\UnknownParameterIndex;
 use Doctrine\DBAL\Driver\Result as ResultInterface;
@@ -54,6 +55,8 @@ final class Statement implements StatementInterface
      *
      * @param resource $dbh   The connection handle.
      * @param string   $query The SQL query.
+     *
+     * @throws Exception
      */
     public function __construct($dbh, $query, ExecutionMode $executionMode)
     {

src/Driver/PDO/Result.php

@@ -90,11 +90,7 @@ final class Result implements ResultInterface
 
     public function free(): void
     {
-        try {
-            $this->statement->closeCursor();
-        } catch (PDOException $exception) {
-            throw Exception::new($exception);
-        }
+        $this->statement->closeCursor();
     }
 
     /**

src/Driver/PDO/Statement.php

@@ -2,10 +2,11 @@
 
 namespace Doctrine\DBAL\Driver\PDO;
 
+use Doctrine\DBAL\Driver\Exception as ExceptionInterface;
+use Doctrine\DBAL\Driver\Exception\UnknownParameterType;
 use Doctrine\DBAL\Driver\Result as ResultInterface;
 use Doctrine\DBAL\Driver\Statement as StatementInterface;
 use Doctrine\DBAL\ParameterType;
-use InvalidArgumentException;
 use PDO;
 use PDOException;
 use PDOStatement;
@@ -50,6 +51,8 @@ class Statement implements StatementInterface
     }
 
     /**
+     * {@inheritDoc}
+     *
      * @param mixed    $column
      * @param mixed    $variable
      * @param int      $type
@@ -87,11 +90,13 @@ class Statement implements StatementInterface
      * Converts DBAL parameter type to PDO parameter type
      *
      * @param int $type Parameter type
+     *
+     * @throws ExceptionInterface
      */
     private function convertParamType(int $type): int
     {
         if (! isset(self::PARAM_TYPE_MAP[$type])) {
-            throw new InvalidArgumentException('Invalid parameter type: ' . $type);
+            throw UnknownParameterType::new($type);
         }
 
         return self::PARAM_TYPE_MAP[$type];

src/Driver/PDOSqlsrv/Driver.php

@@ -4,6 +4,7 @@ namespace Doctrine\DBAL\Driver\PDOSqlsrv;
 
 use Doctrine\DBAL\Driver\AbstractSQLServerDriver;
 use Doctrine\DBAL\Driver\AbstractSQLServerDriver\Exception\PortWithoutHost;
+use Doctrine\DBAL\Driver\Exception;
 use PDO;
 
 use function is_int;
@@ -50,6 +51,8 @@ class Driver extends AbstractSQLServerDriver
      * @param string[] $connectionOptions
      *
      * @return string The DSN.
+     *
+     * @throws Exception
      */
     private function _constructPdoDsn(array $params, array $connectionOptions)
     {

src/Driver/Result.php

@@ -71,6 +71,8 @@ interface Result
      * is not guaranteed for all drivers and should not be relied on in portable applications.
      *
      * @return int The number of rows.
+     *
+     * @throws Exception
      */
     public function rowCount(): int;
 
@@ -79,6 +81,8 @@ interface Result
      *
      * @return int The number of columns in the result. If the columns cannot be counted,
      *             this method must return 0.
+     *
+     * @throws Exception
      */
     public function columnCount(): int;
 

src/Driver/ServerInfoAwareConnection.php

@@ -11,6 +11,8 @@ interface ServerInfoAwareConnection extends Connection
      * Returns the version number of the database server connected to.
      *
      * @return string
+     *
+     * @throws Exception
      */
     public function getServerVersion();
 }

src/Driver/Statement.php

@@ -24,6 +24,8 @@ interface Statement
      *                          constants.
      *
      * @return bool TRUE on success or FALSE on failure.
+     *
+     * @throws Exception
      */
     public function bindValue($param, $value, $type = ParameterType::STRING);
 
@@ -51,6 +53,8 @@ interface Statement
      *                             so that PHP allocates enough memory to hold the returned value.
      *
      * @return bool TRUE on success or FALSE on failure.
+     *
+     * @throws Exception
      */
     public function bindParam($column, &$variable, $type = ParameterType::STRING, $length = null);