From 9f63a03d93119e269bc56c0c1f7f1369243ee648 Mon Sep 17 00:00:00 2001
From: Sara Arjona <sara@moodle.com>
Date: Fri, 9 Aug 2024 17:39:19 +0200
Subject: [PATCH] MDL-82212 core: Add a mechanism to deprecate icons

A new method, get_deprecated_icons(), has been added to the icon_system class.
All deprecated icons should be registered through this method.
When $CFG->debugpageinfo is enabled, a console message will display a list of
the deprecated icons.
---
 .upgradenotes/MDL-82212-2024080916163806.yml  | 11 ++++++++++
 lib/classes/output/icon_system.php            | 22 +++++++++++++++++++
 .../output/icon_system_fontawesome.php        | 16 +++++++++++++-
 lib/pagelib.php                               | 12 ++++++++++
 4 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 .upgradenotes/MDL-82212-2024080916163806.yml

diff --git a/.upgradenotes/MDL-82212-2024080916163806.yml b/.upgradenotes/MDL-82212-2024080916163806.yml
new file mode 100644
index 0000000000000..57d4007f1671d
--- /dev/null
+++ b/.upgradenotes/MDL-82212-2024080916163806.yml
@@ -0,0 +1,11 @@
+issueNumber: MDL-82212
+notes:
+  core:
+    - message: >-
+        A new method, get_deprecated_icons(), has been added to the icon_system
+        class. All deprecated icons should be registered through this method.
+        Plugins can implement a callback to pluginname_get_deprecated_icons() to
+        register their deprecated icons too.
+        When $CFG->debugpageinfo is enabled, a console message will display a
+        list of the deprecated icons.
+      type: improved
diff --git a/lib/classes/output/icon_system.php b/lib/classes/output/icon_system.php
index c9f6b5a1488e8..087e6bbd7c66d 100644
--- a/lib/classes/output/icon_system.php
+++ b/lib/classes/output/icon_system.php
@@ -147,4 +147,26 @@ final public function remap_icon_name($iconname, $component) {
     public static function reset_caches() {
         self::$instance = null;
     }
+
+    /**
+     * Overridable function to get the list of deprecated icons.
+     *
+     * @return array with the deprecated key icons (for instance, core:a/download_all).
+     */
+    public function get_deprecated_icons(): array {
+        $deprecated = [];
+        // Include deprecated icons in plugins too.
+        $callback = 'get_deprecated_icons';
+
+        if ($pluginsfunction = get_plugins_with_function($callback)) {
+            foreach ($pluginsfunction as $plugintype => $plugins) {
+                foreach ($plugins as $pluginfunction) {
+                    $plugindeprecated = $pluginfunction();
+                    $deprecated += $plugindeprecated;
+                }
+            }
+        }
+
+        return $deprecated;
+    }
 }
diff --git a/lib/classes/output/icon_system_fontawesome.php b/lib/classes/output/icon_system_fontawesome.php
index 400102b5929e2..c59787e04c2f9 100644
--- a/lib/classes/output/icon_system_fontawesome.php
+++ b/lib/classes/output/icon_system_fontawesome.php
@@ -488,9 +488,14 @@ public function get_icon_name_map() {
                     }
                 }
 
-                // Add the solid class by default to all icons that have not specific family.
+                $deprecated = $this->get_deprecated_icons();
                 foreach ($this->map as $from => $to) {
+                    // Add the solid class by default to all icons that have not specific family.
                     $this->map[$from] = $this->add_family($to);
+                    // Add the deprecated class to all deprecated icons.
+                    if (in_array($from, $deprecated)) {
+                        $this->map[$from] .= ' deprecated deprecated-'.$from;
+                    }
                 }
 
                 $cache->set($mapkey, $this->map);
@@ -528,6 +533,15 @@ public function render_pix_icon(renderer_base $output, pix_icon $icon) {
 
         if (!$subpix->is_mapped()) {
             $data['unmappedIcon'] = $icon->export_for_template($output);
+            // If the icon is not mapped, we need to check if it is deprecated.
+            $component = $icon->component;
+            if (empty($component) || $component === 'moodle' || $component === 'core') {
+                $component = 'core';
+            }
+            $iconname = $component . ':' . $icon->pix;
+            if (in_array($iconname, $this->get_deprecated_icons())) {
+                $data['unmappedIcon']['extraclasses'] .= ' deprecated deprecated-'.$iconname;
+            }
         }
         if (isset($icon->attributes['aria-hidden'])) {
             $data['aria-hidden'] = $icon->attributes['aria-hidden'];
diff --git a/lib/pagelib.php b/lib/pagelib.php
index 15f81510a1690..5b32c4d13e790 100644
--- a/lib/pagelib.php
+++ b/lib/pagelib.php
@@ -1097,6 +1097,18 @@ public function debug_summary() {
         if ($this->subpage) {
             $summary .= 'Sub-page ' . $this->subpage .  '. ';
         }
+
+        // Display deprecated icons in the console (if any).
+        $summary .= <<< EOF
+            <script type="text/javascript">
+            //<![CDATA[
+            document.querySelectorAll('.icon.deprecated').forEach((icon) => {
+                window.console.warn("Deprecated icon found: " + icon.className);
+            });
+            //]]>
+            </script>
+        EOF;
+
         return $summary;
     }