delete_post_meta()
云策文档标注
概述
delete_post_meta() 函数用于删除指定文章 ID 的元数据字段。它支持基于键或键值对匹配删除，并可处理修订版以避免误删。函数内部调用 delete_metadata() 实现核心逻辑。
关键要点
- 函数接受三个参数：$post_id（整数，必需）、$meta_key（字符串，必需）和 $meta_value（混合类型，可选，默认为空）。
- 删除操作可基于键单独删除所有匹配条目，或基于键值对精确删除以避免重复键的误删。
- 出于历史原因，输入时元键和元值需进行“斜杠转义”。
- 函数返回布尔值：成功时返回 true，失败时返回 false。
- 内部处理会检查文章是否为修订版，确保从原始文章删除元数据。
代码示例
// 删除所有匹配键的元数据
delete_post_meta( $post_id, 'related_posts' );
// 删除特定键值对的元数据
delete_post_meta( $post_id, 'post_inspiration', 'Sherlock Holmes' );
// 避免误删所有键的检查示例
$value_to_delete = My_Class::get_value(); // 可能返回空字符串
if ( $value_to_delete != '' && delete_post_meta( 27, 'key', $value_to_delete ) ) {
// 安全删除键值对
}注意事项
- 提供空字符串作为 $meta_value 会导致跳过值检查，删除所有匹配键的元数据，需谨慎使用以避免意外删除。
- 若要删除所有匹配键的条目而不考虑值，建议将 $meta_value 设置为 null，否则可能返回 false 导致删除失败。
- 非标量元值必须可序列化。
原文内容
Deletes a post meta field for the given post ID.
Description
You can match based on the key, or key and value. Removing based on key and value, will keep from removing duplicate metadata with the same key. It also allows removing all metadata matching the key, if needed.
For historical reasons both the meta key and the meta value are expected to be “slashed” (slashes escaped) on input.
Parameters
$post_idintrequired-
Post ID.
$meta_keystringrequired-
Metadata name.
$meta_valuemixedoptional-
Metadata value. If provided, rows will only be removed that match the value.
Must be serializable if non-scalar. Default empty.
Source
function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) {
// Make sure meta is deleted from the post, not from a revision.
$the_post = wp_is_post_revision( $post_id );
if ( $the_post ) {
$post_id = $the_post;
}
return delete_metadata( 'post', $post_id, $meta_key, $meta_value );
}
Changelog
| Version | Description |
|---|---|
| 1.5.0 | Introduced. |
Skip to note 5 content
Codex
Other Examples
Let’s assume we had a plugin that added some meta values to posts, but now when we are uninstalling the plugin, we want to delete all the post meta keys that the plugin added. Assuming the plugin added the keys
related_postsandpost_inspiration.To delete all the keys use
delete_post_meta_by_key( $post_meta_key ). This would be added to the “uninstall” function:Or, if you wanted to delete all the keys except where
post_inspirationwas “Sherlock Holmes”:ID, 'related_posts' ); $inspiration = get_post_meta( $postinfo->ID, 'post_inspiration' ); foreach( $inspiration as $value ) { if( 'Sherlock Holmes' !== $value ) delete_post_meta( $postinfo->ID, 'post_inspiration', $value ); } } ?>Or maybe post number 185 was just deleted, and you want to remove all
related_postskeys that reference it:ID, 'related_posts', '185' ); } ?>Skip to note 6 content
Codex
Default Usage
Skip to note 7 content
Michelle Blanchette
Be VERY careful when using this function to delete a specific key-value pair. As stated in
delete_metadata()‘s documentation, providing an empty string for$meta_valuewill cause the check to be skipped entirely, resulting in all keys being deleted!To avoid accidentally deleting ALL key instances, use a short-circuit check:
$value_to_delete = My_Class::get_value(); // may return empty string if ( $value_to_delete != '' && delete_metadata( 'post', 27, 'key', $value_to_delete ) ) { // the key-value pair was safely deleted }Skip to note 8 content
Pacicio
If you want to delete all entries with a specified
meta_key, regardless of the field value, you need to setmeta_valueasnull, otherwise the function will returnfalseand the field does not get deleteddelete_post_meta( $post_id, $meta_key, null )