Twig debug output does not display all suggestions when an array of theme hooks is passed to #theme

Closes #2118743

core/lib/Drupal/Core/Theme/ThemeManager.php

@@ -143,7 +143,10 @@ public function render($hook, array $variables) {
 
     // If an array of hook candidates were passed, use the first one that has an
     // implementation.
+    $template_suggestions = [$hook];
     if (is_array($hook)) {
+      // Ensure $template_suggestions has continuous numeric keys.
+      $template_suggestions = array_values($hook);
       foreach ($hook as $candidate) {
         if ($theme_registry->has($candidate)) {
           break;
@@ -184,6 +187,19 @@ public function render($hook, array $variables) {
 
     $info = $theme_registry->get($hook);
 
+    // We've found a template implementation, but we need to let the template
+    // engine know about all possible suggestions (for discoverability). The
+    // code above only iteratively strips '__' parts from $hook if the hook was
+    // not found in the theme registry. If the #theme was an array, that also
+    // means $hook was the last element in that array. So we know it is safe to
+    // always grab the last suggestion from that array in order to find all
+    // possible template suggestions from the #theme value.
+    $hook_name = $template_suggestions[array_key_last($template_suggestions)];
+    while ($pos = strrpos($hook_name, '__')) {
+      $hook_name = substr($hook_name, 0, $pos);
+      $template_suggestions[] = $hook_name;
+    }
+
     // If a renderable array is passed as $variables, then set $variables to
     // the arguments expected by the theme function.
     if (isset($variables['#theme']) || isset($variables['#theme_wrappers'])) {
@@ -244,13 +260,51 @@ public function render($hook, array $variables) {
     $this->moduleHandler->alter($hooks, $suggestions, $variables, $base_theme_hook);
     $this->alter($hooks, $suggestions, $variables, $base_theme_hook);
 
+    // Merge these new suggestions into our previous list of all possible
+    // template suggestions.
+    $reversed_suggestions = array_reverse($suggestions);
+    $hook_position = array_search($hook, $reversed_suggestions);
+    if ($hook_position === FALSE) {
+      $hook_position = count($reversed_suggestions);
+    }
+    // Get the suggestions before and after the chosen $hook.
+    $most_specific_suggestions = array_slice($reversed_suggestions, 0, $hook_position);
+    $least_specific_suggestions = array_slice($reversed_suggestions, $hook_position + 1);
+
+    // Scan through the template suggestions from the end to the beginning to
+    // find the first and last occurrence of the base hook.
+    $base_hook_key = FALSE;
+    foreach (array_reverse($template_suggestions, TRUE) as $key => $hook_name) {
+      // Find the base hook for this hook suggestion.
+      $base_hook_name = $hook_name;
+      if ($pos = strpos($base_hook_name, '__')) {
+        $base_hook_name = substr($base_hook_name, 0, $pos);
+      }
+      if ($base_hook_name === $base_theme_hook) {
+        if ($base_hook_key === FALSE) {
+          // Insert the least specific suggestions just before the last
+          // occurrence of the base hook.
+          $prevent_duplicate = in_array($hook_name, $least_specific_suggestions)
+            ? 1
+            : 0;
+          array_splice($template_suggestions, $key, $prevent_duplicate, $least_specific_suggestions);
+        }
+        $base_hook_key = $key;
+      }
+    }
+    // Insert the most specific suggestions just before the first occurrence of
+    // the base hook.
+    array_splice($template_suggestions, $base_hook_key, 0, $most_specific_suggestions);
+
     // Check if each suggestion exists in the theme registry, and if so,
     // use it instead of the base hook. For example, a function may use
     // '#theme' => 'node', but a module can add 'node__article' as a suggestion
     // via hook_theme_suggestions_HOOK_alter(), enabling a theme to have
     // an alternate template file for article nodes.
+    $template_suggestion = $hook;
     foreach (array_reverse($suggestions) as $suggestion) {
       if ($theme_registry->has($suggestion)) {
+        $template_suggestion = $suggestion;
         $info = $theme_registry->get($suggestion);
         break;
       }
@@ -354,7 +408,11 @@ public function render($hook, array $variables) {
       if (!isset($default_attributes)) {
         $default_attributes = new Attribute();
       }
-      foreach (['attributes', 'title_attributes', 'content_attributes'] as $key) {
+      foreach ([
+        'attributes',
+        'title_attributes',
+        'content_attributes',
+      ] as $key) {
         if (isset($variables[$key]) && !($variables[$key] instanceof Attribute)) {
           if ($variables[$key]) {
             $variables[$key] = new Attribute($variables[$key]);
@@ -381,6 +439,10 @@ public function render($hook, array $variables) {
       if (isset($theme_hook_suggestion)) {
         $variables['theme_hook_suggestion'] = $theme_hook_suggestion;
       }
+      // Add two read-only variables that help the template engine understand
+      // how the template was chosen from among all suggestions.
+      $variables['template_suggestions'] = $template_suggestions;
+      $variables['template_suggestion'] = $template_suggestion;
       $output = $render_function($template_file, $variables);
     }
 
@@ -394,8 +456,9 @@ public function render($hook, array $variables) {
    *   The current route match.
    */
   protected function initTheme(RouteMatchInterface $route_match = NULL) {
-    // Determine the active theme for the theme negotiator service. This includes
-    // the default theme as well as really specific ones like the ajax base theme.
+    // Determine the active theme for the theme negotiator service. This
+    // includes the default theme as well as really specific ones like the ajax
+    // base theme.
     if (!$route_match) {
       $route_match = \Drupal::routeMatch();
     }
@@ -420,8 +483,8 @@ public function alterForTheme(ActiveTheme $theme, $type, &$data, &$context1 = NU
       $extra_types = $type;
       $type = array_shift($extra_types);
       // Allow if statements in this function to use the faster isset() rather
-      // than !empty() both when $type is passed as a string, or as an array with
-      // one item.
+      // than !empty() both when $type is passed as a string, or as an array
+      // with one item.
       if (empty($extra_types)) {
         unset($extra_types);
       }