rest_validate_number_value_from_schema()
云策文档标注
概述
rest_validate_number_value_from_schema() 是一个 WordPress REST API 函数,用于根据提供的 schema 验证数值参数。它检查值是否为数字,并验证倍数、最小值和最大值等约束条件。
关键要点
- 函数接受三个参数:$value(要验证的值)、$args(schema 数组)和 $param(参数名,用于错误消息)。
- 返回 true 表示验证成功,或返回 WP_Error 对象表示验证失败,包含错误代码和消息。
- 验证包括检查值是否为数字、是否为指定倍数、是否在最小值和最大值范围内(支持 exclusiveMinimum 和 exclusiveMaximum)。
- 该函数自 WordPress 5.7.0 版本引入,常用于 REST API 参数验证。
代码示例
function rest_validate_number_value_from_schema( $value, $args, $param ) {
if ( ! is_numeric( $value ) ) {
return new WP_Error(
'rest_invalid_type',
sprintf( __( '%1$s is not of type %2$s.' ), $param, $args['type'] ),
array( 'param' => $param )
);
}
if ( isset( $args['multipleOf'] ) && fmod( $value, $args['multipleOf'] ) !== 0.0 ) {
return new WP_Error(
'rest_invalid_multiple',
sprintf( __( '%1$s must be a multiple of %2$s.' ), $param, $args['multipleOf'] )
);
}
if ( isset( $args['minimum'] ) && ! isset( $args['maximum'] ) ) {
if ( ! empty( $args['exclusiveMinimum'] ) && $value <= $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf( __( '%1$s must be greater than %2$d' ), $param, $args['minimum'] )
);
}
if ( empty( $args['exclusiveMinimum'] ) && $value < $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf( __( '%1$s must be greater than or equal to %2$d' ), $param, $args['minimum'] )
);
}
}
if ( isset( $args['maximum'] ) && ! isset( $args['minimum'] ) ) {
if ( ! empty( $args['exclusiveMaximum'] ) && $value >= $args['maximum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf( __( '%1$s must be less than %2$d' ), $param, $args['maximum'] )
);
}
if ( empty( $args['exclusiveMaximum'] ) && $value > $args['maximum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf( __( '%1$s must be less than or equal to %2$d' ), $param, $args['maximum'] )
);
}
}
if ( isset( $args['minimum'], $args['maximum'] ) ) {
if ( ! empty( $args['exclusiveMinimum'] ) && ! empty( $args['exclusiveMaximum'] ) ) {
if ( $value >= $args['maximum'] || $value <= $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf( __( '%1$s must be between %2$d and %3$d (exclusive)' ), $param, $args['minimum'], $args['maximum'] )
);
}
} elseif ( ! empty( $args['exclusiveMinimum'] ) ) {
if ( $value > $args['maximum'] || $value <= $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf( __( '%1$s must be between %2$d and %3$d (exclusive minimum)' ), $param, $args['minimum'], $args['maximum'] )
);
}
} elseif ( ! empty( $args['exclusiveMaximum'] ) ) {
if ( $value >= $args['maximum'] || $value < $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf( __( '%1$s must be between %2$d and %3$d (exclusive maximum)' ), $param, $args['minimum'], $args['maximum'] )
);
}
} else {
if ( $value > $args['maximum'] || $value < $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf( __( '%1$s must be between %2$d and %3$d' ), $param, $args['minimum'], $args['maximum'] )
);
}
}
}
return true;
}注意事项
- 该函数依赖于 is_numeric() 和 fmod() 进行基础验证,确保传入的 $value 是数字类型。
- schema 数组 $args 应包含 type、multipleOf、minimum、maximum、exclusiveMinimum 和 exclusiveMaximum 等键,以定义验证规则。
- 错误消息使用 __() 函数进行国际化,便于翻译。
- 相关函数包括 rest_validate_integer_value_from_schema() 和 rest_validate_value_from_schema(),用于更广泛的验证场景。
原文内容
Validates a number 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_number_value_from_schema( $value, $args, $param ) {
if ( ! is_numeric( $value ) ) {
return new WP_Error(
'rest_invalid_type',
/* translators: 1: Parameter, 2: Type name. */
sprintf( __( '%1$s is not of type %2$s.' ), $param, $args['type'] ),
array( 'param' => $param )
);
}
if ( isset( $args['multipleOf'] ) && fmod( $value, $args['multipleOf'] ) !== 0.0 ) {
return new WP_Error(
'rest_invalid_multiple',
/* translators: 1: Parameter, 2: Multiplier. */
sprintf( __( '%1$s must be a multiple of %2$s.' ), $param, $args['multipleOf'] )
);
}
if ( isset( $args['minimum'] ) && ! isset( $args['maximum'] ) ) {
if ( ! empty( $args['exclusiveMinimum'] ) && $value <= $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
/* translators: 1: Parameter, 2: Minimum number. */
sprintf( __( '%1$s must be greater than %2$d' ), $param, $args['minimum'] )
);
}
if ( empty( $args['exclusiveMinimum'] ) && $value < $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
/* translators: 1: Parameter, 2: Minimum number. */
sprintf( __( '%1$s must be greater than or equal to %2$d' ), $param, $args['minimum'] )
);
}
}
if ( isset( $args['maximum'] ) && ! isset( $args['minimum'] ) ) {
if ( ! empty( $args['exclusiveMaximum'] ) && $value >= $args['maximum'] ) {
return new WP_Error(
'rest_out_of_bounds',
/* translators: 1: Parameter, 2: Maximum number. */
sprintf( __( '%1$s must be less than %2$d' ), $param, $args['maximum'] )
);
}
if ( empty( $args['exclusiveMaximum'] ) && $value > $args['maximum'] ) {
return new WP_Error(
'rest_out_of_bounds',
/* translators: 1: Parameter, 2: Maximum number. */
sprintf( __( '%1$s must be less than or equal to %2$d' ), $param, $args['maximum'] )
);
}
}
if ( isset( $args['minimum'], $args['maximum'] ) ) {
if ( ! empty( $args['exclusiveMinimum'] ) && ! empty( $args['exclusiveMaximum'] ) ) {
if ( $value >= $args['maximum'] || $value <= $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf(
/* translators: 1: Parameter, 2: Minimum number, 3: Maximum number. */
__( '%1$s must be between %2$d (exclusive) and %3$d (exclusive)' ),
$param,
$args['minimum'],
$args['maximum']
)
);
}
}
if ( ! empty( $args['exclusiveMinimum'] ) && empty( $args['exclusiveMaximum'] ) ) {
if ( $value > $args['maximum'] || $value <= $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf(
/* translators: 1: Parameter, 2: Minimum number, 3: Maximum number. */
__( '%1$s must be between %2$d (exclusive) and %3$d (inclusive)' ),
$param,
$args['minimum'],
$args['maximum']
)
);
}
}
if ( ! empty( $args['exclusiveMaximum'] ) && empty( $args['exclusiveMinimum'] ) ) {
if ( $value >= $args['maximum'] || $value < $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf(
/* translators: 1: Parameter, 2: Minimum number, 3: Maximum number. */
__( '%1$s must be between %2$d (inclusive) and %3$d (exclusive)' ),
$param,
$args['minimum'],
$args['maximum']
)
);
}
}
if ( empty( $args['exclusiveMinimum'] ) && empty( $args['exclusiveMaximum'] ) ) {
if ( $value > $args['maximum'] || $value < $args['minimum'] ) {
return new WP_Error(
'rest_out_of_bounds',
sprintf(
/* translators: 1: Parameter, 2: Minimum number, 3: Maximum number. */
__( '%1$s must be between %2$d (inclusive) and %3$d (inclusive)' ),
$param,
$args['minimum'],
$args['maximum']
)
);
}
}
}
return true;
}
Changelog
| Version | Description |
|---|---|
| 5.7.0 | Introduced. |