Skip to content

Commit 7542cf4

Browse files
committed
Document using null to reset values
1 parent ab20319 commit 7542cf4

File tree

2 files changed

+15
-2
lines changed

2 files changed

+15
-2
lines changed

extending-the-rest-api/adding-custom-endpoints.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ Arguments are defined as a map in the key `args` for each endpoint (next to your
120120

121121
* `default`: Used as the default value for the argument, if none is supplied.
122122
* `required`: If defined as true, and no value is passed for that argument, an error will be returned. No effect if a default value is set, as the argument will always have a value.
123-
* `validate_callback`: Used to pass a function that will be passed the value of the argument. That function should return true if the value is valid, and false if not.
123+
* `validate_callback`: Used to pass a function that will be passed the value of the argument. That function should return true if the value is valid, and false if not. Note that `null` values bypass validation.
124124
* `sanitize_callback`: Used to pass a function that is used to sanitize the value of the argument before passing it to the main callback.
125125

126126
Using `sanitize_callback` and `validate_callback` allows the main callback to act only to process the request, and prepare data to be returned using the `WP_REST_Response` class. By using these two callbacks, you will be able to safely assume your inputs are valid and safe when processing.

extending-the-rest-api/schema.md

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -362,7 +362,20 @@ Because the WordPress REST API accepts [URL form encoded](https://en.wikipedia.o
362362

363363
When using multiple types, types will be evaluated in the order they are specified. This can have an impact on the sanitized data received by your REST API endpoint. For instance, in the previous example, if the value submitted was `"1"`, it would be sanitized to the boolean `true` value. However, if the order was flipped, the value would remain as the string `"1"`.
364364

365-
[info]The JSON Schema specification allows for defining schemas without a `type` field. The WordPress implementation however requires a `type` to be defined, and will issue a `_doing_it_wrong` notice if a type is ommitted.[/info]
365+
[info]The JSON Schema specification allows for defining schemas without a `type` field. The WordPress implementation however requires a `type` to be defined, and will issue a `_doing_it_wrong` notice if a type is omitted.[/info]
366+
367+
#### Resetting Values
368+
369+
The WordPress REST API uses the value `null` (as in a properly typed `null` sent using JSON) to reset a value to the default for its type. This is accomplished by allowing parameters with a value of `null` to bypass validation. `null` is converted to the following values depending on the type:
370+
371+
- `string` An empty string.
372+
- `number` The value `0.0`.
373+
- `integer` The value `0`.
374+
- `boolean` The value `false`.
375+
- `array` An empty native PHP array.
376+
- `object` An empty native PHP array.
377+
378+
When using multiple types, `null` will not be converted to any value by the sanitization function.
366379

367380
### Format
368381

0 commit comments

Comments
 (0)