MDL-82159 core: Deprecate lib/navigationlib.php

.upgradenotes/MDL-82159-2025080707392534.yml

@@ -0,0 +1,12 @@
+issueNumber: MDL-82159
+notes:
+  core:
+    - message: |
+        The following global constants have been deprecated in favour of class
+        constants:
+
+         | Old constant                       | New constant                                              |
+         | ---                                | ---                                                       |
+         | `NAVIGATION_CACHE_NAME`            | `\core\navigation\navigation_node::CACHE_NAME`            |
+         | `NAVIGATION_SITE_ADMIN_CACHE_NAME` | `\core\navigation\navigation_node::SITE_ADMIN_CACHE_NAME` |
+      type: deprecated

public/lib/classes/navigation/global_navigation.php

@@ -138,7 +138,7 @@ class global_navigation extends navigation_node {
         // Initalise and set defaults.
         $this->page = $page;
         $this->forceopen = true;
-        $this->cache = new navigation_cache(NAVIGATION_CACHE_NAME);
+        $this->cache = new navigation_cache(self::CACHE_NAME);
     }
 
     /**

public/lib/classes/navigation/global_navigation_for_ajax.php

@@ -56,7 +56,7 @@ class global_navigation_for_ajax extends global_navigation {
      */
     public function __construct($page, $branchtype, $id) {
         $this->page = $page;
-        $this->cache = new navigation_cache(NAVIGATION_CACHE_NAME);
+        $this->cache = new navigation_cache(self::CACHE_NAME);
         $this->children = new navigation_node_collection();
         $this->branchtype = $branchtype;
         $this->instanceid = $id;

public/lib/classes/navigation/navigation_node.php

@@ -80,6 +80,12 @@ class navigation_node implements renderable {
     /** var string The course index page navigation node */
     public const COURSE_INDEX_PAGE = 'courseindexpage';
 
+    /** @var string The name that will be used for the navigation cache */
+    protected const CACHE_NAME = 'navigation';
+
+    /** @var string The name that will be used for the site admin navigation cache */
+    protected const SITE_ADMIN_CACHE_NAME = 'navigationsiteadmin';
+
     /** @var int Parameter to aid the coder in tracking [optional] */
     public $id = null;
     /** @var string|int The identifier for the node, used to retrieve the node */

public/lib/classes/navigation/settings_navigation.php

@@ -76,7 +76,7 @@ class settings_navigation extends navigation_node {
         $this->page->navigation->initialise();
 
         // Initialise the navigation cache.
-        $this->cache = new navigation_cache(NAVIGATION_CACHE_NAME);
+        $this->cache = new navigation_cache(self::CACHE_NAME);
         $this->children = new navigation_node_collection();
     }
 

public/lib/classes/navigation/settings_navigation_ajax.php

@@ -34,7 +34,7 @@ class settings_navigation_ajax extends settings_navigation {
      */
     public function __construct(moodle_page &$page) {
         $this->page = $page;
-        $this->cache = new navigation_cache(NAVIGATION_CACHE_NAME);
+        $this->cache = new navigation_cache(self::CACHE_NAME);
         $this->children = new navigation_node_collection();
         $this->initialise();
     }

public/lib/navigationlib.php

@@ -23,8 +23,23 @@
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+defined('MOODLE_INTERNAL') || die();
+
+// This file is deprecated, but it should never have been manually included by anything outside of a few select core libraries.
+// Throwing an exception here should be fine because removing the manual inclusion should have no impact.
+// @deprecated Since Moodle 5.1 MDL-82159.
+// The constants NAVIGATION_CACHE_NAME and NAVIGATION_SITE_ADMIN_CACHE_NAME are deprecated and should not be used anymore.
+// They are defined here for autocompletion within IDEs but should not be used outside of \core\navigation anyway.
+throw new \core\exception\coding_exception(
+    'This file should not be manually included by any component.',
+);
+
 /**
- * The name that will be used to separate the navigation cache within SESSION
+ * @deprecated Since Moodle 5.1 MDL-82159.
  */
 define('NAVIGATION_CACHE_NAME', 'navigation');
+
+/**
+ * @deprecated Since Moodle 5.1 MDL-82159.
+ */
 define('NAVIGATION_SITE_ADMIN_CACHE_NAME', 'navigationsiteadmin');

public/lib/setup.php

@@ -624,7 +624,6 @@ require_once($CFG->libdir .'/setuplib.php');        // Functions that MUST be lo
 require_once($CFG->libdir .'/filterlib.php');       // Functions for filtering test as it is output.
 require_once($CFG->libdir .'/weblib.php');          // Functions relating to HTTP and content.
 require_once($CFG->libdir .'/outputlib.php');       // Functions for generating output.
-require_once($CFG->libdir .'/navigationlib.php');   // Class for generating Navigation structure.
 require_once($CFG->libdir .'/dmllib.php');          // Database access.
 require_once($CFG->libdir .'/datalib.php');         // Legacy lib with a big-mix of functions..
 require_once($CFG->libdir .'/accesslib.php');       // Access control functions.

public/lib/tests/coverage.php

@@ -80,7 +80,6 @@ return new class extends phpunit_coverage_info {
         'modinfolib.php',
         'moodlelib.php',
         'myprofilelib.php',
-        'navigationlib.php',
         'oauthlib.php',
         'outputlib.php',
         'pagelib.php',

public/r.php

@@ -35,7 +35,6 @@ require_once("{$CFG->libdir}/setuplib.php");        // Functions that MUST be lo
 require_once("{$CFG->libdir}/filterlib.php");       // Functions for filtering test as it is output.
 require_once("{$CFG->libdir}/weblib.php");          // Functions relating to HTTP and content.
 require_once("{$CFG->libdir}/outputlib.php");       // Functions for generating output.
-require_once("{$CFG->libdir}/navigationlib.php");   // Class for generating Navigation structure.
 require_once("{$CFG->libdir}/dmllib.php");          // Database access.
 require_once("{$CFG->libdir}/datalib.php");         // Legacy lib with a big-mix of functions.
 require_once("{$CFG->libdir}/accesslib.php");       // Access control functions.

public/user/preferences.php

@@ -23,7 +23,6 @@
  */
 
 require_once(__DIR__ . '/../config.php');
-require_once($CFG->libdir . '/navigationlib.php');
 
 require_login(null, false);
 if (isguestuser()) {