Introduce #alters for \Drupal\Core\Render\Renderer::render()

Updated issue summary.

Updated issue summary.

#2025259: drupal_render() should preserve the original render element in #original so pre and post render functions can access "raw" input could be useful to get in as it would be more useful to a dynamic hook setup than a pre-defined list of callbacks.

I had a bit more of a think. It might be worth introducing #render in this issue too so that we can stop using alters/pre_render to flatten things into #markup (which always feels like a hack to me).

Alters would just be responsible for sanitising and other processing, #render would simply concatenate strings.

I think alters + #render + recursive drupal_render() would be generally preferable to the #pre_render -> drupal_render() recursive -> #markup workflow that we have now, without being too radical a change conceptually.

Patch as a proof-of-concept for pre/post #alters + #render for Drupal render with the intention that these could eventually replace #pre_render and #post_render. Unfortunately, removing the #pre/post callbacks would be a big API break and so wouldn't be feasible for D8 - but we could theoretically add in the new alters I think as their addition doesn't break any backwards compatibility.

So, aside from just saying "hooks are good, callbacks are bad", I wanted to elaborate on a bit of the reasoning behind what's in this patch and what it does:

- #alters is a new standard attribute used by drupal_render(). It is an array of strings that are used to construct the alter hooks that will be called for *both* pre and post processing. This means that for as long as we have both a pre and post render phase, each value in the array will trigger *two* alters, one before the element is rendered into a string and one afterwards. This enforces a consistent API for modules to hook into for each element.

- defining #type for a render element automatically sets an alter with the same name as #type. This gives developers a nice carrot to use #type consistently and correctly in their code and (I believe) is a decent step towards a "render components library" that has been identified as a goal for Drupal elsewere.

- #render is a new standard attribute used by drupal_render(). It can be a string or an array of callbacks that should render the element but not its children - in fact it must assume and respect that children may have been rendered into #children. This works pretty much identically to #theme_wrappers but without the performance overhead and Nth degree of flexibility of the theme system and will therefore need something analagous to the patch over at #2042285: #theme_wrappers should be able to have a unique set of variables per wrapper hook. These callbacks are really intended to render:
-- Elements that are text strings or contain inline markup only
-- Elements that are a single tag with no known use-case to provide templates for
-- Maybe elements with a single tag and a single wrapper tag
There are lots of reasons why this "atomic" markup should be only "alter data, concatenate string" and not full Twig templates, but there are lots of reasons to use Twig templates for anything bigger/more complex.

An example is that something like this:

array(
  '#type' => 'more_link',
);

Could fetch defaults that look like:

array(
  '#alters' => array('link', 'container'),
  '#render' => array('link', 'container'),
  'more' => t('More'),
  ...
  ...
);

