From a69ba70ddc17144d46d3f5dfc37756f7f97396cf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Mudr=C3=A1k?= <david@moodle.com>
Date: Tue, 24 Mar 2015 00:06:03 +0100
Subject: [PATCH] MDL-49643 navigation: Fix API for extending navigation in
 local plugins

---
 lib/navigationlib.php | 31 +++++++++++++++++++++++++------
 local/readme.txt      | 10 ++++++----
 local/upgrade.txt     |  8 ++++++++
 3 files changed, 39 insertions(+), 10 deletions(-)
 create mode 100644 local/upgrade.txt

diff --git a/lib/navigationlib.php b/lib/navigationlib.php
index b87a1b7e1f1..3dafc2b20e2 100644
--- a/lib/navigationlib.php
+++ b/lib/navigationlib.php
@@ -1297,8 +1297,18 @@ class global_navigation extends navigation_node {
         }
 
         // Give the local plugins a chance to include some navigation if they want.
-        foreach (get_plugin_list_with_function('local', 'extends_navigation') as $function) {
-            $function($this);
+        foreach (core_component::get_plugin_list_with_file('local', 'lib.php', true) as $plugin => $unused) {
+            $function = "local_{$plugin}_extend_navigation";
+            $oldfunction = "local_{$plugin}_extends_navigation";
+
+            if (function_exists($function)) {
+                $function($this);
+
+            } else if (function_exists($oldfunction)) {
+                debugging("Deprecated local plugin navigation callback: Please rename '{$oldfunction}' to '{$function}'. ".
+                    "Support for the old callback will be dropped in Moodle 3.1", DEBUG_DEVELOPER);
+                $oldfunction($this);
+            }
         }
 
         // Remove any empty root nodes
@@ -4593,10 +4603,19 @@ class settings_navigation extends navigation_node {
      * This function gives local plugins an opportunity to modify the settings navigation.
      */
     protected function load_local_plugin_settings() {
-        // Get all local plugins with an extend_settings_navigation function in their lib.php file
-        foreach (get_plugin_list_with_function('local', 'extends_settings_navigation') as $function) {
-            // Call each function providing this (the settings navigation) and the current context.
-            $function($this, $this->context);
+
+        foreach (core_component::get_plugin_list_with_file('local', 'lib.php', true) as $plugin => $unused) {
+            $function = "local_{$plugin}_extend_settings_navigation";
+            $oldfunction = "local_{$plugin}_extends_settings_navigation";
+
+            if (function_exists($function)) {
+                $function($this, $this->context);
+
+            } else if (function_exists($oldfunction)) {
+                debugging("Deprecated local plugin navigation callback: Please rename '{$oldfunction}' to '{$function}'. ".
+                    "Support for the old callback will be dropped in Moodle 3.1", DEBUG_DEVELOPER);
+                $oldfunction($this, $this->context);
+            }
         }
     }
 
diff --git a/local/readme.txt b/local/readme.txt
index 563daa6255a..28ad8e5a5d8 100644
--- a/local/readme.txt
+++ b/local/readme.txt
@@ -214,17 +214,19 @@ These two functions both need to be defined within /local/nicehack/lib.php.
 
 sample code
 <?php
-function local_nicehack_extends_navigation(global_navigation $nav) {
+function local_nicehack_extend_navigation(global_navigation $nav) {
     // $nav is the global navigation instance.
     // Here you can add to and manipulate the navigation structure as you like.
     // This callback was introduced in 2.0 as nicehack_extends_navigation(global_navigation $nav)
-    // In 2.3 support was added for the now preferred local_nicehack_extends_navigation(global_navigation $nav).
+    // In 2.3 support was added for local_nicehack_extends_navigation(global_navigation $nav).
+    // In 2.9 the name was corrected to local_nicehack_extend_navigation() for consistency
 }
-function local_nicehack_extends_settings_navigation(settings_navigation $nav, context $context) {
+function local_nicehack_extend_settings_navigation(settings_navigation $nav, context $context) {
     // $nav is the settings navigation instance.
     // $context is the context the settings have been loaded for (settings is context specific)
     // Here you can add to and manipulate the settings structure as you like.
-    // This callback was introduced in 2.3
+    // This callback was introduced in 2.3, originally as local_nicehack_extends_settings_navigation()
+    // In 2.9 the name was corrected to the imperative mood ('extend', not 'extends')
 }
 
 Other local customisation files
diff --git a/local/upgrade.txt b/local/upgrade.txt
new file mode 100644
index 00000000000..2815621077b
--- /dev/null
+++ b/local/upgrade.txt
@@ -0,0 +1,8 @@
+This file describes API changes for the plugins of the type 'local'.
+
+=== 2.9 ===
+
+* Navigation API callbacks local_<plugin>_extends_navigation() and local_<plugin>_extends_settings_navigation() are deprecated.
+  Please rename them to local_<plugin>_extend_navigation() and local_<plugin>_extend_settings_navigation() respectively. The
+  deprecated variant will be supported in 2.9 and 3.0 and then the support will be dropped.
+* Definitely dropped support for the original <plugin>_extends_navigation() that has been deprecated since 2.3.