函数文档

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.

Return

true|WP_Error

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.