View Config: Add version handling

[ntsekouras]

What?

Part of: #76544

This PR adds version handling to the server-side view configuration API (gutenberg_get_entity_view_config()).

Why?

Right now consumers of the filters have to customize the config by walking the raw payload (find the right index, foreach, unset, etc..), and imperative array manipulation can never be migrated. A later shape change could break existing callbacks in the wild. So even though there is only version 1 today and no migrations exist, this code is the safeguard to keep filters working in a possible shape change.

How?

The approach here partially mirrors theme.json version handling, where documents declare a version and WP_Theme_JSON_Data->update_with() migrates older data forward. So instead of mutating a single payload directly, now callbacks receive a data container and update the config through the container's specific methods.

Any update made is marked against the version it was written, and the payload could be migrated in newer versions.

Where it differs from theme.json handling is the need for updating configs that are arrays (e.g. fields and view_list) and handling index based transforms cannot happen reliably in a filter. These props though have stable identities (field.id, view_list.slug), so each part of the config has its own update function and patches are keyed by that identity: the key names the member, the value carries only the changes. All the update functions follow the same rules — an associative array merges key by key, a numerically indexed array replaces wholesale, and null deletes what it names: a nested key, a whole member, or a whole top-level key (which resets it to its default).

update_properties()

• update_properties( $patch, $version ) merges partial changes into default_view, default_layouts, and form except its fields.
• a null patch value unsets a nested key, and null for a whole top-level key resets it to its default.

function example_filter_page_view_config( $data ) {
    // Unset a nested value with null: drop the grid layout option. Form
    // properties other than `fields` also merge here
    $data->update_properties(
        array(
            'default_layouts' => array( 'grid' => null ),
            'form'                   => array( 'layout' => array( 'type' => 'regular' ) ),
        ),
        1
    );

    return $data;
}
add_filter( 'get_entity_view_config_postType_page', 'example_filter_page_view_config' );

update_view_list_items()

• update_view_list_items( $items, $version ) patches the view_list, keyed by slug.
• a matching view merges in place, an unknown slug appends a new view to the end, and null removes the view.

function example_filter_page_view_config( $data ) {
    // Add a saved view, retitle the existing Drafts view — matched by slug,
    // only the given keys change — and remove the Trash view with null.
    $data->update_view_list_items(
        array(
            'my-drafts' => array(
                'title' => __( 'My drafts', 'example' ),
                'view'  => array(
                    'filters' => array(
                        array(
                            'field'    => 'status',
                            'operator' => 'isAny',
                            'value'    => 'draft',
                            'isLocked' => true,
                        ),
                    ),
                ),
            ),
            'drafts'    => array( 'title' => __( 'In progress', 'example' ) ),
            'trash'     => null,
        ),
        1
    );

    return $data;
}
add_filter( 'get_entity_view_config_postType_page', 'example_filter_page_view_config' );

update_form_fields()

• update_form_fields( $fields, $version ) patches the form fields, keyed by id. A field is found wherever it lives — at the top level or nested inside a group's children — so a patch only needs the id.
• a matching field merges in place, an unknown id appends a new field, and null removes the field.
• the id lives in the patch key and the value only carries overrides, so a new field with no overrides is 'my_field' => array(). Inside a field patch, an associative children value merges into the group's children by id (unknown ids append to the group), while a numerically indexed one replaces them wholesale.

function example_filter_page_view_config( $data ) {
    // Change label position to post-content-info field, remove the slug and author
    // fields with null, and append a field to the discussion group.
    $data->update_form_fields(
        array(
            'post-content-info' => array(
                'layout' => array( 'labelPosition' => 'side' ),
            ),
            'slug'                        => null,
            'author'                    => null,
            'discussion'             => array(
                'children' => array( 'my_field' => array() ),
            ),
        ),
        1
    );

    return $data;
}
add_filter( 'get_entity_view_config_postType_page', 'example_filter_page_view_config' );

set()

Replaces a whole top-level key. It shouldn't be the default choice — a callback using it stops inheriting core's future changes to that key — but it's useful for cases like a CPT that doesn't want the default post form at all.

function example_filter_book_view_config( $data ) {
    // The default post form doesn't fit books; define one from scratch.
    return $data->set(
        'form',
        array(
            'layout' => array( 'type' => 'panel' ),
            'fields' => array( 'isbn', 'publisher' ),
        ),
        1
    );
}
add_filter( 'get_entity_view_config_postType_book', 'example_filter_book_view_config' );

Testing Instructions

1. Add the example callback above in PHP.
2. Open Site Editor → Pages:
   • The "My drafts" view appears in the views list; the Drafts view is retitled "In progress"; the Trash view is gone.
   • The Grid layout option is no longer offered.
3. Open Quick Edit on a page: the Slug and Author fields are gone from the form.
4. Play around with different payloads

Use of AI Tools

Opus 4.8 and Fable 5 with direction, changes and review

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: ntsekouras <ntsekouras@git.wordpress.org>
Co-authored-by: mcsf <mcsf@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Mamaduka]

Some surface notes, it's been ages since I've worked on the PHP-side APIs 😅

• Do we want a more general filter that can change multiple configs? Usually filters like get_entity_view_config_{$kind}_{$name} come with something like get_entity_view_config in Core.
• The get_entity_view_config_postType_post doesn't match Core filter naming conventions. Will that be okay?
• The ::update_with method name is okay, but it requires reading the PHPDoc to understand what it really does. Do we have better alternatives?
• Working with private methods can be hard in the future. It's better to have a good plan for how the Gutenberg plugin can patch those when needed.

cc @aaronjorbin, @peterwilsoncc

[github-actions]

Flaky tests detected in e988fad.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/28843166988
📝 Reported issues:

• [Flaky Test] can use appender in site editor sidebar list view #79632 in /test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js

[ntsekouras]

Do we want a more general filter that can change multiple configs? Usually filters like get_entity_view_config_{$kind}_{$name} come with something like get_entity_view_config in Core.

I'm assuming you mean a single filter to update all entities for my reply. TBH I don't think so - at least from the start.. Even current core usages have quite a few differences and I'm not sure how updating something for everything makes sense.

Working with private methods can be hard in the future. It's better to have a good plan for how the Gutenberg plugin can patch those when needed.

I think that this class will stay forever in GB to always override like WP_Theme_JSON_Data_Gutenberg.

[mcsf]

Having gone through the latest changes, in particular the provision of specific removal methods (remove_view_list_items and remove_fields), I must ask:

Would the API be clearer, less surprising and maybe even more maintainable if, instead of a general update_with, we had something like:

• update_view_list_items( array, int )
• update_form_fields( array, int )
• update_properties( array, int ) (or _settings)

[mcsf]

How would one replace all the children, if desired, and without changing the order of discussion among the other top-level fields?

[ntsekouras]

With the new approach you would do children => array( 'author' ).

[mcsf]

This highlights something I mentioned when we talked about this, which is the limitation of not using associative arrays.

If fields looked like:

