云策 WordPress 开发者社区

钩子文档

posts_search

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

概述

posts_search 是一个 WordPress 过滤器，用于修改 WP_Query 中 WHERE 子句的搜索 SQL 语句。它允许开发者自定义搜索逻辑，例如限制搜索范围或添加额外条件。

关键要点

  • posts_search 过滤器用于过滤 WP_Query 的 WHERE 子句中的搜索 SQL。
  • 它接受两个参数：$search（搜索 SQL 字符串）和 $query（WP_Query 对象）。
  • 自 WordPress 3.0.0 版本引入，常用于高级搜索定制。
  • 通常与 add_filter 结合使用，以修改默认搜索行为。

代码示例

function wpdocs_search_by_title_only( $search, $wp_query ) {
    global $wpdb;

    if ( empty( $search ) ) {
        return $search; // 跳过处理 - 查询中无搜索词
    }

    $q = $wp_query->query_vars;
    $n = ! empty( $q['exact'] ) ? '' : '%';
    $search = '';
    $searchand = '';

    foreach ( (array) $q['search_terms'] as $term ) {
        $term = esc_sql( $wpdb->esc_like( $term ) );
        $search .= "{$searchand}($wpdb->posts.post_title LIKE '{$n}{$term}{$n}')";
        $searchand = ' AND ';
    }

    if ( ! empty( $search ) ) {
        $search = " AND ({$search}) ";
        if ( ! is_user_logged_in() )
            $search .= " AND ($wpdb->posts.post_password = '') ";
    }

    return $search;
}
add_filter( 'posts_search', 'wpdocs_search_by_title_only', 500, 2 );

注意事项

  • 函数签名应为 function __search_by_title_only( $search, $wp_query )，而非使用引用 &$wp_query，以避免潜在问题。
  • 确保正确处理 SQL 转义和安全性，如使用 $wpdb->esc_like() 和 esc_sql()。
  • 过滤器优先级（如 500）可根据需要调整，以控制执行顺序。
📄 原文内容

Filters the search SQL that is used in the WHERE clause of WP_Query.

Parameters

$searchstring
Search SQL for WHERE clause.
$queryWP_Query
The current WP_Query object.

More Information

Since version 3.0.0, the posts_search filter is used to filter the search SQL that is used in the WHERE clause of WP_Query.

Source

$search = apply_filters_ref_array( 'posts_search', array( $search, &$this ) );

View all references View on Trac View on GitHub

Used by Description
WP_Query::get_posts()wp-includes/class-wp-query.php

Retrieves an array of posts based on query variables.

Changelog

Version Description
3.0.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    norrismp


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

    Example function search by title only:

    function wpdocs_search_by_title_only( $search, $wp_query ) {
    global $wpdb;

    if ( empty( $search ) ) {
        return $search; // skip processing - no search term in query
    }

    $q = $wp_query->query_vars;
    $n = ! empty( $q['exact'] ) ? '' : '%';
    $search = '';
    $searchand = '';

    foreach ( (array) $q['search_terms'] as $term ) {
        $term = esc_sql( $wpdb->esc_like( $term ) );
        $search .= "{$searchand}($wpdb->posts.post_title LIKE '{$n}{$term}{$n}')";
        $searchand = ' AND ';
    }

    if ( ! empty( $search ) ) {
        $search = " AND ({$search}) ";
        if ( ! is_user_logged_in() )
            $search .= " AND ($wpdb->posts.post_password = '') ";
    }

    return $search;
}
add_filter( 'posts_search', 'wpdocs_search_by_title_only', 500, 2 );