Merge pull request #6000 from kenjis/deprecate-const-EVENT_PRIORITY

refactor: deprecate const `EVENT_PRIORITY_*`

Author: kenjis

app/Config/Constants.php

@@ -77,3 +77,18 @@
 defined('EXIT_DATABASE')       || define('EXIT_DATABASE', 8); // database error
 defined('EXIT__AUTO_MIN')      || define('EXIT__AUTO_MIN', 9); // lowest automatically-assigned error code
 defined('EXIT__AUTO_MAX')      || define('EXIT__AUTO_MAX', 125); // highest automatically-assigned error code
+
+/**
+ * @deprecated Use \CodeIgniter\Events\Events::PRIORITY_LOW instead.
+ */
+define('EVENT_PRIORITY_LOW', 200);
+
+/**
+ * @deprecated Use \CodeIgniter\Events\Events::PRIORITY_NORMAL instead.
+ */
+define('EVENT_PRIORITY_NORMAL', 100);
+
+/**
+ * @deprecated Use \CodeIgniter\Events\Events::PRIORITY_HIGH instead.
+ */
+define('EVENT_PRIORITY_HIGH', 10);

system/Events/Events.php

@@ -14,15 +14,15 @@
 use Config\Modules;
 use Config\Services;
 
-define('EVENT_PRIORITY_LOW', 200);
-define('EVENT_PRIORITY_NORMAL', 100);
-define('EVENT_PRIORITY_HIGH', 10);
-
 /**
  * Events
  */
 class Events
 {
+    public const PRIORITY_LOW    = 200;
+    public const PRIORITY_NORMAL = 100;
+    public const PRIORITY_HIGH   = 10;
+
     /**
      * The list of listeners.
      *

tests/system/Events/EventsTest.php

@@ -157,15 +157,15 @@ public function testPriorityWithMultiple()
 
         Events::on('foo', static function () use (&$result) {
             $result[] = 'a';
-        }, EVENT_PRIORITY_NORMAL);
+        }, Events::PRIORITY_NORMAL);
 
         Events::on('foo', static function () use (&$result) {
             $result[] = 'b';
-        }, EVENT_PRIORITY_LOW);
+        }, Events::PRIORITY_LOW);
 
         Events::on('foo', static function () use (&$result) {
             $result[] = 'c';
-        }, EVENT_PRIORITY_HIGH);
+        }, Events::PRIORITY_HIGH);
 
         Events::on('foo', static function () use (&$result) {
             $result[] = 'd';

user_guide_src/source/changelogs/v4.2.0.rst

@@ -103,6 +103,7 @@ Deprecations
 - ``CodeIgniter\Router\Router::setDefaultController()`` is deprecated.
 - The constant ``SPARKED`` in **spark** is deprecated. Use the ``$context`` property in ``CodeIgniter\CodeIgniter`` instead.
 - ``CodeIgniter\Autoloader\Autoloader::discoverComposerNamespaces()`` is deprecated, and no longer used.
+- The constants ``EVENT_PRIORITY_LOW``, ``EVENT_PRIORITY_NORMAL`` and ``EVENT_PRIORITY_HIGH`` are deprecated. Use the class constants ``CodeIgniter\Events\Events::PRIORITY_LOW``, ``CodeIgniter\Events\Events::PRIORITY_NORMAL`` and ``CodeIgniter\Events\Events::PRIORITY_HIGH`` instead.
 
 Bugs Fixed
 **********

user_guide_src/source/extending/events.rst

@@ -46,11 +46,13 @@ are executed first, with a value of 1 having the highest priority, and there bei
 
 Any subscribers with the same priority will be executed in the order they were defined.
 
-Three constants are defined for your use, that set some helpful ranges on the values. You are not required to use these
+Since v4.2.0, three class constants are defined for your use, that set some helpful ranges on the values. You are not required to use these
 but you might find they aid readability:
 
 .. literalinclude:: events/004.php
 
+.. note:: The constants ``EVENT_PRIORITY_LOW``, ``EVENT_PRIORITY_NORMAL`` and ``EVENT_PRIORITY_HIGH`` are deprecated, and the definitions are moved to ``app/Config/Constants.php``.
+
 Once sorted, all subscribers are executed in order. If any subscriber returns a boolean false value, then execution of
 the subscribers will stop.
 

user_guide_src/source/extending/events/004.php

@@ -1,5 +1,7 @@
 <?php
 
-define('EVENT_PRIORITY_LOW', 200);
-define('EVENT_PRIORITY_NORMAL', 100);
-define('EVENT_PRIORITY_HIGH', 10);
+use CodeIgniter\Events\Events;
+
+Events::PRIORITY_LOW;    // 200
+Events::PRIORITY_NORMAL; // 100
+Events::PRIORITY_HIGH;   // 10

user_guide_src/source/installation/upgrade_420.rst

@@ -15,12 +15,20 @@ Please refer to the upgrade instructions corresponding to your installation meth
 Mandatory File Changes
 **********************
 
+index.php and spark
+===================
+
 The following files received significant changes and
 **you must merge the updated versions** with your application:
 
 * ``public/index.php``
 * ``spark``
 
+Config/Constants.php
+====================
+
+The constants ``EVENT_PRIORITY_LOW``, ``EVENT_PRIORITY_NORMAL`` and ``EVENT_PRIORITY_HIGH`` are deprecated, and the definitions are moved to ``app/Config/Constants.php``. If you use these constants, define them in ``app/Config/Constants.php``. Or use new class constants ``CodeIgniter\Events\Events::PRIORITY_LOW``, ``CodeIgniter\Events\Events::PRIORITY_NORMAL`` and ``CodeIgniter\Events\Events::PRIORITY_HIGH``.
+
 Breaking Changes
 ****************