Merge release 3.2.2 into 3.3.x (#5186)

docs/en/reference/architecture.rst

@@ -12,11 +12,6 @@ and a ``Doctrine\DBAL\Result`` wraps a ``Doctrine\DBAL\Driver\Result``.
 and ``Doctrine\DBAL\Driver\Result`` are just interfaces.
 These interfaces are implemented by concrete drivers.
 
-What do the wrapper components add to the underlying driver
-implementations? The enhancements include SQL logging, events and
-control over the transaction isolation level in a portable manner,
-among others.
-
 Apart from the three main components, a DBAL driver should also provide
 an implementation of the ``Doctrine\DBAL\Driver`` interface that
 has two primary purposes:
@@ -26,18 +21,40 @@ has two primary purposes:
 2. Act as a factory of other driver-specific components like
    platform, schema manager and exception converter.
 
+The driver components can be decorated using the four driver interfaces in
+order to add driver-independent functionality like logging or profiling. Those
+decorators are configured as a middleware.
+
+The wrapper components ``Connection``, ``Statement`` and ``Result`` are the
+objects that the application usually interacts with directly. They wrap the
+middleware stack as well as the driver at the bottom of that stack.
+
 The DBAL is separated into several different packages that
 separate responsibilities of the different RDBMS layers.
 
 Drivers
 -------
 
-The drivers abstract a PHP specific database API by enforcing three
+The drivers abstract a PHP specific database API by enforcing four
 interfaces:
 
--  ``\Doctrine\DBAL\Driver\Connection``
--  ``\Doctrine\DBAL\Driver\Statement``
--  ``\Doctrine\DBAL\Driver\Result``
+-  ``Doctrine\DBAL\Driver``
+-  ``Doctrine\DBAL\Driver\Connection``
+-  ``Doctrine\DBAL\Driver\Statement``
+-  ``Doctrine\DBAL\Driver\Result``
+
+Middlewares
+-----------
+
+A middleware sits in the middle between the wrapper components and the driver.
+By implementing the ``Doctrine\DBAL\Driver\Middleware``, it decorates the
+``Driver`` component of either the actual driver or a lower middleware. If
+necessary, the middleware might also decorate ``Connection``, ``Statement``
+and ``Result``.
+
+An example for a middleware implementation is
+``Doctrine\DBAL\Logging\Middleware`` which implements logging capabilities
+on top of a driver.
 
 Platforms
 ---------
@@ -72,4 +89,3 @@ The types offer an abstraction layer for the converting and
 generation of types between Databases and PHP. Doctrine comes
 bundled with some common types but offers the ability for
 developers to define custom types or extend existing ones easily.
-