云策 WordPress 开发者社区

钩子文档

get_{$meta_type}_metadata

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

概述

get_{$meta_type}_metadata 是一个 WordPress 过滤器钩子，用于短路元数据字段的返回值。它允许开发者在获取元数据时拦截并自定义返回的值，而不是从数据库或缓存中读取。

关键要点

  • 钩子名称中的 $meta_type 是动态部分，指代元对象类型，如 blog、post、comment、term、user 等。
  • 返回非 null 值将短路 get_metadata() 函数，直接返回该值；返回 null 则继续正常执行，从数据库获取数据。
  • 过滤器接收参数：$value（默认 null）、$object_id、$meta_key、$single 和 $meta_type。
  • 使用时应注意与其他插件兼容：回调函数应返回 $value 参数，而不是硬编码 null，以避免覆盖高优先级过滤器的设置。

代码示例

add_action( 'init', 'wpdocs_init' );

function wpdocs_init() {
    add_filter( 'get_user_metadata', 'wpdocs_get_foo', 10, 3 );
}

function wpdocs_get_foo( $check, $object_id, $meta_key ) {
    if ( 'foo' === $meta_key ) {
        // 始终返回数组形式的值
        return array( 'bar' );
    }
    return $check; // 继续正常执行
}

注意事项

  • 回调函数的第一个参数 $value 可能不是 null，可能是之前过滤器设置的值，因此应返回 $value 而不是 null 以保持兼容性。
  • 钩子从 WordPress 3.1.0 版本引入，5.5.0 版本增加了 $meta_type 参数。
📄 原文内容

Short-circuits the return value of a meta field.

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 filter names include:

  • get_blog_metadata
  • get_post_metadata
  • get_comment_metadata
  • get_term_metadata
  • get_user_metadata

Parameters

$valuemixed
The value to return, either a single metadata value or an array of values depending on the value of $single. Default null.
$object_idint
ID of the object metadata is for.
$meta_keystring
Metadata key.
$singlebool
Whether to return only the first value of the specified $meta_key.
$meta_typestring
Type of object metadata is for. Accepts 'blog', 'post', 'comment', 'term', 'user', or any other object type with an associated meta table.

More Information

The filter must return null if the data should be taken from the database. If it returns anything else, the get_metadata() function (and therefore the get_user_meta) will return what the filter returns.

Source

$check = apply_filters( "get_{$meta_type}_metadata", null, $object_id, $meta_key, $single, $meta_type );

View all references View on Trac View on GitHub

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

Retrieves raw metadata value for the specified object.
metadata_exists()wp-includes/meta.php

Determines if a meta field with the given key exists for the given object ID.

Changelog

Version Description
5.5.0 Added the $meta_type parameter.
3.1.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    leogermani


    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

    Note that although this filter filters the value that will be returned, you do not receive the current value as the first parameter.

    You allways receive null in the first parameter.

    If your callback returns anything else than null, this is the value that the function will return at the end. If you return null, the function will continue to run normally and try to fetch the data from the database (or cache).

  2. Skip to note 4 content


    Steven Lin


    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

    Example migrated from Codex:

    add_action( 'init', 'wpdocs_init' );

function wpdocs_init() {
	add_filter( 'get_user_metadata', 'wpdocs_get_foo', 10, 3 );
}

function wpdocs_get_foo( $check, $object_id, $meta_key ) {
	if ( 'foo' === $meta_key ) {
		// Always return an array with your return value.
		return array( 'bar' );
	}

	return $check; // Go on with the normal execution in meta.php
}