rest_validate_value_from_schema()
云策文档标注
概述
rest_validate_value_from_schema() 是 WordPress REST API 中用于根据 JSON Schema 验证值的核心函数。它处理多种数据类型、复杂模式（如 anyOf 和 oneOf）以及格式验证，确保输入值符合预期结构。
关键要点
- 函数接受三个参数：$value（待验证值）、$args（模式数组）和 $param（参数名，用于错误消息）。
- 支持内置类型：array、object、string、number、integer、boolean、null，并处理多类型模式。
- 处理 anyOf 和 oneOf 模式，通过 rest_find_any_matching_schema() 和 rest_find_one_matching_schema() 查找匹配模式。
- 验证枚举值（enum）和格式（format），如 hex-color、date-time、email、ip、uuid，确保值符合特定约束。
- 返回 true 表示验证成功，或返回 WP_Error 对象包含错误详情。
- 自 WordPress 4.7.0 引入，后续版本扩展了模式关键字支持，如 5.6.0 添加了 minProperties、maxProperties、multipleOf 等。
代码示例
// 示例：验证一个字符串值是否符合模式
$schema = array(
'type' => 'string',
'format' => 'email'
);
$result = rest_validate_value_from_schema( 'test@example.com', $schema, 'email_param' );
if ( is_wp_error( $result ) ) {
// 处理错误
} else {
// 验证通过
}注意事项
- 模式中必须包含 'type' 关键字，否则会触发 _doing_it_wrong() 警告。
- 格式验证（format）通常仅适用于字符串类型，但为向后兼容，在类型未指定或无效时也允许。
- 函数依赖于多个辅助函数，如 rest_validate_string_value_from_schema() 等，用于具体类型验证。
原文内容
Validate a value based on a schema.
Parameters
$valuemixedrequired-
The value to validate.
$argsarrayrequired-
Schema array to use for validation.
$paramstringrequired-
The parameter name, used in error messages.
Source
function rest_validate_value_from_schema( $value, $args, $param = '' ) {
if ( isset( $args['anyOf'] ) ) {
$matching_schema = rest_find_any_matching_schema( $value, $args, $param );
if ( is_wp_error( $matching_schema ) ) {
return $matching_schema;
}
if ( ! isset( $args['type'] ) && isset( $matching_schema['type'] ) ) {
$args['type'] = $matching_schema['type'];
}
}
if ( isset( $args['oneOf'] ) ) {
$matching_schema = rest_find_one_matching_schema( $value, $args, $param );
if ( is_wp_error( $matching_schema ) ) {
return $matching_schema;
}
if ( ! isset( $args['type'] ) && isset( $matching_schema['type'] ) ) {
$args['type'] = $matching_schema['type'];
}
}
$allowed_types = array( 'array', 'object', 'string', 'number', 'integer', 'boolean', 'null' );
if ( ! isset( $args['type'] ) ) {
/* translators: %s: Parameter. */
_doing_it_wrong( __FUNCTION__, sprintf( __( 'The "type" schema keyword for %s is required.' ), $param ), '5.5.0' );
}
if ( is_array( $args['type'] ) ) {
$best_type = rest_handle_multi_type_schema( $value, $args, $param );
if ( ! $best_type ) {
return new WP_Error(
'rest_invalid_type',
/* translators: 1: Parameter, 2: List of types. */
sprintf( __( '%1$s is not of type %2$s.' ), $param, implode( ',', $args['type'] ) ),
array( 'param' => $param )
);
}
$args['type'] = $best_type;
}
if ( ! in_array( $args['type'], $allowed_types, true ) ) {
_doing_it_wrong(
__FUNCTION__,
/* translators: 1: Parameter, 2: The list of allowed types. */
wp_sprintf( __( 'The "type" schema keyword for %1$s can only be one of the built-in types: %2$l.' ), $param, $allowed_types ),
'5.5.0'
);
}
switch ( $args['type'] ) {
case 'null':
$is_valid = rest_validate_null_value_from_schema( $value, $param );
break;
case 'boolean':
$is_valid = rest_validate_boolean_value_from_schema( $value, $param );
break;
case 'object':
$is_valid = rest_validate_object_value_from_schema( $value, $args, $param );
break;
case 'array':
$is_valid = rest_validate_array_value_from_schema( $value, $args, $param );
break;
case 'number':
$is_valid = rest_validate_number_value_from_schema( $value, $args, $param );
break;
case 'string':
$is_valid = rest_validate_string_value_from_schema( $value, $args, $param );
break;
case 'integer':
$is_valid = rest_validate_integer_value_from_schema( $value, $args, $param );
break;
default:
$is_valid = true;
break;
}
if ( is_wp_error( $is_valid ) ) {
return $is_valid;
}
if ( ! empty( $args['enum'] ) ) {
$enum_contains_value = rest_validate_enum( $value, $args, $param );
if ( is_wp_error( $enum_contains_value ) ) {
return $enum_contains_value;
}
}
/*
* The "format" keyword should only be applied to strings. However, for backward compatibility,
* we allow the "format" keyword if the type keyword was not specified, or was set to an invalid value.
*/
if ( isset( $args['format'] )
&& ( ! isset( $args['type'] ) || 'string' === $args['type'] || ! in_array( $args['type'], $allowed_types, true ) )
) {
switch ( $args['format'] ) {
case 'hex-color':
if ( ! rest_parse_hex_color( $value ) ) {
return new WP_Error( 'rest_invalid_hex_color', __( 'Invalid hex color.' ) );
}
break;
case 'date-time':
if ( false === rest_parse_date( $value ) ) {
return new WP_Error( 'rest_invalid_date', __( 'Invalid date.' ) );
}
break;
case 'email':
if ( ! is_email( $value ) ) {
return new WP_Error( 'rest_invalid_email', __( 'Invalid email address.' ) );
}
break;
case 'ip':
if ( ! rest_is_ip_address( $value ) ) {
/* translators: %s: IP address. */
return new WP_Error( 'rest_invalid_ip', sprintf( __( '%s is not a valid IP address.' ), $param ) );
}
break;
case 'uuid':
if ( ! wp_is_uuid( $value ) ) {
/* translators: %s: The name of a JSON field expecting a valid UUID. */
return new WP_Error( 'rest_invalid_uuid', sprintf( __( '%s is not a valid UUID.' ), $param ) );
}
break;
}
}
return true;
}
Changelog
| Version | Description |
|---|---|
| 5.6.0 | Support the “minProperties” and “maxProperties” keywords for objects. Support the “multipleOf” keyword for numbers and integers. Support the “patternProperties” keyword for objects. Support the “anyOf” and “oneOf” keywords. |
| 5.5.0 | Add the “uuid” and “hex-color” formats. Support the “minLength”, “maxLength” and “pattern” keywords for strings. Support the “minItems”, “maxItems” and “uniqueItems” keywords for arrays. Validate required properties. |
| 5.4.0 | Convert an empty string to an empty object. |
| 5.3.0 | Support multiple types. |
| 5.2.0 | Support validating “additionalProperties” against a schema. |
| 4.9.0 | Support the “object” type. |
| 4.7.0 | Introduced. |