From 10988f80e4f111fa7da88707d0d4a64650393096 Mon Sep 17 00:00:00 2001
From: Sergei Morozov <morozov@tut.by>
Date: Fri, 21 Oct 2022 16:34:23 -0700
Subject: [PATCH] Deprecate extension via Doctrine Event Manager

---
 UPGRADE.md                         | 11 ++++++++++
 docs/en/reference/events.rst       | 33 ------------------------------
 docs/en/sidebar.rst                |  1 -
 psalm.xml.dist                     | 11 ++++++++++
 src/Connection.php                 | 15 +++++++++++++-
 src/Events.php                     |  2 ++
 src/Platforms/AbstractPlatform.php | 24 +++++++++++++++++++++-
 7 files changed, 61 insertions(+), 36 deletions(-)
 delete mode 100644 docs/en/reference/events.rst

diff --git a/UPGRADE.md b/UPGRADE.md
index c14a776c921..a119fd932f2 100644
--- a/UPGRADE.md
+++ b/UPGRADE.md
@@ -8,6 +8,17 @@ 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:
+- `AbsractPlatform::$_eventManager`,
+- `AbsractPlatform::getEventManager()`,
+- `AbsractPlatform::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
diff --git a/docs/en/reference/events.rst b/docs/en/reference/events.rst
deleted file mode 100644
index c6ba5f99f98..00000000000
--- a/docs/en/reference/events.rst
+++ /dev/null
@@ -1,33 +0,0 @@
-Events
-======
-
-Both ``Doctrine\DBAL\DriverManager`` and
-``Doctrine\DBAL\Connection`` accept an instance of
-``Doctrine\Common\EventManager``. The EventManager has a couple of
-events inside the DBAL layer that are triggered for the user to
-listen to.
-
-Schema Events
--------------
-
-There are multiple events in Doctrine DBAL that are triggered on schema changes
-of the database. It is possible to add your own event listener to be able to run
-your own code before changes to the database are committed. An instance of
-``Doctrine\Common\EventManager`` can also be added to :doc:`platforms`.
-
-A event listener class can contain one or more methods to schema events. These
-methods must be named like the events itself.
-
-.. code-block:: php
-
-    <?php
-    $evm = new EventManager();
-    $eventName = Events::onSomething;
-    $evm->addEventListener($eventName, new MyEventListener());
-
-.. code-block:: php
-
-    <?php
-    $evm = new EventManager();
-    $eventNames = [Events::onSomething, Events::onSomethingElse];
-    $evm->addEventListener($eventNames, new MyEventListener());
diff --git a/docs/en/sidebar.rst b/docs/en/sidebar.rst
index 5ca10801812..472e05c9529 100644
--- a/docs/en/sidebar.rst
+++ b/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
diff --git a/psalm.xml.dist b/psalm.xml.dist
index 901f7817635..2d2b18a9d1b 100644
--- a/psalm.xml.dist
+++ b/psalm.xml.dist
@@ -122,6 +122,7 @@
                 <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>
@@ -491,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>
@@ -544,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>
diff --git a/src/Connection.php b/src/Connection.php
index 0bf80ab6acd..364df9a9c6e 100644
--- a/src/Connection.php
+++ b/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;
     }
 
diff --git a/src/Events.php b/src/Events.php
index 0646029dd5d..37125df5357 100644
--- a/src/Events.php
+++ b/src/Events.php
@@ -6,6 +6,8 @@
  * Container for all DBAL events.
  *
  * This class cannot be instantiated.
+ *
+ * @deprecated
  */
 final class Events
 {
diff --git a/src/Platforms/AbstractPlatform.php b/src/Platforms/AbstractPlatform.php
index b1dd6e1c093..28a0eb5807b 100644
--- a/src/Platforms/AbstractPlatform.php
+++ b/src/Platforms/AbstractPlatform.php
@@ -89,7 +89,11 @@ abstract class AbstractPlatform
      */
     protected $doctrineTypeComments;
 
-    /** @var EventManager|null */
+    /**
+     * @deprecated
+     *
+     * @var EventManager|null
+     */
     protected $_eventManager;
 
     /**
@@ -102,20 +106,38 @@ abstract class AbstractPlatform
     /**
      * Sets the EventManager used by the Platform.
      *
+     * @deprecated
+     *
      * @return void
      */
     public function setEventManager(EventManager $eventManager)
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/issues/5784',
+            '%s is deprecated.',
+            __METHOD__,
+        );
+
         $this->_eventManager = $eventManager;
     }
 
     /**
      * Gets the EventManager used by the Platform.
      *
+     * @deprecated
+     *
      * @return EventManager|null
      */
     public function getEventManager()
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/issues/5784',
+            '%s is deprecated.',
+            __METHOD__,
+        );
+
         return $this->_eventManager;
     }