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:

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:

  1. Add read-only methods to get child keys and check whether children exist.
  2. Improve test coverage for Core callers ready to be switched to the new methods
  3. 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

Command icon 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

pancho created an issue.