Merge pull request #7905 from cakephp/5.next-events-hook

5.next: add docs related to new events hook

Author: markstory

en/appendices/5-1-migration-guide.rst

@@ -88,6 +88,8 @@ Core
 - The ``toString``, ``toInt``, ``toBool`` functions were added. They give you
   a typesafe way to cast request data or other input and return ``null`` when conversion fails.
 - ``pathCombine()`` was added to help build paths without worrying about duplicate and trailing slashes.
+- A new ``events`` hook was added to the ``BaseApplication`` as well as the ``BasePlugin`` class. This hook
+  is the recommended way to register global event listeners for you application. See :ref:`Registering Listeners <registering-event-listeners>`
 
 Database
 --------

en/core-libraries/events.rst

@@ -198,6 +198,30 @@ As you can see in the above code, the ``on()`` function will accept instances
 of the ``EventListener`` interface. Internally, the event manager will use
 ``implementedEvents()`` to attach the correct callbacks.
 
+.. versionadded:: 5.1.0
+    The ``events`` hook was added to the ``BaseApplication`` as well as the ``BasePlugin`` class
+
+As of CakePHP 5.1 it is recommended to register event listeners by adding them via the ``events`` hook in your application or plugin class::
+
+    namespace App;
+    
+    use App\Event\UserStatistic;
+    use Cake\Event\EventManagerInterface;
+    use Cake\Http\BaseApplication;
+
+    class Application extends BaseApplication
+    {
+        // The rest of your Application class
+
+        public function events(EventManagerInterface $eventManager): EventManagerInterface
+        {
+            $statistics = new UserStatistic();
+            $eventManager->on($statistics);
+
+            return $eventManager;
+        }
+    }
+
 Registering Anonymous Listeners
 -------------------------------