rest_validate_object_value_from_schema()
云策文档标注
概述
rest_validate_object_value_from_schema() 是一个 WordPress REST API 函数，用于根据 JSON Schema 验证对象值。它检查对象类型、必需属性、属性模式匹配以及属性数量限制，并返回 true 或 WP_Error。
关键要点
- 函数接受三个参数：$value（要验证的值）、$args（模式数组）和 $param（参数名，用于错误消息）。
- 首先验证 $value 是否为对象类型，否则返回 WP_Error。
- 支持模式版本 3 和 4 的必需属性检查，通过 'required' 或 'properties' 数组实现。
- 遍历对象属性，使用 rest_validate_value_from_schema() 验证每个属性是否符合模式定义。
- 处理 patternProperties 和 additionalProperties 模式关键字，以允许或禁止额外属性。
- 检查 minProperties 和 maxProperties 以限制属性数量，违反时返回错误。
- 函数返回 true 表示验证成功，否则返回 WP_Error 包含具体错误信息。
代码示例
function rest_validate_object_value_from_schema( $value, $args, $param ) {
if ( ! rest_is_object( $value ) ) {
return new WP_Error(
'rest_invalid_type',
sprintf( __( '%1$s is not of type %2$s.' ), $param, 'object' ),
array( 'param' => $param )
);
}
// 更多验证逻辑...
}注意事项
- 此函数是 WordPress 5.7.0 版本引入的，用于增强 REST API 的数据验证能力。
- 依赖于其他函数如 rest_is_object()、rest_sanitize_object() 和 rest_validate_value_from_schema()，确保在调用前这些函数可用。
- 错误消息支持国际化，使用 __() 和 _n() 函数进行翻译。
- 模式数组 $args 应遵循 JSON Schema 结构，包括 properties、required、additionalProperties 等键。
原文内容
Validates an object 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_object_value_from_schema( $value, $args, $param ) {
if ( ! rest_is_object( $value ) ) {
return new WP_Error(
'rest_invalid_type',
/* translators: 1: Parameter, 2: Type name. */
sprintf( __( '%1$s is not of type %2$s.' ), $param, 'object' ),
array( 'param' => $param )
);
}
$value = rest_sanitize_object( $value );
if ( isset( $args['required'] ) && is_array( $args['required'] ) ) { // schema version 4
foreach ( $args['required'] as $name ) {
if ( ! array_key_exists( $name, $value ) ) {
return new WP_Error(
'rest_property_required',
/* translators: 1: Property of an object, 2: Parameter. */
sprintf( __( '%1$s is a required property of %2$s.' ), $name, $param )
);
}
}
} elseif ( isset( $args['properties'] ) ) { // schema version 3
foreach ( $args['properties'] as $name => $property ) {
if ( isset( $property['required'] ) && true === $property['required'] && ! array_key_exists( $name, $value ) ) {
return new WP_Error(
'rest_property_required',
/* translators: 1: Property of an object, 2: Parameter. */
sprintf( __( '%1$s is a required property of %2$s.' ), $name, $param )
);
}
}
}
foreach ( $value as $property => $v ) {
if ( isset( $args['properties'][ $property ] ) ) {
$is_valid = rest_validate_value_from_schema( $v, $args['properties'][ $property ], $param . '[' . $property . ']' );
if ( is_wp_error( $is_valid ) ) {
return $is_valid;
}
continue;
}
$pattern_property_schema = rest_find_matching_pattern_property_schema( $property, $args );
if ( null !== $pattern_property_schema ) {
$is_valid = rest_validate_value_from_schema( $v, $pattern_property_schema, $param . '[' . $property . ']' );
if ( is_wp_error( $is_valid ) ) {
return $is_valid;
}
continue;
}
if ( isset( $args['additionalProperties'] ) ) {
if ( false === $args['additionalProperties'] ) {
return new WP_Error(
'rest_additional_properties_forbidden',
/* translators: %s: Property of an object. */
sprintf( __( '%1$s is not a valid property of Object.' ), $property )
);
}
if ( is_array( $args['additionalProperties'] ) ) {
$is_valid = rest_validate_value_from_schema( $v, $args['additionalProperties'], $param . '[' . $property . ']' );
if ( is_wp_error( $is_valid ) ) {
return $is_valid;
}
}
}
}
if ( isset( $args['minProperties'] ) && count( $value ) < $args['minProperties'] ) {
return new WP_Error(
'rest_too_few_properties',
sprintf(
/* translators: 1: Parameter, 2: Number. */
_n(
'%1$s must contain at least %2$s property.',
'%1$s must contain at least %2$s properties.',
$args['minProperties']
),
$param,
number_format_i18n( $args['minProperties'] )
)
);
}
if ( isset( $args['maxProperties'] ) && count( $value ) > $args['maxProperties'] ) {
return new WP_Error(
'rest_too_many_properties',
sprintf(
/* translators: 1: Parameter, 2: Number. */
_n(
'%1$s must contain at most %2$s property.',
'%1$s must contain at most %2$s properties.',
$args['maxProperties']
),
$param,
number_format_i18n( $args['maxProperties'] )
)
);
}
return true;
}
Changelog
| Version | Description |
|---|---|
| 5.7.0 | Introduced. |