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

各位同学们，晚上好！今天咱们来聊点刺激的，来扒一扒 WordPress 的 the_posts 过滤器，看看咱们怎么在 WP_Query 拿到文章列表之后，动点手脚，让它展现出我们想要的样子。

想象一下，WP_Query 就像一个辛勤的快递员，吭哧吭哧地从数据库里把文章列表给搬出来了。但是呢，这个快递员可能不太懂时尚，搬出来的东西可能不是我们想要的风格。这时候，the_posts 过滤器就闪亮登场了，它就像一个造型师，可以让我们在文章列表被送到“展示台”之前，给它们好好打扮一番。

什么是 the_posts 过滤器？

简单来说，the_posts 过滤器就是一个挂钩点（hook），允许我们在 WP_Query 执行查询后，但在文章列表被最终使用之前，对文章列表进行修改。它接收一个参数，就是 WP_Query 返回的文章对象数组，然后我们需要返回一个修改后的文章对象数组。

the_posts 过滤器在哪里？

the_posts 过滤器位于 wp-includes/class-wp-query.php 文件中 WP_Query::get_posts() 方法的末尾。让我们找到相关源码，简化版如下：

// wp-includes/class-wp-query.php

public function get_posts() {
  // ... 一堆查询数据库的代码 ...

  $this->posts = apply_filters_ref_array( 'the_posts', array( $this->posts, $this ) );

  return $this->posts;
}

看到了吧？apply_filters_ref_array 函数就是触发过滤器的地方。它做了两件事：

调用所有挂载到 the_posts 过滤器的函数。
将 $this->posts（也就是文章对象数组）和 $this （也就是 WP_Query 对象本身）作为参数传递给这些函数。
将过滤函数返回的结果赋值给 $this->posts。

如何使用 the_posts 过滤器？

要使用 the_posts 过滤器，我们需要使用 add_filter() 函数。这个函数接受三个参数：

过滤器名称 (这里是 'the_posts')
要执行的函数名称
优先级 (可选，默认为 10)
参数个数 (可选，默认为 1。这里因为 apply_filters_ref_array 传入了两个参数，所以我们需要指定为2)

基本结构如下：

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

function my_custom_the_posts_filter( $posts, $query ) {
  // 在这里修改 $posts 数组
  return $posts;
}

实战演练：修改文章列表

接下来，我们来几个实战例子，看看 the_posts 过滤器到底有多强大。

1. 在文章列表头部添加一个置顶推荐文章

假设我们想在文章列表的头部添加一篇指定的置顶推荐文章，即使它不符合当前的查询条件。

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

function add_featured_post_to_top( $posts, $query ) {
  // 只在主循环中执行
  if ( $query->is_main_query() && ! is_admin() ) {
    $featured_post_id = 123; // 替换为你的置顶文章 ID
    $featured_post = get_post( $featured_post_id );

    if ( $featured_post ) {
      // 将置顶文章插入到数组的开头
      array_unshift( $posts, $featured_post );

      // 确保文章列表不重复（如果置顶文章也在查询结果中）
      $posts = array_unique( $posts, SORT_REGULAR );
    }
  }

  return $posts;
}

这段代码做了什么？

首先，我们使用 add_filter 将 add_featured_post_to_top 函数挂载到 the_posts 过滤器上。
add_featured_post_to_top 函数接收 $posts (文章数组) 和 $query (WP_Query 对象) 两个参数。
我们首先检查是否是主循环，并且不在后台管理界面。这是为了避免影响后台或其他地方的查询。
我们获取置顶文章的 ID，并使用 get_post() 函数获取文章对象。
如果成功获取到文章对象，我们使用 array_unshift() 函数将文章对象插入到 $posts 数组的开头。
最后，使用 array_unique() 函数移除重复的文章（如果置顶文章也在查询结果中）。SORT_REGULAR 确保我们比较的是整个对象，而不是简单地比较 ID。

2. 过滤掉特定分类的文章

有时候，我们可能需要从文章列表中排除某些分类的文章。

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

function exclude_category_from_posts( $posts, $query ) {
  // 只在主循环中执行
  if ( $query->is_main_query() && ! is_admin() ) {
    $excluded_category_id = 456; // 替换为你要排除的分类 ID
    $filtered_posts = array();

    foreach ( $posts as $post ) {
      if ( ! has_category( $excluded_category_id, $post ) ) {
        $filtered_posts[] = $post;
      }
    }

    return $filtered_posts;
  }

  return $posts;
}

这段代码的逻辑是：

遍历文章数组 $posts。
对于每一篇文章，使用 has_category() 函数检查它是否属于要排除的分类。
如果不属于，则将文章添加到 $filtered_posts 数组中。
最后，返回 $filtered_posts 数组，这个数组不包含任何属于被排除分类的文章。

3. 按自定义字段排序

假设我们想按照文章的某个自定义字段的值来排序文章列表。

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

function sort_posts_by_custom_field( $posts, $query ) {
  // 只在主循环中执行
  if ( $query->is_main_query() && ! is_admin() ) {
    $custom_field_key = 'my_custom_field'; // 替换为你的自定义字段的 key

    usort( $posts, function( $a, $b ) use ( $custom_field_key ) {
      $value_a = get_post_meta( $a->ID, $custom_field_key, true );
      $value_b = get_post_meta( $b->ID, $custom_field_key, true );

      // 比较逻辑，可以根据字段类型进行调整
      if ( $value_a == $value_b ) {
        return 0;
      }
      return ( $value_a < $value_b ) ? -1 : 1;
    } );
  }

  return $posts;
}

