剖析 WordPress `the_posts` 过滤器源码：如何修改 `WP_Query` 查询出的文章列表。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

咳咳，各位观众，欢迎来到今天的“WordPress 炼金术”课堂！我是你们的老朋友，今天咱们要一起解剖一个WordPress的神秘器官：the_posts 过滤器。

别害怕，虽然听起来像解剖课，但咱们不会见血，只会见到各种代码的“血”，然后把它们炼成我们自己的金子！

今天要讲的就是如何用 the_posts 这个过滤器，来修改 WP_Query 查询出来的文章列表。 WP_Query 就像一个辛勤的矿工，挖出一堆文章，而 the_posts 就像一个精炼师，可以把这些文章按照我们的意愿重新排列、筛选、甚至直接替换成另一堆闪闪发光的“金矿”。

开场白：the_posts 是个什么鬼？

首先，我们来搞清楚 the_posts 到底是什么。简单来说，它是一个过滤器钩子 (filter hook)。WordPress 的钩子机制允许我们在特定的代码执行点插入我们自己的代码，来改变程序原有的行为。the_posts 这个钩子，就像一个拦截器，拦住 WP_Query 查询出来的文章列表，让我们有机会对这个列表进行“魔改”。

第一步：找到你的魔杖（代码编辑器）

想要使用 the_posts，我们需要在主题的 functions.php 文件，或者你自己的插件里编写代码。

第二步：念咒语（添加过滤器）

核心代码就这么一行：

add_filter( 'the_posts', 'your_custom_filter_function', 10, 2 );

add_filter()：这是添加过滤器的函数。
'the_posts'：这是我们要挂载的钩子名称，也就是 the_posts 过滤器。
'your_custom_filter_function'：这是你自定义的函数名，用来处理文章列表。你可以随便起个名字，但是要记住，等下要定义这个函数。
10：这是优先级。数字越小，优先级越高，执行得越早。通常情况下，10 是一个不错的选择。
2：这是传递给你的自定义函数的参数个数。the_posts 过滤器会传递两个参数：文章列表 ($posts) 和 WP_Query 对象 ($query)。

第三步：定义你的炼金术（自定义函数）

现在，我们要定义 your_custom_filter_function 这个函数，这才是真正的炼金术开始的地方！

/**
 * 自定义文章列表过滤器
 *
 * @param WP_Post[] $posts  文章列表（WP_Post 对象数组）。
 * @param WP_Query  $query  WP_Query 对象。
 *
 * @return WP_Post[] 修改后的文章列表。
 */
function your_custom_filter_function( $posts, $query ) {
  // 在这里编写你的代码，修改 $posts 数组
  return $posts; // 必须返回修改后的文章列表
}

$posts：这就是 WP_Query 查询出来的文章列表，是一个 WP_Post 对象的数组。
$query：这是 WP_Query 对象本身，你可以通过它访问查询的各种参数。

重点：必须返回 $posts！ 即使你没有做任何修改，也必须把 $posts 数组原封不动地返回，否则页面上可能什么都显示不出来。

案例一：只显示特定分类的文章

假设你只想在首页显示某个特定分类的文章，比如分类 ID 为 5 的文章。

function my_custom_home_filter( $posts, $query ) {
    if ( is_home() && $query->is_main_query() ) { // 仅在首页的主查询中执行
        $filtered_posts = array();
        foreach ( $posts as $post ) {
            if ( has_term( 5, 'category', $post ) ) { // 检查文章是否属于分类 ID 为 5
                $filtered_posts[] = $post;
            }
        }
        return $filtered_posts;
    }
    return $posts; // 其他情况返回原始文章列表
}
add_filter( 'the_posts', 'my_custom_home_filter', 10, 2 );

is_home()：判断是否是首页。
$query->is_main_query()：判断是否是主查询。我们通常只想修改主查询的文章列表，避免影响后台或者其他地方的查询。
has_term( 5, 'category', $post )：检查当前文章 $post 是否属于分类ID为5的分类。

案例二：按标题排序文章

有时候，你可能想按照文章标题来排序文章列表。

function my_custom_title_sort( $posts, $query ) {
    if ( $query->is_main_query() ) {
        usort( $posts, function( $a, $b ) {
            return strcmp( $a->post_title, $b->post_title );
        });
    }
    return $posts;
}
add_filter( 'the_posts', 'my_custom_title_sort', 10, 2 );

