云策 WordPress 开发者社区

钩子文档

update_{$meta_type}_metadata

查看官方原文 ↗
💡 云策文档标注

概述

update_{$meta_type}_metadata 是一个 WordPress 过滤器，用于在更新特定类型的元数据（如博客、文章、评论、分类、用户等）时进行短路操作。通过返回非 null 值，可以阻止元数据保存到数据库。

关键要点

  • 这是一个动态钩子，$meta_type 指代元对象类型（如 blog、post、comment、term、user 等），对应具体钩子如 update_user_metadata。
  • 过滤器在元数据更新前应用，返回 null 允许正常保存，返回其他值（如 false）则短路更新过程。
  • 参数包括 $check（是否允许更新）、$object_id（对象 ID）、$meta_key（元数据键）、$meta_value（元数据值）和 $prev_value（前值，可选）。
  • 常用于自定义元数据验证或阻止特定元数据更新。

代码示例

add_filter( 'update_user_metadata', function( $check, $object_id, $meta_key, $meta_value ) {
    if ( 'foo' == $meta_key && empty( $meta_value ) ) {
        return false; // 阻止保存空值
    }
    return $check; // 继续正常执行
}, 10, 4 );

注意事项

  • 短路操作可能影响数据一致性，需谨慎处理，例如阻止保存空值时应考虑是否需要删除现有元数据。
  • 确保过滤器逻辑正确，避免意外阻止所有元数据更新。
📄 原文内容

Short-circuits updating metadata of a specific type.

Description

The dynamic portion of the hook name, $meta_type, refers to the meta object type (blog, post, comment, term, user, or any other type with an associated meta table).
Returning a non-null value will effectively short-circuit the function.

Possible hook names include:

  • update_blog_metadata
  • update_post_metadata
  • update_comment_metadata
  • update_term_metadata
  • update_user_metadata

Parameters

$checknull|bool
Whether to allow updating metadata for the given type.
$object_idint
ID of the object metadata is for.
$meta_keystring
Metadata key.
$meta_valuemixed
Metadata value. Must be serializable if non-scalar.
$prev_valuemixed
Previous value to check before updating.
If specified, only update existing metadata entries with this value. Otherwise, update all entries.

More Information

  • This filter is applied before a metadata gets updated; it allows short-circuiting the updating of metadata of a specific type by returning a non-null value.
  • The dynamic portion of the hook, $meta_type, refers to the meta object type. For example, if a ‘user’ metadata gets updated, the hook would be ‘update_user_metadata‘.
  • The filter must return a null value (the value of $check) if the data is be saved to the database. If it returns anything else, the ‘update_metadata‘ function (and therefore the ‘update_{$meta_type}_metadata‘ filter) will return what the filter callbacks return.

Source

$check = apply_filters( "update_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $prev_value );

View all references View on Trac View on GitHub

Used by Description
update_metadata()wp-includes/meta.php

Updates metadata for the specified object. If no value already exists for the specified object ID and metadata key, the metadata will be added.

Changelog

Version Description
3.1.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Steven Lin


    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    Example migrated from Codex:

    The example below skips saving the metadata with the key ‘foo’ and an empty value. For other metadata, continue the normal execution.

    add_action( 'init', 'wpdocs_init' );

function wpdocs_init() {
   add_filter( 'update_user_metadata', 'wpdocs_update_foo', 10, 4 );
}

function wpdocs_update_foo( $check, $object_id, $meta_key, $meta_value ) {

   if ( 'foo' == $meta_key && empty( $meta_value ) ) {
      return false; // this means: stop saving the value into the database
   }

   return $check; // this means: go on with the normal execution in meta.php
}

  2. Skip to note 4 content


    crstauf


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Similar to stevenlinx’s example, to skip saving empty value of foo to user metadata. Note that this could create problems if the user is attempting to clear previously entered data; an additional hook should be included that deletes the foo key from the user’s metadata if the value is empty.

    add_filter( 'update_user_metadata', function( $check, $object_id, $meta_key, $meta_value ) {

    // Already short-circuited; bail.
    if ( null !== $check )
        return $check;

    // Bail if not saving the 'foo' metadata.
    if ( 'foo' !== $meta_key )
        return null;

    // If meta value is not empty, then we _want_ to save it.
    if ( ! empty( $meta_value ) )
        return null;

    // Prevent saving empty value to user's 'foo' metadata.
    return false;
}, 10, 4 );