sanitize_meta()
云策文档标注
概述
sanitize_meta() 函数用于对元数据值进行清理，本身不执行具体清理操作，而是通过动态过滤器钩子允许开发者自定义清理逻辑。它被 add_metadata() 和 update_metadata() 等 WordPress 核心函数调用。
关键要点
- 函数参数包括 $meta_key（元数据键）、$meta_value（元数据值）、$object_type（对象类型，如 'post'、'user'）和可选的 $object_subtype（对象子类型）。
- 返回清理后的 $meta_value，具体清理逻辑通过过滤器钩子实现，钩子格式为 "sanitize_{$object_type}_meta_{$meta_key}" 或带子类型的变体。
- 支持对象子类型（WordPress 4.9.8 引入），优先检查子类型特定的过滤器钩子。
- 主要用于元数据添加和更新时的值验证与清理，确保数据安全性和一致性。
代码示例
$clean_value = sanitize_meta( 'birth-year', $user_input, 'user' );
function wpdocs_sanitize_birth_year_meta( $year ) {
$now = date( 'Y' );
$then = $now - 115; // No users older than 115.
if ( $then > $year || $year > $now ) {
wp_die( __( 'Invalid entry, go back and try again.', 'textdomain' ) );
}
return $year;
}
add_filter( 'sanitize_user_meta_birth-year', 'wpdocs_sanitize_birth_year_meta' );
原文内容
Sanitizes meta value.
Parameters
$meta_keystringrequired-
Metadata key.
$meta_valuemixedrequired-
Metadata value to sanitize.
$object_typestringrequired-
Type of object metadata is for. Accepts
'blog','post','comment','term','user', or any other object type with an associated meta table. $object_subtypestringoptional-
The subtype of the object type. Default empty string.
Source
function sanitize_meta( $meta_key, $meta_value, $object_type, $object_subtype = '' ) {
if ( ! empty( $object_subtype ) && has_filter( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}" ) ) {
/**
* Filters the sanitization of a specific meta key of a specific meta type and subtype.
*
* The dynamic portions of the hook name, `$object_type`, `$meta_key`,
* and `$object_subtype`, refer to the metadata object type (blog, comment, post, term, or user),
* the meta key value, and the object subtype respectively.
*
* @since 4.9.8
*
* @param mixed $meta_value Metadata value to sanitize.
* @param string $meta_key Metadata key.
* @param string $object_type Type of object metadata is for. Accepts 'blog', 'post', 'comment', 'term',
* 'user', or any other object type with an associated meta table.
* @param string $object_subtype Object subtype.
*/
return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}", $meta_value, $meta_key, $object_type, $object_subtype );
}
/**
* Filters the sanitization of a specific meta key of a specific meta type.
*
* The dynamic portions of the hook name, `$meta_type`, and `$meta_key`,
* refer to the metadata object type (blog, comment, post, term, or user) and the meta
* key value, respectively.
*
* @since 3.3.0
*
* @param mixed $meta_value Metadata value to sanitize.
* @param string $meta_key Metadata key.
* @param string $object_type Type of object metadata is for. Accepts 'blog', 'post', 'comment', 'term',
* 'user', or any other object type with an associated meta table.
*/
return apply_filters( "sanitize_{$object_type}_meta_{$meta_key}", $meta_value, $meta_key, $object_type );
}
Hooks
- apply_filters( “sanitize_{$object_type}_meta_{$meta_key}”, mixed $meta_value, string $meta_key, string $object_type )
-
Filters the sanitization of a specific meta key of a specific meta type.
- apply_filters( “sanitize_{$object_type}_meta_{$meta_key}_for_{$object_subtype}”, mixed $meta_value, string $meta_key, string $object_type, string $object_subtype )
-
Filters the sanitization of a specific meta key of a specific meta type and subtype.
Skip to note 2 content
Codex
Example
$clean_value = sanitize_meta( 'birth-year', $user_input, 'user' ); function wpdocs_sanitize_birth_year_meta( $year ) { $now = date( 'Y' ); $then = $now - 115; // No users older than 115. if ( $then > $year || $year > $now ) { wp_die( __( 'Invalid entry, go back and try again.', 'textdomain' ) ); } return $year; } add_filter( 'sanitize_user_meta_birth-year', 'wpdocs_sanitize_birth_year_meta' );