To build an extensible, consistent link wrapped in a div with the minimal performance overhead we can achieve using standard Drupal methods (without hacks like pre-rendering #markup).

What all this means is that we can take our existing "atomic" #type elements like #type 'link' and stop using hacks to make them work. Specifically, we could replace this:

- #type 'link' loads a default #pre_render
- The #pre_render both processes the $elements variable to do sanitisation and other "preparation" and then passes it to l() and then saves the return of l() as a string in #markup
- The theme system is skipped, there is no chance for modules to react or do further processing on the link (well, there is, but only because we recently added drupal_alter() to l(), but this isn't anything that drupal_render() is doing for us) without doing things in hook_element_info_alter() - but even this isn't foolproof as it only changes the defaults, an element that sets #pre_render and #type 'link' will not be processed by your module that wants to process link elements.
- The link's markup is *concatenated before* the rendered children of this render element so child elements don't even appear within the link (if you want to put content in your link you need to use the "special" #title attribute)

With this:

- #type 'link' sets up hook_pre_render_link_alter() and has no need for any #pre_render callbacks
- Any module implementing the hook can prepare the variables ready to be rendered
- The theme system is skipped but there is no need for modules to do any further processing as this is a single html tag built from a simple, alterable data structure, the link #render callback is called which simply returns <a> with sanitised/processed attributes and pre-rendered #children *inside* the tag. There is no need for a special #title attribute as we can just use element children as we would for anything else.

#type 'link' could potentially even use the same #render function as #type 'html_tag' with #alters looking like array('link', 'html_tag').

docs do need improving though

- Improved docs here
- Moved the #render into the same logic block as #markup to avoid potential weird behaviour with #render_children
- Cast #alters and #render to an array as we iterate over them to mop up potential issues with anyone providing a string by mistake
- Check that #type is not already one of the values in #alters before adding it so that we don't accidentally call a single alter hook twice

still probably needs:

- some basic tests
- something like #2042285: #theme_wrappers should be able to have a unique set of variables per wrapper hook for #render

Updated issue summary.

Sure, I updated the patch:

- Removed any mention of #pre_render or #post_render being deprecated
- Added test coverage
- Added the ability for #render callbacks to clarify which attributes are "owned" by them

Is this definitely a D9 thing? The patch doesn't break any backwards compatibility for the API.

#13 - yeah, ok. Makes sense. I'll try a re-roll at the #theme_wrappers issue first then port back here.

#15 - Automatically including #type in #alters could be a modest performance hit, I agree. Happy to re-roll without that functionality (although I think it would be great for learnability/usability of the system) and require #alters to be set explicitly in the element or as a default from #type. Also happy to look into setting up some test scenarios for profiling but I think including #alters in a #type definition returned by hook_element_info() would lead to either comparable performance or a performance improvement once some #theme hooks have actually been converted to #render functions (some things on my hit-list would be 'link', 'image', 'html_tag', 'container'). Two reasons for my belief:

1. When we remove a #theme implementation and convert it to #type -> #pre_render -> #markup style rendering we've been inventing new alter hooks in the #pre_render functions to maintain a degree of the flexibility we lose by removing the theme layer. Adding #alters as in #11 simply gives us a formal place to put the alter hooks, they're not intended to be something that we wouldn't be wanting to introduce anyway, see #2030243: Remove theme_file_upload_help() from the theme system for an example of a patch with a new alter that wouldn't be required if it fit into an #alters/#render setup or some other equivalent paradigm. It looks like we're introducing new things with #alters but we're really just moving them somewhere central and giving them a consistent naming convention for every element that would actually utilise them.

2. Using a system that formally accommodates extensible rendering outside the theme system will be a performance improvement for each conversion of #theme to #render that is completed - our profiling when we swapped out theme() for alter() in #1922454: Gut l(), fix theme('link'), have a working framework for consistently generated links inside and outside of Twig showed links being rendered 4-5% faster overall with the alter() implementation for theme functions and something like 10-15% improvement over twig templates. Improving performance for rendering tiny, "atomic" chunks of HTML without resorting to #pre_render -> #markup style hacks is one of the key goals of this issue.

Looking at #2047263: Provide inline_template tag within Twig that inlines a template for usage with a render array, and talking to @Fabianx in IRC, it seems like the #type -> #pre_render -> #markup rendering flow we currently use makes life very difficult for supporting "drillability" in Twig templates, and this issue would be one way to clear that road block.

A suggestion also came up in the discussion that #alters could be expected to build/modify a #variables attribute inside the render element being processed in drupal_render() and this is what is expected to represent the "ready to render" form of the element, whether by #render or Twig. Kind of like the "inverse" of #2025259: drupal_render() should preserve the original render element in #original so pre and post render functions can access "raw" input - instead of taking a snapshot of the element before modifying it directly, making a new "bucket" to throw all our modifications into and not touching the original element at all.

I'll see if I can make a patch incorporating the most recent discussion points in the next few days.

Let's deal with #render over at #2052253: [META] Add #render property to drupal_render() and convert #type "#pre_render -> #markup" calls to use it

Ok.

Here's a patch that doesn't do anything with #render, just #alters. Patch also removed the automatic setting of #alters based on #type.

I removed the profiling tag as when #alters is not set, we only add 2 isset() calls, which is very lightweight.

Updated issue summary.