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-78334-2024080916163806.yml

@@ -0,0 +1,11 @@
+issueNumber: MDL-78334
+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

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;
+    }
 }

lib/classes/output/icon_system_fontawesome.php

@@ -487,9 +487,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);
@@ -527,6 +532,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'];

lib/pagelib.php

@@ -1104,6 +1104,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;
     }