云策 WordPress 开发者社区

钩子文档

pre_user_query

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

概述

pre_user_query 是一个 WordPress 动作钩子，在 WP_User_Query 解析后、执行前触发，允许开发者修改查询参数或 SQL 语句。

关键要点

  • 触发时机：在 WP_User_Query 解析完成之后，查询执行之前
  • 参数：传递一个 WP_User_Query 对象（引用传递），包含已解析的 SQL 部分
  • 用途：常用于自定义用户查询逻辑，如修改搜索条件或添加元数据过滤
  • 版本：自 WordPress 3.1.0 引入

代码示例

add_action('pre_user_query', function($uqi) {
    global $wpdb;
    $search = '';
    if (isset($uqi->query_vars['search']) && !empty($uqi->query_vars['search']))
        $search = trim($uqi->query_vars['search']);

    if ($search) {
        $search = trim($search, '*');
        $the_search = '%'.$search.'%';

        $search_meta = $wpdb->prepare("
        ID IN ( SELECT user_id FROM {$wpdb->usermeta}
        WHERE ( ( meta_key='first_name' OR meta_key='last_name' )
            AND {$wpdb->usermeta}.meta_value LIKE '%s' )
        )", $the_search);

        $uqi->query_where = str_replace(
            'WHERE 1=1 AND (',
            "WHERE 1=1 AND (" . $search_meta . " OR ",
            $uqi->query_where );
    }
});

注意事项

  • 参数 $query 是 WP_User_Query 实例，通过引用传递，可直接修改其属性（如 query_where）
  • 相关函数：WP_User_Query::prepare_query() 用于准备查询变量
  • 用户贡献笔记中提供了扩展搜索到用户元数据（如 first_name、last_name）的示例代码
📄 原文内容

Fires after the WP_User_Query has been parsed, and before the query is executed.

Description

The passed WP_User_Query object contains SQL parts formed from parsing the given query.

Parameters

$queryWP_User_Query
Current instance of WP_User_Query (passed by reference).

Source

do_action_ref_array( 'pre_user_query', array( &$this ) );

View all references View on Trac View on GitHub

Used by Description
WP_User_Query::prepare_query()wp-includes/class-wp-user-query.php

Prepares the query variables.

Changelog

Version Description
3.1.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    tikot


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

    Find user by usermeta add change the meta key or add more meta keys OR meta_key='key_name' between () on WHERE line

    query_vars['search'] ) )
        $search = trim( $uqi->query_vars['search'] );

    if ( $search ) {
        $search = trim($search, '*');
        $the_search = '%'.$search.'%';

        $search_meta = $wpdb->prepare("
        ID IN ( SELECT user_id FROM {$wpdb->usermeta}
        WHERE ( ( meta_key='first_name' OR meta_key='last_name' )
            AND {$wpdb->usermeta}.meta_value LIKE '%s' )
        )", $the_search);

        $uqi->query_where = str_replace(
            'WHERE 1=1 AND (',
            "WHERE 1=1 AND (" . $search_meta . " OR ",
            $uqi->query_where );
    }
});