Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Problem/Motivation
Sequences in a config schema are used for many things and they can define if they should be ordered by key or value. Unfortunately, however, most sequences do not specify a sorting order.
For some sequences there is already an order defined in the config entity class which can not easily be translated to order by key or value.
In order to allow more sequences to be sorted the way they are we need to add a more flexible sorting definition.
However, unlike in #3246905: Add optional sorting method for sequences we don't want the flexibility to run arbitrary code and instead keep things declarative.
Proposed resolution
Add a new allowed values to orderby.
The new values have the form of subkey:[somekey] for example subkey:weight
For some sequences however just one property is not enough, so we should allow multiple, and also allow drilling down into sub-sub keys is an option.
Remaining tasks
decide on name
decide on whether or not we want to drill into sub-sub-keys
implement
User interface changes
none
API changes
new allowed values for orderby in sequence config schema.
Data model changes
none
Release notes snippet
Config sequences can be sorted with more fine grained control.
Issue fork drupal-3298348
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:
changes
Comments
Comment #4
wim leersComment #7
mikelutzComment #8
mikelutzThis one seemed like fun.
I preserved BC, so if orderby is null, or === 'key', or === 'value' existing behavior is preserved.
if orderby is a string other than 'key' or 'value' it is treated as a key inside the value. I did not require a prefix 'subkey:' as it seemed unnecessary. If you need to reference a key named 'key' or 'value' it can be done using the advanced syntax that follows. To drill down into deeper items in the sequence arrays, separate keys with a '/' (see tests). This mimics the format we use to access nested array items in the migration system.
if orderby is an array, each item is assumed to be a sort directive, and the sequence is sorted by the first, then the second, and so on. The sequence is finally sorted by the element values (while preserving keys) so as to be deterministic.
Each sort directive can be either a string, which is taken to be an element key as decribed above, or mapping containing at minimum a 'sort_by' key (containing the element key described above) and optionally 'sort_order' and 'sort_flags' keys.
sort_order and sort_flags accept as strings the constant names described here: https://www.php.net/manual/en/function.array-multisort.php sort_flags can either be a string containing a single flag, or a sequence containing multiple flags to OR together.
It would be nice if #2951046: Allow parsing and writing PHP class constants and enums in YAML files were in, and we could avoid parsing the constants as strings altogether. If we don't wait, we should probably add some error checking here to ensure only the expected strings are used.
A dozenish tests are provided to test combinations of sort orders, ensure that string keys are preserved. and to demonstrate capibilities.
A new `UnsupportedSequenceSortConfigException` is provided and thrown if a sequence element does not contain a key that the schema requests that we sort on.
I'm hoping adding in support for various sorting types gets us closer to [#28855675-13] without allowing custom sort functions.
Comment #9
borisson_This looks great. I really like the test coverage provided here. That looks like it covers all possible combinations. I think we should wait for #2951046: Allow parsing and writing PHP class constants and enums in YAML files to get in.
Comment #10
mikelutz