Problem/Motivation
theme.api.php still documents hook_render_template(), which is obsolete. Its documented body reaches directly into the Twig service:
function hook_render_template($template_file, $variables): string|\Stringable {
$twig_service = \Drupal::service('twig');
return $twig_service->loadTemplate($template_file)->render($variables);
}
This predates #1685492: Convert theme engines into services, which replaced the ENGINE_render_template() hook convention with theme engines as services implementing ThemeEngineInterface::renderTemplate(string $template_file, array $variables): string|MarkupInterface. TwigThemeEngine::renderTemplate() is the real, current implementation. hook_render_template() describes a mechanism core no longer uses and will mislead anyone using it as a reference for writing a new theme engine.
This is a companion cleanup to the issue removing hook_extension() — filed separately since they are two independent, single-function removals, but they should probably be linked once both are open.
Steps to reproduce
- Read
core/lib/Drupal/Core/Render/theme.api.phpon Drupal 11.3.0 or later (verified againstmainat commiteaba66f4, lines 824–849). - Find
hook_render_template(), documented as "Render a template using the theme engine." - Compare with the actual current contract in
core/lib/Drupal/Core/Theme/ThemeEngineInterface.php, which declaresrenderTemplate()as an interface method implemented by a service taggedtheme_engine(seeTwigThemeEngine::renderTemplate()), not a hook.
Proposed resolution
Remove hook_render_template() (theme.api.php, lines 824–849 at eaba66f4) and its docblock entirely, for the same reason as the companion hook_extension() removal. Point readers instead to ThemeEngineInterface for the current contract.
Remaining tasks
- Confirm (grep is sufficient) that no core or contrib code defines an
*_render_template()function relying on the old hook invocation. - Write the patch/MR removing the function and its docblock.
- Review.
User interface changes
None.
Introduced terminology
None.
API changes
Removes the documented, but already non-functional, hook_render_template(). No runtime behavior changes, since nothing in current core invokes this hook.
Data model changes
None.
Release notes snippet
Removed the obsolete hook_render_template(), non-functional documentation left over from the pre-11.3 theme engine file system.
Comments
Comment #2
nicxvan commentedGood find!
Let's take care of this here: #3624887: Remove obsolete hook_extension() and hook_render_template() documentation