这里，我们使用了 usort() 函数，这是一个 PHP 内置的排序函数，允许我们自定义排序逻辑。我们使用匿名函数来定义比较规则：

获取每篇文章的自定义字段的值。
比较这两个值。
返回 -1, 0, 或 1，指示 $a 应该排在 $b 之前，相同，或之后。

4. 修改文章内容（谨慎使用！）

虽然不推荐，但我们也可以在 the_posts 过滤器中修改文章的内容。这样做可能会影响性能，因为每次查询都会修改文章内容。

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

function modify_post_content( $posts, $query ) {
  // 只在主循环中执行
  if ( $query->is_main_query() && ! is_admin() ) {
    foreach ( $posts as &$post ) {
      $post->post_content = '<div>' . $post->post_content . '</div>'; // 在内容前后添加 div 标签
    }
  }

  return $posts;
}

注意：这里我们使用了 &$post，这意味着我们传递的是文章对象的引用。这样，我们对 $post 的修改会直接影响到原始的文章对象。此外，在修改文章内容之前，请三思而后行，尽量使用其他更合适的方法，例如模板文件。

WP_Query 对象的妙用

在上面的例子中，我们都使用了 $query 对象来判断是否是主循环。 $query 对象包含了关于当前查询的所有信息，我们可以利用它来做很多事情。

$query->is_main_query(): 判断是否是主循环。
$query->is_home(): 判断是否是首页。
$query->is_category(): 判断是否是分类页面。
$query->get( 'category_name' ): 获取当前分类的别名。
$query->get( 's' ): 获取搜索关键词。

通过 $query 对象，我们可以根据不同的条件，应用不同的过滤规则，让我们的 the_posts 过滤器更加灵活。

一些注意事项

性能问题: the_posts 过滤器会在每次查询后执行，所以尽量避免在过滤器中进行耗时的操作，例如复杂的数据库查询。
避免冲突: 如果多个插件或主题都使用了 the_posts 过滤器，可能会发生冲突。可以使用不同的优先级来控制过滤器的执行顺序。
调试技巧: 可以使用 var_dump() 或 error_log() 函数来调试过滤器，查看文章数组的内容。

总结

the_posts 过滤器是一个非常强大的工具，可以让我们在 WP_Query 查询之后，对文章列表进行各种修改。我们可以添加、删除、排序文章，甚至修改文章的内容。但是，在使用 the_posts 过滤器时，一定要注意性能问题和避免冲突。

希望今天的讲座对大家有所帮助。掌握了 the_posts 过滤器，你就可以像一个真正的 WordPress 大师一样，掌控你的文章列表，让它们展现出你想要的样子！下课！

表格总结常用场景和代码

场景	代码示例
添加置顶文章到列表头部	`php add_filter( 'the_posts', 'add_featured_post_to_top', 10, 2 ); function add_featured_post_to_top( $posts, $query ) { if ( $query->is_main_query() && ! is_admin() ) { $featured_post_id = 123; $featured_post = get_post( $featured_post_id ); if ( $featured_post ) { array_unshift( $posts, $featured_post ); $posts = array_unique( $posts, SORT_REGULAR ); } } return $posts; }`
排除特定分类的文章	`php add_filter( 'the_posts', 'exclude_category_from_posts', 10, 2 ); function exclude_category_from_posts( $posts, $query ) { if ( $query->is_main_query() && ! is_admin() ) { $excluded_category_id = 456; $filtered_posts = array(); foreach ( $posts as $post ) { if ( ! has_category( $excluded_category_id, $post ) ) { $filtered_posts[] = $post; } } return $filtered_posts; } return $posts; }`
按自定义字段排序	php add_filter( 'the_posts', 'sort_posts_by_custom_field', 10, 2 ); function sort_posts_by_custom_field( $posts, $query ) { if ( $query->is_main_query() && ! is_admin() ) { $custom_field_key = 'my_custom_field'; usort( $posts, function( $a, $b ) use ( $custom_field_key ) { $value_a = get_post_meta( $a->ID, $custom_field_key, true ); $value_b = get_post_meta( $b->ID, $custom_field_key, true ); if ( $value_a == $value_b ) { return 0; } return ( $value_a < $value_b ) ? -1 : 1; } ); } return $posts; }
修改文章内容 (谨慎使用)	`php add_filter( 'the_posts', 'modify_post_content', 10, 2 ); function modify_post_content( $posts, $query ) { if ( $query->is_main_query() && ! is_admin() ) { foreach ( $posts as &$post ) { $post->post_content = '<div>' . $post->post_content . '</div>'; } } return $posts; }`
使用 `$query` 对象判断是否是主循环	`php if ( $query->is_main_query() ) { // ... }`
使用 `$query` 对象判断是否是首页	`php if ( $query->is_home() ) { // ... }`
使用 `$query` 对象获取当前分类的别名	`php $category_name = $query->get( 'category_name' );`
使用 `$query` 对象获取搜索关键词	`php $search_keyword = $query->get( 's' );`

发表回复 取消回复

发表回复取消回复