Support for objects in schema validation and sanitization

[rachelbaker]

Follow-up on #38531 and support sanitizing and validating objects with our schema. This would allow our Meta and Settings endpoints to accept non-scalar values.
See ​https://github.com/WP-API/WP-API/issues/2859

I've taken a stab at implementing support for object validation in ​https://github.com/xwp/wp-js-widgets/blob/062c571f5ea77c5c0e3a069b6db3f40f763c97e8/php/class-js-widgets-rest-controller.php#L300-L365

Looking forward to seeing this in a release. So this is waiting for sanitization support, currently?

I've added two separate versions.

1) Simply adds object validation. For the properties like content or title which can accept either a structured object or a string, the validation_callback is set to null ( matching sanitization ).

2) Adds object validation and adds support for multiple type options. So content for instance becomes type => [ 'object', 'string'].

Bumping priority to high for visibility and alignment with 4.9 goals, and given proximity to beta 1 deadline.

@joehoyle I think you'd be in the best position to review this, do you have bandwidth to do that today so we can consider this for 4.9?

38583.1.diff is looking good to me, I don't think it would be right to go with 38583.2.diff at this point. It could be considered after adding basic object support, but the two should be separate. Thanks for all the work on it though, that's a big patch!

For 38583.1.diff this looks mostly good. I think we shouldn't support additionalProperties for now, the point of the schema is to whitelist data and types into the REST API (and out), so I'm not sure I see a long term path for it; but again, let's get basic object support before putting a nail in that coffin.

I can clean up 38583.1.diff to remove those, test etc.

We also ideally need to look at register_meta / register_setting to make sure they also handle the extra types, else this is only useful to register_rest_field and custom controllers / endpoints.

Added new patch working off 38583.1.diff:

• Removed support for additionalProperties
• Fixed sanitize -> validate in comments
• Will now remove / ignore any properties that are not included in the registered properties. We follow this pattern mostly around the API where over-providing data is just silently ignored.

Add support for stdClass

In 41727:

REST API: Support for objects in schema validation and sanitization.

When registering routes developers can now define their complex objects in the schema and benefit from the automatic validation and sanitization in the REST API. This also paves the way for support for complex object registration via register_meta and register_setting.

See #38583.
Props TimothyBlynJacobs5.

I'm going to keep this ticket up and do a follow-up patch to add support for register_meta and register_setting.

Added a patch for enabling use of objects in register_setting. This is essentially whitelisting the added type in the settings controller, and also now passes properties from the arg registration into the validation functions.

In 41758:

REST API: Support objects in settings schema.

Enables register_setting to accept an object as its schema value, allowing settings to accept non-scalar values through the REST API.
This whitelists the added type in the settings controller, and passes properties from argument registration into the validation functions.

Props joehoyle.
See #38583.

Leaving this open in case we want to continue to use this ticket for register_meta, but defer to @joehoyle on whether that should at this point be broken out.

Let's resolve this as fixed and open a new task/defect for any necessary change for register_meta().

This is a nice feature we will definetely use in our plugin!
Unfortunately, the only reason I learned about it was because it broke our plugin's unit tests! :)

Our custom REST API endpoints accept a query parameterof type "object" which has a pretty complex structure, so we were performing our validation on it later in the request. However, this change now has validation kicking in early and wiping the object right away. So, our previous valid query params are now being marked as invalid.

eg, this is the info in the WP REST API index page about the endpoint

"/ee/v4.8.36/datetimes": {
            "namespace": "ee/v4.8.36",
            "methods": [
                "GET",
                "POST"
            ],
            "endpoints": [
                {
                    "methods": [
                        "GET"
                    ],
                    "args": {
                        "where": {
                            "required": false,
                            "default": [],
                            "type": "object"
                        },
...

A request like mysite.com/wp-json/ee/v4.8.36/datetimes?where[DTT_EVT_start]=2017-01-01T00:00:00 used to only show the datetimes where their DTT_EVT_start property matched January 1st 2017, but this new validation removes that condition because it only considers an empty object to be a valid value for the where arg.

I'm not sure if other plugin developers or users with custom endpoints will experience the same issue.

I'd suggest: if $args['properties'] is empty inside rest_sanitize_value_from_schema, that no validation should occur (for backward compatibility, that was the previous behaviour), instead of only considering an empty object valid (current behaviour).

ie, inside rest_sanitize_value_from_schema, replace the code that deals with args of type object with this

if ( 'object' === $args['type'] ) {
                if ($value instanceof stdClass) {
                        $value = (array)$value;
                }
                if (! is_array($value)) {
                        return array();
                }
                if (isset($args['properties'])) {// <--- new
                        foreach ($value as $property => $v) {
                                if (! isset($args['properties'][$property])) {
                                        unset($value[$property]);
                                        continue;
                                }
                                $value[$property] = rest_sanitize_value_from_schema($v, $args['properties'][$property]);
                        }
                }// <---- new