Deprecate extension via Doctrine Event Manager

UPGRADE.md

@@ -8,6 +8,27 @@ awareness about deprecated code.
 
 # Upgrade to 3.5
 
+## Deprecated extension via Doctrine Event Manager
+
+Extension of the library behavior via Doctrine Event Manager has been deprecated.
+
+The following methods and properties have been deprecated:
+- `AbstractPlatform::$_eventManager`,
+- `AbstractPlatform::getEventManager()`,
+- `AbstractPlatform::setEventManager()`,
+- `Connection::$_eventManager`,
+- `Connection::getEventManager()`.
+
+## Deprecated extension via connection events
+
+Subscription to the `postConnect` event has been deprecated. Use one of the following replacements for the standard
+event listeners or implement a custom middleware instead.
+
+The following `postConnect` event listeners have been deprecated:
+1. `OracleSessionInit`. Use `Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession`.
+2. `SQLiteSessionInit`. Use `Doctrine\DBAL\Driver\AbstractSQLiteDriver\Middleware\EnableForeignKeys`.
+3. `SQLSessionInit`. Implement a custom middleware.
+
 ## Deprecated extension via transaction events
 
 Subscription to the following events has been deprecated:

ci/github/phpunit/oci8.xml

@@ -17,7 +17,6 @@
         <var name="db_password" value="oracle"/>
         <var name="db_dbname" value="XE"/>
         <var name="db_charset" value="AL32UTF8" />
-        <var name="db_event_subscribers" value="Doctrine\DBAL\Event\Listeners\OracleSessionInit"/>
 
         <var name="tmpdb_driver" value="oci8"/>
         <var name="tmpdb_host" value="localhost"/>

ci/github/phpunit/pdo_oci.xml

@@ -17,7 +17,6 @@
         <var name="db_password" value="oracle"/>
         <var name="db_dbname" value="XE"/>
         <var name="db_charset" value="AL32UTF8" />
-        <var name="db_event_subscribers" value="Doctrine\DBAL\Event\Listeners\OracleSessionInit"/>
 
         <var name="tmpdb_driver" value="pdo_oci"/>
         <var name="tmpdb_host" value="localhost"/>

ci/github/phpunit/pdo_sqlite.xml

@@ -13,7 +13,6 @@
 
         <var name="db_driver" value="pdo_sqlite"/>
         <var name="db_memory" value="true"/>
-        <var name="db_event_subscribers" value="Doctrine\DBAL\Event\Listeners\SQLiteSessionInit"/>
     </php>
 
     <testsuites>

ci/github/phpunit/sqlite3.xml

@@ -13,7 +13,6 @@
 
         <var name="db_driver" value="sqlite3"/>
         <var name="db_memory" value="true"/>
-        <var name="db_event_subscribers" value="Doctrine\DBAL\Event\Listeners\SQLiteSessionInit"/>
     </php>
 
     <testsuites>

docs/en/sidebar.rst

@@ -11,7 +11,6 @@
     reference/types
     reference/schema-manager
     reference/schema-representation
-    reference/events
     reference/security
     reference/supporting-other-databases
     reference/portability

psalm.xml.dist

@@ -118,6 +118,11 @@
                 <referencedClass name="Doctrine\DBAL\Event\TransactionBeginEventArgs"/>
                 <referencedClass name="Doctrine\DBAL\Event\TransactionCommitEventArgs"/>
                 <referencedClass name="Doctrine\DBAL\Event\TransactionRollBackEventArgs"/>
+                <referencedClass name="Doctrine\DBAL\Event\ConnectionEventArgs"/>
+                <referencedClass name="Doctrine\DBAL\Event\Listeners\OracleSessionInit"/>
+                <referencedClass name="Doctrine\DBAL\Event\Listeners\SQLSessionInit"/>
+                <referencedClass name="Doctrine\DBAL\Event\Listeners\SQLiteSessionInit"/>
+                <referencedClass name="Doctrine\DBAL\Events"/>
             </errorLevel>
         </DeprecatedClass>
         <DeprecatedConstant>