usort()：这是 PHP 的一个排序函数，可以根据自定义的比较函数来排序数组。
strcmp()：这是 PHP 的字符串比较函数，用于比较两个字符串的大小。
这个例子使用了匿名函数 (anonymous function) 作为 usort() 的比较函数。

案例三：移除重复文章

有时候，由于插件或者主题的bug，可能会导致文章列表中出现重复的文章。我们可以用 the_posts 过滤器来移除这些重复的文章。

function my_custom_remove_duplicates( $posts, $query ) {
    if ( $query->is_main_query() ) {
        $unique_posts = array();
        $post_ids = array();
        foreach ( $posts as $post ) {
            if ( ! in_array( $post->ID, $post_ids ) ) {
                $unique_posts[] = $post;
                $post_ids[] = $post->ID;
            }
        }
        return $unique_posts;
    }
    return $posts;
}
add_filter( 'the_posts', 'my_custom_remove_duplicates', 10, 2 );

这个例子使用了两个数组：$unique_posts 用于存储去重后的文章，$post_ids 用于记录已经出现过的文章 ID。

案例四：替换整个文章列表

如果你觉得 WP_Query 查询出来的文章都不合你胃口，你可以直接用 the_posts 过滤器来替换整个文章列表。

function my_custom_replace_posts( $posts, $query ) {
    if ( is_home() && $query->is_main_query() ) {
        // 构建你自己的文章列表
        $args = array(
            'post_type' => 'page', // 获取页面
            'posts_per_page' => 3, // 只获取 3 个页面
            'orderby' => 'title', // 按照标题排序
            'order' => 'ASC', // 升序
        );
        $new_query = new WP_Query( $args );
        if ( $new_query->have_posts() ) {
            $new_posts = $new_query->posts;
            return $new_posts; // 返回新的文章列表
        } else {
            return array(); // 如果没有页面，返回一个空数组
        }
    }
    return $posts; // 其他情况返回原始文章列表
}
add_filter( 'the_posts', 'my_custom_replace_posts', 10, 2 );

这个例子在首页用 3 个页面替换了原来的文章列表。

高级技巧：利用 $query 对象

the_posts 过滤器传递的第二个参数 $query 是一个 WP_Query 对象，我们可以通过它访问查询的各种参数，从而更精准地控制文章列表的修改。

例如，我们可以根据当前的分类 ID 来修改文章列表：

function my_custom_category_filter( $posts, $query ) {
    if ( $query->is_main_query() && is_category() ) {
        $category_id = get_queried_object_id(); // 获取当前分类 ID
        // 根据分类 ID 执行不同的操作
        if ( $category_id == 10 ) {
            // 如果是分类 ID 为 10 的分类页面，执行一些特殊操作
            // ...
        } elseif ( $category_id == 20 ) {
            // 如果是分类 ID 为 20 的分类页面，执行另一些特殊操作
            // ...
        }
    }
    return $posts;
}
add_filter( 'the_posts', 'my_custom_category_filter', 10, 2 );

注意事项：

性能问题： the_posts 过滤器会在每次查询文章列表时都执行，所以要尽量避免在里面执行复杂的逻辑，以免影响网站的性能。
优先级问题： 如果你的主题或者其他插件也使用了 the_posts 过滤器，要注意优先级的问题，确保你的代码能够按照你期望的顺序执行。
调试： 如果你的代码没有生效，可以使用 var_dump() 或者 error_log() 函数来调试代码，看看 $posts 和 $query 变量的值是否符合你的预期。
不要滥用： the_posts 是一个强大的工具，但也要避免滥用。如果只需要修改查询参数，最好直接修改 WP_Query 的参数，而不是使用 the_posts 过滤器。

总结：

the_posts 过滤器是一个非常灵活的工具，可以让我们在 WordPress 中对文章列表进行各种各样的修改。掌握了它，你就可以像一个炼金术士一样，把普通的文章列表变成闪闪发光的金矿。

练习题：

尝试使用 the_posts 过滤器，在文章列表中添加一个 "推荐" 标签，如果文章的浏览量超过 1000。
尝试使用 the_posts 过滤器，在搜索结果页面，将搜索结果按照相关性排序，而不是按照时间排序。

今天的课程就到这里，希望大家能够学有所成，成为真正的 WordPress 炼金术士！下课！

发表回复 取消回复

发表回复取消回复