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

@@ -141,9 +141,17 @@ public function render($hook, array $variables) {
 
     $theme_registry = $this->themeRegistry->getRuntime();
 
+    // While we search for templates, we create a list of template suggestions
+    // to use for Twig debug comments. Note: this list is entirely separate from
+    // the list of $suggestions created later that is passed to
+    // theme_suggestions alter hooks.
+    $template_suggestions = [$hook];
+
     // If an array of hook candidates were passed, use the first one that has an
     // implementation.
     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 +192,16 @@ public function render($hook, array $variables) {
 
     $info = $theme_registry->get($hook);
 
+    // If $hook is an array of strings, the code above only expands the final
+    // element in the array. We need to let the template engine know about all
+    // possible $template_suggestions (for discoverability), so we grab the last
+    // element and expand it.
+    $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'])) {
@@ -228,11 +246,17 @@ public function render($hook, array $variables) {
 
     // Invoke hook_theme_suggestions_HOOK().
     $suggestions = $this->moduleHandler->invokeAll('theme_suggestions_' . $base_theme_hook, [$variables]);
+    // Make a copy of the initial suggestions for later.
+    $suggestions_copy = $suggestions;
     // If the theme implementation was invoked with a direct theme suggestion
     // like '#theme' => 'node__article', add it to the suggestions array before
     // invoking suggestion alter hooks.
     if (isset($info['base hook'])) {
       $suggestions[] = $hook;
+      $suggestions_include_specific_hook = TRUE;
+    }
+    else {
+      $suggestions_include_specific_hook = FALSE;
     }
 
     // Invoke hook_theme_suggestions_alter() and
@@ -244,13 +268,105 @@ public function render($hook, array $variables) {
     $this->moduleHandler->alter($hooks, $suggestions, $variables, $base_theme_hook);
     $this->alter($hooks, $suggestions, $variables, $base_theme_hook);
 
+    // In order to properly merge these new suggestions into our previous list
+    // of all possible template suggestions, we need to determine where each
+    // suggestion comes from and order them like so:
+    //
+    // 1. More-specific suggestions from the #theme list that aren't for the
+    //    $base_theme_hook.
+    // 2. Suggestions for $base_theme_hook from:
+    //    a. hook_theme_suggestions_alter(), hook_theme_suggestions_HOOK_alter()
+    //    b. #theme list
+    //    c. hook_theme_suggestions_HOOK()
+    //    d. $base_theme_hook
+    // 3. Less-specific suggestions from the #theme array that aren't for the
+    //    $base_theme_hook.
+    //
+    // Since 2a and 2c come from $suggestions, we need to figure out how to
+    // split that array into two parts.
+    if ($suggestions_include_specific_hook) {
+      $separator_hook = $hook;
+      // Ensure numeric keys are continuous to make slicing the array easier.
+      $reindexed_suggestions = array_values($suggestions);
+    }
+    else {
+      // Since the $hook is not included in $suggestions, the only guaranteed
+      // way to split the list is to re-run the alter hooks with a dummy
+      // separator inserted into the suggestions list.
+      $separator_hook = $base_theme_hook . '__do.not.remove__hook.separator';
+      $suggestions_copy[] = $separator_hook;
+      $this->moduleHandler->alter($hooks, $suggestions_copy, $variables, $base_theme_hook);
+      $this->alter($hooks, $suggestions_copy, $variables, $base_theme_hook);
+      $reindexed_suggestions = array_values($suggestions_copy);
+    }
+    // Find the separator in the suggestions list.
+    $split_position = array_search($separator_hook, $reindexed_suggestions);
+
+    // Split the suggestions into the two needed lists (see above).
+    $least_specific_suggestions = array_slice(
+      $reindexed_suggestions,
+      0,
+      ($split_position === FALSE) ? 0 : $split_position
+    );
+    $most_specific_suggestions = array_slice(
+      $reindexed_suggestions,
+      // If the separator was not found, then we assume any #theme array
+      // suggestions inserted into $suggestions would also be removed. So, all
+      // suggestions are more specific than the #theme array suggestions.
+      ($split_position === FALSE) ? 0 : $split_position + 1
+    );
+
+    // The $hook's theme registry may specify a "base hook" that differs from
+    // the base string of $hook. If so, we need to search $template_suggestions
+    // for both of these base hook strings.
+    $base_of_hook = explode('__', $hook)[0];
+
+    // Scan through the template suggestions from the end to the beginning to
+    // find the first and last occurrence of the base hook.
+    $first_base_hook_key = FALSE;
+    foreach (array_reverse($template_suggestions, TRUE) as $key => $suggestion) {
+      // Find the base hook for this hook suggestion.
+      $suggestion_base = explode('__', $suggestion)[0];
+      if ($suggestion_base === $base_of_hook || $suggestion_base === $base_theme_hook) {
+        if ($first_base_hook_key === FALSE) {
+          // Since we are searching from the end of $template_suggestions, we
+          // have just now found the last occurrence of the base hook. Insert
+          // the least specific suggestions just before this last occurrence of
+          // the base hook, assuming it is the base theme hook. However, under
+          // some edge cases, the last occurrence of the base hook will be a
+          // specific suggestion and won't be the actual base hook, so we need
+          // to insert the suggestions after this last occurrence.
+          $insertion_point = $suggestion === $base_theme_hook ? $key : $key + 1;
+          $prevent_duplicate = in_array($suggestion, $least_specific_suggestions) ? 1 : 0;
+          array_splice(
+            $template_suggestions,
+            $insertion_point,
+            $prevent_duplicate,
+            array_reverse($least_specific_suggestions)
+          );
+        }
+        // Keep searching for the first occurrence of the base hook.
+        $first_base_hook_key = $key;
+      }
+    }
+    // Insert the most specific suggestions just before the first occurrence of
+    // the base hook.
+    array_splice(
+      $template_suggestions,
+      $first_base_hook_key,
+      0,
+      array_reverse($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 +470,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 +501,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 +518,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 +545,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);
       }