Problem/Motivation
Element::children() is one of our more notorious problem children in the rendering system, nomen est omen...
While it returns child keys, it also tends to reorder the original array passed by reference and set #sorted. Even a call that intentionally omits the sort argument may end up reordering the elemnet's children, when the array given has #sorted set to FALSE. Setting #sorted too early can prevent the renderer from picking up later weight changes. Reordering removes the entries and reinserts their values, which can break existing PHP references. A total nightmare.
Core already works around these side effects, wherever they're unintended. Form validation creates a copy of the array to make sure Element::children() doesn't mess with the original array. Views UI and Navigation also sort local arrays to choose the default display or build the page actions, even though they only need to iterate over the keys in weight order.
Background
Render arrays collect child elements, rendering instructions, and state such as #sorted in the same array. This makes it hard to tell what inspecting an array will reveal or change. For example, a region can contain blocks and still have no visible content.
This and other problems asked for an overhaul of the Render API, the last attempts being:
- #953034: [meta] Themes improperly check renderable arrays when determining visibility
- #2702061: Unify & simplify render & theme system: component-based rendering (enables pattern library, style guides, interface previews, client-side re-rendering)
- #3533198: [Meta] Make Drupal the first "design-system native" CMS + Unify & simplify render & theme systems
This work on the Render and Theme systems is likely to take some years or may be restarted again and take even longer. In the meantime we need to improve on what we have.
Proposed resolution
Callers should be able to get child keys in weight order or check whether children exist without modifying the render array. We therefore should:
- Add read-only methods to get child keys and check whether children exist.
- Improve test coverage for Core callers ready to be switched to the new methods
- Switch those Core callers to the new methods without changing their behavior.
Remaining tasks
Review.
Further work on stable sorting can continue in #2522712: Simplify Element::children() stable sort., with other callers addressed in follow-up issues.
User interface changes
None.
Introduced terminology
None.
API changes
- The new method
Element::getChildKeys()returns the child keys and can order them by weight. - The new method
Element::hasAnyChildren()checks whether the render array contains a child.
Preexisting methods such as Element::children() and Element::getVisibleChildren() remain unchanged for now.
Data model changes
None.
Release notes snippet
Drupal core adds two methods to check a render array for children and get their keys without modifying the array. Element::getChildKeys() returns the child keys, optionally sorted by weight, and Element::hasAnyChildren() checks whether any children exist.
Issue fork drupal-3638760
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments