Add multiple orderby support to REST Posts Controller

[gwwar]

Fixes https://core.trac.wordpress.org/ticket/39037 This PR adds multiple orderby support to the REST posts controller.

As an experiment, I also added a secondary ID sort to stabilize the order. This would help address pagination issues, without forcing the caller to set a second sort. Another way of fixing that would be doing so in WP_Query versus the REST posts controller, but that change would have a much larger surface area. Reading through other issues, I think folks were preferring this be done at the WP_Query level.

Related: https://core.trac.wordpress.org/ticket/46294 https://core.trac.wordpress.org/ticket/44349

Problem

We can currently only sort by a single dimension using the REST API. In some cases, we need a second sort to help provide a stable order. For example imagine if we sort by menu_order, if other items don't have this value set, what order should they be sorted by? id? title?

What happens currently is that internal implementation details affect this ordering, sometimes in surprising ways. One example is simply changing a limit from 499 to 500 when using menu_order. This is because at a limit of <500, WP_Query internally splits a post query into two queries: issue, changeset.

Proposed changes here allow us to sort with multiple orderby values, to provide more consistent ordering in results.

TODO

• Audit affected filters
• Smoke test other affected rest endpoints

Testing Instructions

• Verify that tests pass and make sense
• Manually test with a few requests in the following format:

/wp/v2/pages?per_page=100&orderby=menu_order&order=asc

/wp/v2/pages?per_page=100&orderby=menu_order,title&order=asc

/wp/v2/pages?per_page=100&orderby[]=menu_order&orderby[]=title&order=asc

/wp/v2/pages?per_page=100&orderby[menu_order]=asc&orderby[title]=desc

If folks don't have an rest client handy, we can open the console when visiting the post editor:

wp.apiFetch( { path: '/wp/v2/pages?per_page=100&orderby[menu_order]=asc&orderby[title]=desc' } ).then( ( data ) => { 
    console.log( data );
} );

[gwwar]

Highlighting that we still need to 🤔 audit existing filters

[gwwar]

For the rest_query_var-orderby filter I do think it's clearest to simply pass through value, which might be a string or array.

If we'd really like to preserve backwards compatibility, we could do something like pass through the first argument as a string (maybe the first value or some comma or space delimited string), and have the second argument be the original value. I feel like it'd avoid potential errors on upgrade, but would be confusing for future usage.

[gwwar]

Taking another look, it looks like the default implementation returns $value so passing through a string as a first arg won't work.

[gwwar]

@mdawaffe was kind enough to propose a patch, which I added in 073fffc along with some basic tests.

[gwwar]

Reading through https://core.trac.wordpress.org/ticket/47642#comment:13 it looks like folks do prefer this at the WP_Query level. I’ll back out the other commits from this PR

[gwwar]

I circled back to this one and it's ready for another look 👀 In terms of feedback I have two main areas that would be helpful:

Affected Filters

There are two filters that now have breaking changes. What do folks think might be the best way to resolve this?

• rest_query_var-orderby https://developer.wordpress.org/reference/hooks/rest_query_var-key/ Breaking Change $value used to be string, but can now be array or object)
• https://developer.wordpress.org/reference/hooks/rest_this-post_type_query/ Breaking Change $value['orderby] used to be string, but can now be array or object)
• https://developer.wordpress.org/reference/hooks/rest_this-post_type_collection_params/ (updated orderby schema, change looks okay).

Any missing test coverage?

Are there any areas that I should add tests / verify changes for?

cc @TimothyBJacobs @mdawaffe or whomever may be interested

[gwwar]

I think test failures here mean that fixtures need to be regenerated for tests/qunit/fixtures/wp-api-generated.js Do folks know what command should be run here?

[TimothyBJacobs]

I think test failures here mean that fixtures need to be regenerated for tests/qunit/fixtures/wp-api-generated.js Do folks know what command should be run here?

Running the rest api phpunit test suite should regenerate those files. --group restapi