Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add detailed descriptions about validate_callback in REST API(adding-custom-endpoints.md) #195

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Update adding-custom-endpoints.md
#194

- Add return value for validate_callback
- Add detailed description for falsy return value.
  • Loading branch information
fumikito authored Nov 28, 2024
commit 4a66ff908cdd6d4a263bc966020f52f26ba5020d
4 changes: 3 additions & 1 deletion extending-the-rest-api/adding-custom-endpoints.md
Original file line number Diff line number Diff line change
@@ -120,7 +120,7 @@ Arguments are defined as a map in the key `args` for each endpoint (next to your

* `default`: Used as the default value for the argument, if none is supplied.
* `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.
* `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.
* `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. Alternatively, a `WP_Error` object can be returned, which will add messages to the params and details properties of the response.
* `sanitize_callback`: Used to pass a function that is used to sanitize the value of the argument before passing it to the main callback.

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.
@@ -146,6 +146,8 @@ add_action( 'rest_api_init', function () {

You could also pass in a function name to `validate_callback`, but passing certain functions like `is_numeric` directly will not only throw a warning about having extra parameters passed to it, but will also return `NULL` causing the callback function to be called with invalid data. We hope to [eventually solve this problem in WordPress core](https://core.trac.wordpress.org/ticket/34659).

Besides that, keep in mind that `validate_callback` recognizes falsy values other than `false`(e.g. `''`, `0`, and `null` ) as valid. Because `WP_REST_Request` class [checks invalid values](https://github.com/WordPress/WordPress/blob/master/wp-includes/rest-api/class-wp-rest-request.php#L911-L923) with strict equality operator `if ( false === $valid_check ) {}`, a function that returns falsy values may result in unintended validation behavior. For example, `return preg_match( '/\d{4}-\d{2}-\d{2}/', $date );` will be always recognized valid, because it returns 1 for a match, 0 for a mismatch, and false for an error.

We could also use something like `'sanitize_callback' => 'absint'` instead, but validation will throw an error, allowing clients to understand what they're doing wrong. Sanitization is useful when you would rather change the data being input rather than throwing an error (such as invalid HTML).