Do not implement driver-level interfaces by wrapper-level classes

[morozov]

Q	A
Type	improvement
BC Break	yes

There are certain downsides of having the wrapper-level classes have to implement the driver-level interfaces:

1. Alongside the executeQuery() and executeUpdate() methods, the wrapper connection has to implement query() and exec() just because the interface declares them. Although, API-wise the latter two are just the subset of the former.

2. Prior to PHP 7.4, the return type contravariance is not supported (https://3v4l.org/dNsho) which means that the wrapper-level classes cannot declare their return type specifically enough and have to declare the type just as prescribed by the lower-level interface.

3. The fact that the wrappers implement the driver interfaces makes it harder to evolve the wrapper layer independently of the driver one. E.g. we cannot add a new (even optional) argument to any of the wrapper methods that are declared in the driver interface without a BC break.

4. Unlike the driver-level classes that are allowed to throw driver exceptions and only them, the wrapper-level classes are not allowed to throw driver-level exceptions but are allowed to throw wrapper-level exceptions. This leads to the following issues:

   1. If a consumer uses a wrapper class as a driver interface implementation, it will expect a driver-level exception to be thrown but will get a wrapper-level one.
   2. If a consumer uses a wrapper class as such, it will expect a wrapper-level exception to be thrown but the static analysis will identify it as not handling the driver-level exceptions that are allowed by the driver-level interfaces but in fact never happen.

   Strictly speaking, at this point the wrapper layer violates the interface that it's forced to implement.

As for the upsides, I haven't seen a case where a consumer should be able to use a wrapper connection as a driver one. The fact that not a single test had to be changed confirms that.

TODO:

• Add a deprecation in 2.11.x (Deprecated usage of wrapper components as implementations of driver-level interfaces #4165).

[greg0ire]

Hold on, I think https://github.com/doctrine/dbal/blob/3.0.x/docs/en/reference/architecture.rst has to be changed, for instance this sentence:

Even more, a Doctrine\DBAL\Connection is a Doctrine\DBAL\Driver\Connection and a Doctrine\DBAL\Statement is a Doctrine\DBAL\Driver\Statement.

missing doc changes

[morozov]

[…] https://github.com/doctrine/dbal/blob/3.0.x/docs/en/reference/architecture.rst has to be changed, for instance this sentence:

Even more, a Doctrine\DBAL\Connection is a Doctrine\DBAL\Driver\Connection and a Doctrine\DBAL\Statement is a Doctrine\DBAL\Driver\Statement.

Yeah, this is no longer true, so I'll just remove it. There are some other bits outdated as of 3.0.0-dev but I'll update them in a separate PR (#4164).