@@ -142,9 +147,15 @@
                     TODO: remove in 4.0.0
                 -->
                 <file name="src/Connection.php"/>
+                <file name="src/Connections/PrimaryReadReplicaConnection.php"/>
+                <file name="src/Event/Listeners/OracleSessionInit.php"/>
+                <file name="src/Event/Listeners/SQLSessionInit.php"/>
+                <file name="src/Event/Listeners/SQLiteSessionInit.php"/>
                 <file name="src/Platforms/AbstractPlatform.php"/>
                 <file name="src/Schema/AbstractSchemaManager.php"/>
                 <file name="tests/ConnectionTest.php"/>
+                <file name="tests/Events/OracleSessionInitTest.php"/>
+                <file name="tests/Events/SQLSessionInitTest.php"/>
                 <file name="tests/Functional/Schema/SchemaManagerFunctionalTestCase.php"/>
                 <file name="tests/Platforms/AbstractPlatformTestCase.php"/>
             </errorLevel>
@@ -481,6 +492,11 @@
                     TODO: remove in 4.0.0
                 -->
                 <referencedMethod name="Doctrine\DBAL\Query\QueryBuilder::getConnection"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedMethod name="Doctrine\DBAL\Connection::getEventManager"/>
+                <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::setEventManager"/>
             </errorLevel>
         </DeprecatedMethod>
         <DeprecatedProperty>
@@ -534,6 +550,11 @@
                     TODO: remove in 4.0.0
                 -->
                 <referencedProperty name="Doctrine\DBAL\Schema\SchemaDiff::$orphanedForeignKeys"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedProperty name="Doctrine\DBAL\Connection::$_eventManager"/>
+                <referencedProperty name="Doctrine\DBAL\Platforms\AbstractPlatform::$_eventManager"/>
             </errorLevel>
         </DeprecatedProperty>
         <DocblockTypeContradiction>

src/Connection.php

@@ -80,7 +80,11 @@ class Connection
     /** @var Configuration */
     protected $_config;
 
-    /** @var EventManager */
+    /**
+     * @deprecated
+     *
+     * @var EventManager
+     */
     protected $_eventManager;
 
     /**
@@ -256,10 +260,19 @@ public function getConfiguration()
     /**
      * Gets the EventManager used by the Connection.
      *
+     * @deprecated
+     *
      * @return EventManager
      */
     public function getEventManager()
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/issues/5784',
+            '%s is deprecated.',
+            __METHOD__,
+        );
+
         return $this->_eventManager;
     }
 
@@ -340,6 +353,13 @@ public function connect()
         }
 
         if ($this->_eventManager->hasListeners(Events::postConnect)) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/issues/5784',
+                'Subscribing to %s events is deprecated. Implement a middleware instead.',
+                Events::postConnect,
+            );
+
             $eventArgs = new Event\ConnectionEventArgs($this);
             $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
         }

src/Connections/PrimaryReadReplicaConnection.php

@@ -13,6 +13,7 @@
 use Doctrine\DBAL\Events;
 use Doctrine\DBAL\Exception;
 use Doctrine\DBAL\Statement;
+use Doctrine\Deprecations\Deprecation;
 use InvalidArgumentException;
 
 use function array_rand;
@@ -199,6 +200,13 @@ protected function performConnect(?string $connectionName = null): bool
         }
 
         if ($this->_eventManager->hasListeners(Events::postConnect)) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/issues/5784',
+                'Subscribing to %s events is deprecated. Implement a middleware instead.',
+                Events::postConnect,
+            );
+
             $eventArgs = new ConnectionEventArgs($this);
             $this->_eventManager->dispatchEvent(Events::postConnect, $eventArgs);
         }

