Improve documentation of hook_theme_suggestions_HOOK_alter()

Anecdotally, and with zero testing right this second, I seem to recall seeing theme suggestions added with hyphens will appear in the twig debug output as well, but will never be used because they were crafted incorrectly. If that's still the case, can we also make that system able to accept hyphenated suggestions or prevent them from appearing in the twig debug output?

MR updates the theme.api.php doc comments, and filters malformed theme suggestions into a new list where themers can see them.

Hey @andy-blum, the code looks good, just added some stuff there but I'm open to discuss. I think it would be nice to add some tests here, I have to dive into this to see if we have any tests to validate the debug info being rendered, so I'm leaving it as NW and the need tests tag.

@murilohp - Thanks for the feedback, I've updated the code with your suggestions. I agree some test coverage would be good, probably as part of TwigDebugMarkupTest.php, though we will likely need to create a test suite module to add in some theme suggestions that will fail.

Hey, I just added a new hook to the theme_test module with an invalid suggestion and updated the test, let's see how it goes.

The code looks okay to me.

This hook allows any module or theme to provide alternative theme function or template name suggestions and reorder or remove suggestions provided by hook_theme_suggestions_HOOK() or by earlier invocations of this hook.

HOOK is the least-specific version of the hook being called. For example, if '#theme' => 'node__article' is called, then node_theme_suggestions_node() will be invoked, not node_theme_suggestions_node__article(). The specific hook called (in this case 'node__article') is available in $variables['theme_hook_original'].

Removing tests tag as I see they were added.

Moving to NW for the failure in MR.

andy-blum → credited safetypin → .

Think this will need a change record.

As existing sites may be using these templates, even though they are invalid

Change record drafted.

Thanks for the quick turnaround on the change record!

Think this is good for next review.

Additional changes look good to me.
There is 1 thread still open. Should this use the D10 link or D9?

Could we craft the link to be whatever version of core is running?

$version = explode('.', \Drupal::VERSION)[0];

$output['debug_info'] .= "\n   See https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Render!theme.api.php/function/hook_theme_suggestions_alter/" . $version;

Would we be able to get the core value in the tests?

The other option is to leave the link as-is without a version, and let it resolve to whatever the latest supported version is

Looking at other examples in core

@link https://api.drupal.org/api/drupal/namespace/Drupal!migrate!Plugin!migrat... List of source plugins provided by the core Migrate module. @endlink

They don't seem to be specifying either so think we can do as #25 mentioned and rely on latest supported version.

Removing credit for @Avanishyadav. Simply opening a MR with no commits does not warrant a contrib credit.

@Avanishyadav, if you're genuinely interested in contributing please be sure to adhere to issue ettiquette, and not just gaming the credit system as it appears you're doing in this issues and the following issues:

• Empty MR: 🐛 Empty #tag in HtmlTag causes <> to be printed at the top of the pages. Needs work
• Creating a duplicate issue: 📌 remove the word "blacklist" from code and documentation Closed: duplicate
• Resubmitting another's solution: [#3342535}
• Empty MR: 📌 jQuery UI Slider - Update Categories Postponed

Thank You @andy-blum for taking a moment to educate @Avanishyadav on issue queue etiquette,

Deleted the bogus MR by Avanishyadav.

Committed 0ac4b76 and pushed to 10.1.x. Thanks!

I don't think this issue needs CR. It is a DX improvement. I don't think anyone. needs to be actively aware of this feature and I don't see that there would be any action for anyone to take as a result of this.

Should we add similar documentation to hook_theme_suggestions_HOOK docs too?

lauriii → closed merge request !3507

Opened a follow-up 📌 Improve documentation of hook_theme_suggestions_HOOK() Fixed .

Automatically closed - issue fixed for 2 weeks with no activity.