Pass WP_REST_Request object to registered callback for a route schema.

[nerrad]

The documentation here (​https://developer.wordpress.org/rest-api/schema/#resource-schema) indicates that an instance of WP_REST_Request is passed along to the registered callback for schema.

However, as found in \WP_REST_Server::get_data_for_route it is clear that the callback recieves nothing:

if ( isset( $this->route_options[ $route ] ) ) {
    $options = $this->route_options[ $route ];

    if ( isset( $options['namespace'] ) ) {
        $data['namespace'] = $options['namespace'];
    }

    if ( isset( $options['schema'] ) && 'help' === $context ) {
        $data['schema'] = call_user_func( $options['schema'] );
    }
}

It's very clear the documentation is in error, and I realize that the request instance isn't even really exposed where the callback is invoked. For the purpose of dynamic schema generation when there is a single schema callback used, it would be useful if we exposed the $route to the callback.

If I did a patch for this is it something that would be considered?

[jnylen0]

Replying to nerrad:

If I did a patch for this is it something that would be considered?

+1 from me, it's a harmless and potentially useful change that probably somebody intended to make at some point.

[nerrad]

Pass $route to the registered schema callback. Also adds tests for this.

[rachelbaker]

@nerrad I am curious, can you explain your use case?

[nerrad]

Hi @rachelbaker, sure! It might help if I link to the slack convo where I conversed a bit with James about this. ​https://wordpress.slack.com/archives/core-restapi/p1482439854001512 and ​https://wordpress.slack.com/archives/core-restapi/p1482439900001514

If you would like more detail than that I can try to provide.

Also, I should emphasize, regardless of what happens with this ticket, the REST API documentation I linked to in the original post here does need fixed. It's incorrect and is primarily why I started out this ticket as a bug (but totally am fine with the change to enhancement). Specifically in the documentation is this function:

function prefix_get_comment_schema( $request ) { ... }

Which is not correct because the callback registered on schema currently receives nothing for its argument (unless I'm reading the related code wrong :) )

[jnylen0]

After giving this some more thought I'd rather fix this issue by revising the documentation rather than adding another parameter in the code. The schema callback shouldn't care what the route is or about the details of the request, because the schema is the description of a single item regardless of what you are doing to that item.

More generally, I would also recommend one register_rest_route call per endpoint, preferring explicit code over implicit dynamic registration. This makes it easier to follow what endpoints are registered, and where and how. This isn't always possible though - @nerrad and I chatted some in DMs where he shared his code that led to this request:

• ​`rest_api_init` callback
• ​`register_rest_route` call
• ​`schema_callback` argument
• ​schema callback code
• ​current code to determine the request route

As an alternative solution, I suggested something like schema_callback => create_schema_callback( 'some_model_type' ) which seems like a better level of abstraction than relying on the REST route.

I've fixed the incorrect documentation linked in the original report, so we can close this ticket.