src/Driver/AbstractSQLiteDriver/Middleware/EnableForeignKeys.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Doctrine\DBAL\Driver\AbstractSQLiteDriver\Middleware;
+
+use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Driver\Connection;
+use Doctrine\DBAL\Driver\Middleware;
+use Doctrine\DBAL\Driver\Middleware\AbstractDriverMiddleware;
+
+class EnableForeignKeys implements Middleware
+{
+    public function wrap(Driver $driver): Driver
+    {
+        return new class ($driver) extends AbstractDriverMiddleware {
+            /**
+             * {@inheritDoc}
+             */
+            public function connect(array $params): Connection
+            {
+                $connection = parent::connect($params);
+
+                $connection->exec('PRAGMA foreign_keys=ON');
+
+                return $connection;
+            }
+        };
+    }
+}

src/Driver/OCI8/Middleware/InitializeSession.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Doctrine\DBAL\Driver\OCI8\Middleware;
+
+use Doctrine\DBAL\Driver;
+use Doctrine\DBAL\Driver\Connection;
+use Doctrine\DBAL\Driver\Middleware;
+use Doctrine\DBAL\Driver\Middleware\AbstractDriverMiddleware;
+
+class InitializeSession implements Middleware
+{
+    public function wrap(Driver $driver): Driver
+    {
+        return new class ($driver) extends AbstractDriverMiddleware {
+            /**
+             * {@inheritDoc}
+             */
+            public function connect(array $params): Connection
+            {
+                $connection = parent::connect($params);
+
+                $connection->exec(
+                    'ALTER SESSION SET'
+                        . " NLS_DATE_FORMAT = 'YYYY-MM-DD HH24:MI:SS'"
+                        . " NLS_TIME_FORMAT = 'HH24:MI:SS'"
+                        . " NLS_DATE_FORMAT = 'YYYY-MM-DD HH24:MI:SS'"
+                        . " NLS_TIMESTAMP_FORMAT = 'YYYY-MM-DD HH24:MI:SS'"
+                        . " NLS_TIMESTAMP_TZ_FORMAT = 'YYYY-MM-DD HH24:MI:SS TZH:TZM'"
+                        . " NLS_NUMERIC_CHARACTERS = '.,'",
+                );
+
+                return $connection;
+            }
+        };
+    }
+}

src/Event/ConnectionEventArgs.php

@@ -7,6 +7,8 @@
 
 /**
  * Event Arguments used when a Driver connection is established inside Doctrine\DBAL\Connection.
+ *
+ * @deprecated
  */
 class ConnectionEventArgs extends EventArgs
 {

src/Event/Listeners/OracleSessionInit.php

@@ -23,6 +23,8 @@
  * NLS_DATE_FORMAT="YYYY-MM-DD HH24:MI:SS"
  * NLS_TIMESTAMP_FORMAT="YYYY-MM-DD HH24:MI:SS"
  * NLS_TIMESTAMP_TZ_FORMAT="YYYY-MM-DD HH24:MI:SS TZH:TZM"
+ *
+ * @deprecated Use {@see \Doctrine\DBAL\Driver\OCI8\Middleware\InitializeSession} instead.
  */
 class OracleSessionInit implements EventSubscriber
 {

src/Event/Listeners/SQLSessionInit.php

@@ -9,6 +9,8 @@
 
 /**
  * Session init listener for executing a single SQL statement right after a connection is opened.
+ *
+ * @deprecated Implement a middleware instead.
  */
 class SQLSessionInit implements EventSubscriber
 {

src/Event/Listeners/SQLiteSessionInit.php

@@ -7,6 +7,7 @@
 use Doctrine\DBAL\Events;
 use Doctrine\DBAL\Exception;
 
+/** @deprecated Use {@see \Doctrine\DBAL\Driver\AbstractSQLiteDriver\Middleware\EnableForeignKeys} instead. */
 class SQLiteSessionInit implements EventSubscriber
 {
     /**

src/Events.php

@@ -6,6 +6,8 @@
  * Container for all DBAL events.
  *
  * This class cannot be instantiated.
+ *
+ * @deprecated
  */
 final class Events
 {
@@ -18,6 +20,7 @@ private function __construct()
     {
     }
 
+    /** @deprecated */
     public const postConnect = 'postConnect';
 
     /** @deprecated */