Rework the portability layer to act as a middleware

[morozov]

Q	A
Type	bug, improvement
BC Break	yes

Fixes #4156.

Importance

Apart from the fatal error reported in the linked issue, the current implementation blocks the decoupling of the driver and wrapper APIs. The wrapper-level Connection::prepare() declares its return type as DriverStatement (which is not intended but required by the driver-level Connection interface) however it returns a Statement (a more specific and feature-rich type):

dbal/src/Connection.php

Lines 908 to 912 in 98c23fe

	* @return Statement
	*
	* @throws DBALException
	*/
	public function prepare(string $sql): DriverStatement

Even if it stops implementing the driver connection interface, it cannot declare its return type as Statement because the Portability\Connection class currently extends it and returns a driver-level statement:

dbal/src/Portability/Statement.php

Lines 9 to 12 in 48625f1

	/**
	* Portability wrapper for a Statement.
	*/
	class Statement implements DriverStatement

The Driver Middleware concept

The concept of a driver middleware will allow extending the behavior of the DBAL connection by wrapping the underlying driver. Once the driver is wrapped, the wrapper can also wrap the connection and the statement objects effectively extending any of the behaviors. The middleware objects are registered via configuration (see example in the test).

Apart from the portability layer, it can be used to reimplement the caching layer which is currently implemented as part of the wrapper connection class.

Portability layer reworked

The portability layer has been reworked to act as middleware and implement only the driver-level APIs.