[
  'excerpt' => [ 'label' => 'Excerpt' ],
[

then consumers of the API would have the flexibility to express either:

$data->update_with( [
  'form' => [
    'fields' => [
      'excerpt' => [ 'label' => null ], // Deletes label
    ],
  ],
], 1 );

$data->update_with( [
  'form' => [
    'fields' => [
      'excerpt' => null, // Deletes field, without the need for `remove`
    ],
  ],
], 1 );

This would also mean less magic in update_with, since it would no longer need special handling for different struct branches (slug within view_list, id within form > fields). It would also mean more consistency with the use case shown in the next test (unsetting default_view and view_list with null).

I understand that the reason for not having associative arrays here is that we're mimicking the internal shape as it currently stands. But since we're introducing a method to manipulate it, mightn't it be worth allowing associative arrays in $patch? Or would that confuse more than help?

[ntsekouras]

That's actually a good idea and I'll update the code. It aligns with your suggestion:

update_view_list_items( array, int )
update_form_fields( array, int )
update_properties( array, int ) (or _settings)

Additionally it would improve updating fields because update_form_fields would make updates based on identity, including nested fields. With the current code, to update a nested field you should also provide the parent, which could have changed in a callback.

Or would that confuse more than help?

I think the main thing that will make things just a tiny bit more confusing is that in order to update form.layout you would have to go through the generic update function, which I believe is not a big deal.

[mcsf]

There's a lot here. :)

I think we're quite close.

That said, to be fully transparent, here are some questions that came to my mind throughout the review process:

• Is there a risk that the shape of the API is too biased towards the internal structure? We've certainly improved things now that patches support keying ('discussion' => null), but who knows.
• Any chance that, with the recent change of the API towards three separate updaters, the versioning itself might no longer be needed? (Probably best to keep it, as it's the whole point of the PR, but still a pertinent question: did the work embedded in this PR help us reduce the uncertainty around future changes to the config structure?)

General observations:

• As hinted in the inline comments, documentation will need a rework before 7.1.
• There's a lot to review. I did my best to scrutinise a lot, but not all of it.
• There may or may not be some code patterns that could be condensed or refactored at some point, but I promise I won't get too distracted by that right now!

[ntsekouras]

Is there a risk that the shape of the API is too biased towards the internal structure?

I think that's unavoidable in order to ensure consumers don't target through indexes, nesting, etc.., which additionally is not even reliable due to possible multiple filters.

Any chance that, with the recent change of the API towards three separate updaters, the versioning itself might no longer be needed? (Probably best to keep it, as it's the whole point of the PR, but still a pertinent question: did the work embedded in this PR help us reduce the uncertainty around future changes to the config structure?)

While the new API reduced the uncertainty for view_list and form fields, it can't help when properties change (e.g. a property is renamed or moves elsewhere). Marking the update with the version is cheap now and future proof, so I'd say we should keep it from the start.

[mcsf]

I'll leave the question of set up to you. Good work!

[oandregal]

👋 I ran into an issue with this API:

• Updating scalar values ✅
• Updating objects (associative arrays) ✅
• Updating lists (numerical indexed arrays) 🔴 It's possible but will break if there's changes to the view config object shape — defeating the purpose of this API.

$data->update_properties( array(
    'default_view' => array(

        // Updating a scalar value (string, int, float, bool) works
        'type' => 'table',

        // Updating an object (associative array) without modifying sibling keys works.
        // This would leave sort.field untouched.
        'sort' => array(
            'direction' => 'desc'
        ),

        // Updating a list (numerical indexed array) will break if there's changes.
        // 
        // Updating a list (such as default_view.fields or default_view.filters) requires
        // accessing the existing values of that key, aka using get_config()[ 'default_view' ][ 'fields' ].
        // But this is problematic. If a consumer (filter callback) does this, it's tied to a specific tree version,
        // but the $data would come in the latest version — hence the risk of breakage.
        'fields' => array_merge(
	    $data->get_config()['default_view']['fields'],
             // I want to add an extra field but need to add the existing fields before
	    array('slug' ) 
        ),
        'filters' => array_merge(
            $data->get_config()['default_view']['filters'],
            // I want to add this new filter, but need to add the existing filters before.
            [
                'field' => 'status',
                'operator' => 'isAny',
                'value'=>['publish']
            ]
        )
) ), 1 );

This is the biggest issue. I think we need to get rid of get_config and provide a declarative way to add, update, and remove any aspect of the tree.

A secondary aspect is the naming and organization:

• we have get_config but also set and update_properties (instead of get, set, update; or get_config, set_config, update_config; etc.)
• update_properties doesn't update every property, there's a handful that have its own methods (view list, form fields)

[ntsekouras]

// Updating a list (such as default_view.fields or default_view.filters) requires
// accessing the existing values of that key, aka using get_config()[ 'default_view' ][ 'fields' ].

There were already so many nuances for trying to solve this problem and yet your example highlights these use cases 😓 .

get_config wrongfully wasn't considered public API and it wasn't documented, but indeed it is and we could mitigate that by making it private. The problem of probably the most common scenario you present about adding some fields in the default view remains.

TBH I'm not sure right now what would be the best path forward and need to think about it more. The 7.1 deadline is here though and we should make a decision really soon.