分析 WordPress `get_comments()` 函数的源码：如何通过 `WP_Comment_Query` 类查询评论列表。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

WordPress 评论查询的秘密：`get_comments()` 和 `WP_Comment_Query` 的深度剖析

各位观众，晚上好！我是你们的老朋友，今天咱们来聊聊 WordPress 评论查询的那些事儿。大家肯定都用过 get_comments() 函数，但你真的了解它背后的运作机制吗？今天，我们就深入剖析一下，特别是它如何借助强大的 WP_Comment_Query 类来获取评论列表。准备好了吗？咱们开始咯！

1. `get_comments()`：评论查询的入口

get_comments() 函数是 WordPress 中获取评论列表的常用函数。它接受一个参数，可以是一个参数数组，也可以是一个查询字符串。我们先来看一个简单的例子：

$comments = get_comments( array(
  'number' => 10, // 获取最新的 10 条评论
  'status' => 'approve' // 只获取已审核的评论
));

if ( $comments ) {
  foreach ( $comments as $comment ) {
    echo '<p>' . get_comment_author( $comment->comment_ID ) . ': ' . get_comment_text( $comment->comment_ID ) . '</p>';
  }
} else {
  echo 'No comments found.';
}

这段代码很简单，就是获取最新的 10 条已审核的评论，然后循环输出评论作者和评论内容。但是，get_comments() 函数内部到底做了什么呢？别急，咱们一步步来。

2. `get_comments()` 的内部运作

get_comments() 函数的核心任务是将传入的参数传递给 WP_Comment_Query 类，然后利用 WP_Comment_Query 类来执行数据库查询。它的基本结构大致如下：

function get_comments( $args = '' ) {
  global $wpdb;

  $defaults = array(
    'number'  => 'all',
    'offset'  => 0,
    'orderby' => '',
    'order'   => 'DESC',
    'status'  => 'approve',
    // ... 其他参数
  );

  $args = wp_parse_args( $args, $defaults );

  // 创建 WP_Comment_Query 实例
  $comment_query = new WP_Comment_Query( $args );

  // 执行查询并返回结果
  $comments = $comment_query->comments;

  return $comments;
}

可以看到，get_comments() 函数主要做了以下几件事：

设置默认参数： 使用 $defaults 数组定义了查询的默认参数，例如评论数量、排序方式、评论状态等。
解析参数： 使用 wp_parse_args() 函数将传入的参数与默认参数合并，确保所有需要的参数都被正确设置。
创建 WP_Comment_Query 实例： 这是最关键的一步，将解析后的参数传递给 WP_Comment_Query 类的构造函数，创建一个 WP_Comment_Query 对象。
执行查询： WP_Comment_Query 对象在创建时会自动执行查询，并将结果存储在 comments 属性中。
返回结果： get_comments() 函数直接返回 WP_Comment_Query 对象的 comments 属性，也就是查询到的评论列表。

3. `WP_Comment_Query`：评论查询的核心引擎

WP_Comment_Query 类是 WordPress 中用于查询评论的核心类。它负责构建 SQL 查询语句，执行数据库查询，并将查询结果转换为评论对象。我们接下来深入了解一下 WP_Comment_Query 类的主要方法和属性。

3.1 `WP_Comment_Query` 的构造函数 `__construct()`

WP_Comment_Query 类的构造函数接受一个参数数组，这个数组包含了查询评论的所有参数。构造函数的主要任务是：

解析参数： 与 get_comments() 函数类似，构造函数也会解析传入的参数，并将其存储在类的属性中。
构建 SQL 查询语句： 根据解析后的参数，构造函数会构建一个复杂的 SQL 查询语句，用于从数据库中获取符合条件的评论。
执行查询： 构造函数会执行构建好的 SQL 查询语句，并将查询结果存储在类的 comments 属性中。

我们来看一下 WP_Comment_Query 构造函数的部分代码：

public function __construct( $query = '' ) {
  if ( ! empty( $query ) ) {
    $this->query( $query );
  }
}

public function query( $query ) {
  $this->query_vars = wp_parse_args( $query, $this->query_vars );
  return $this->get_comments();
}

public function get_comments() {
  global $wpdb;

  // ... 解析参数，设置查询变量

  // 构建 SQL 查询语句
  $this->get_sql();

  // 执行查询
  $this->comments = $wpdb->get_results( $this->request );

  // ... 处理查询结果，例如将查询结果转换为评论对象

  return $this->comments;
}

3.2 `WP_Comment_Query` 的重要属性

WP_Comment_Query 类有很多重要的属性，这些属性用于存储查询参数、查询结果和 SQL 查询语句。以下是一些常用的属性：

属性名	类型	描述
`query_vars`	array	存储查询参数的数组，例如 `number`、`offset`、`orderby`、`order`、`status` 等。
`comments`	array	存储查询结果的数组，数组中的每个元素都是一个评论对象。
`comment_count`	int	评论的总数。
`sql_clauses`	array	存储SQL语句的各个部分，比如`select`，`from`，`where`，`orderby`，`limits`等。
`request`	string	完整的 SQL 查询语句。
`db_fields`	array	数据库中评论表对应的字段名。

3.3 `WP_Comment_Query` 的重要方法

除了构造函数之外，WP_Comment_Query 类还有很多重要的方法，这些方法用于构建 SQL 查询语句、执行查询和处理查询结果。以下是一些常用的方法：

prepare_query(): 这个方法准备查询。它会处理传入的参数，进行验证，设置默认值，并进行必要的清理工作。
get_sql(): 这个方法根据查询参数构建 SQL 查询语句。它会将查询参数转换为 SQL 语句的各个部分，例如 WHERE 子句、ORDER BY 子句和 LIMIT 子句。
get_comments(): 实际执行查询并返回评论列表。
parse_comment(): 这个方法将数据库查询结果转换为评论对象。

4. `WP_Comment_Query` 的参数详解

WP_Comment_Query 类支持很多参数，这些参数可以控制查询的行为。以下是一些常用的参数：

参数名	类型	描述
`number`	int	要获取的评论数量。如果设置为 `'all'`，则获取所有评论。
`offset`	int	要跳过的评论数量。
`orderby`	string	排序方式。常用的值包括 `comment_ID`、`comment_date`、`comment_post_ID`、`comment_author_email` 等。
`order`	string	排序顺序。常用的值包括 `ASC`（升序）和 `DESC`（降序）。
`status`	string	评论状态。常用的值包括 `approve`（已审核）、`hold`（待审核）、`spam`（垃圾评论）、`trash`（已删除）和 `any`（所有状态）。
`post_id`	int	只获取指定文章的评论。
`post_id__in`	array	只获取指定文章列表的评论。
`post_id__not_in`	array	排除指定文章列表的评论。
`user_id`	int	只获取指定用户的评论。
`author_email`	string	只获取指定作者邮箱的评论。
`date_query`	array	日期查询参数，可以根据日期范围过滤评论。
`meta_query`	array	元数据查询参数，可以根据评论元数据过滤评论。
`parent`	int	只获取指定评论的子评论。
`parent__in`	array	只获取指定评论列表的子评论。
`parent__not_in`	array	排除指定评论列表的子评论。
`hierarchical`	mixed	获取评论的层级结构. 可选值 `flat` (默认), `threaded` 和 `false`.

5. `WP_Comment_Query` 的高级用法

除了基本的查询参数之外，WP_Comment_Query 类还支持一些高级用法，例如使用 date_query 和 meta_query 参数进行更复杂的过滤。

5.1 `date_query` 参数

date_query 参数允许你根据日期范围过滤评论。它接受一个数组，数组中的每个元素都定义了一个日期条件。例如，以下代码获取 2023 年 1 月 1 日之后的所有评论：

$comments = get_comments( array(
  'date_query' => array(
    array(
      'after' => '2023-01-01',
    ),
  ),
));

date_query 参数还支持其他日期条件，例如 before、year、month、day 等。

5.2 `meta_query` 参数

meta_query 参数允许你根据评论元数据过滤评论。它接受一个数组，数组中的每个元素都定义了一个元数据条件。例如，以下代码获取 rating 元数据值为 5 的所有评论：

$comments = get_comments( array(
  'meta_query' => array(
    array(
      'key'   => 'rating',
      'value' => '5',
      'compare' => '=',
    ),
  ),
));

meta_query 参数还支持其他比较运算符，例如 !=、>、<、LIKE 等。

5.3 自定义SQL语句

虽然 WP_Comment_Query 已经提供了强大的查询功能，但在某些特殊情况下，你可能需要自定义 SQL 查询语句。 WP_Comment_Query 提供了一个 comments_clauses 过滤器，允许你修改查询的各个部分。

add_filter( 'comments_clauses', 'my_custom_comment_clauses', 10, 1 );

function my_custom_comment_clauses( $clauses ) {
  // 在 WHERE 子句中添加自定义条件
  $clauses['where'] .= " AND comment_karma > 10 ";

  return $clauses;
}

$comments = get_comments(); // 使用了自定义 WHERE 子句的查询

注意: 使用自定义 SQL 语句需要谨慎，确保你的 SQL 语句是安全且正确的。

6. 实战案例：构建一个评论管理面板

现在，让我们通过一个实战案例来巩固一下所学知识。假设我们要构建一个简单的评论管理面板，可以根据评论状态过滤评论，并显示评论作者、评论内容和评论日期。

<?php
// 获取所有评论状态
$comment_statuses = array(
  'approve' => '已审核',
  'hold'    => '待审核',
  'spam'    => '垃圾评论',
  'trash'   => '已删除',
);

// 获取当前选择的评论状态
$current_status = isset( $_GET['status'] ) ? $_GET['status'] : 'approve';

// 构建查询参数
$args = array(
  'status' => $current_status,
  'number' => 20, // 每页显示 20 条评论
);

// 获取评论列表
$comments = get_comments( $args );

?>

<h1>评论管理面板</h1>

<form method="get">
  <label for="status">状态：</label>
  <select name="status" id="status">
    <?php foreach ( $comment_statuses as $status => $label ) : ?>
      <option value="<?php echo esc_attr( $status ); ?>" <?php selected( $current_status, $status ); ?>><?php echo esc_html( $label ); ?></option>
    <?php endforeach; ?>
  </select>
  <input type="submit" value="筛选">
</form>

<?php if ( $comments ) : ?>
  <table>
    <thead>
      <tr>
        <th>作者</th>
        <th>内容</th>
        <th>日期</th>
      </tr>
    </thead>
    <tbody>
      <?php foreach ( $comments as $comment ) : ?>
        <tr>
          <td><?php echo esc_html( get_comment_author( $comment->comment_ID ) ); ?></td>
          <td><?php echo esc_html( get_comment_text( $comment->comment_ID ) ); ?></td>
          <td><?php echo esc_html( get_comment_date( 'Y-m-d H:i:s', $comment->comment_ID ) ); ?></td>
        </tr>
      <?php endforeach; ?>
    </tbody>
  </table>
<?php else : ?>
  <p>没有找到评论。</p>
<?php endif; ?>

这段代码首先定义了一个包含所有评论状态的数组，然后根据用户选择的评论状态构建查询参数，最后使用 get_comments() 函数获取评论列表，并将其显示在一个简单的表格中。

7. 总结

今天，我们深入剖析了 WordPress get_comments() 函数和 WP_Comment_Query 类的运作机制。我们了解了 get_comments() 函数如何将参数传递给 WP_Comment_Query 类，以及 WP_Comment_Query 类如何构建 SQL 查询语句、执行查询和处理查询结果。我们还学习了 WP_Comment_Query 类的各种参数和高级用法，并通过一个实战案例巩固了所学知识。

希望今天的讲座对大家有所帮助！记住，掌握这些知识可以让你更好地理解 WordPress 的运作机制，并能够更灵活地定制你的 WordPress 网站。下次再见！

WordPress 评论查询的秘密：get_comments() 和 WP_Comment_Query 的深度剖析

1. get_comments()：评论查询的入口

2. get_comments() 的内部运作

3. WP_Comment_Query：评论查询的核心引擎

3.1 WP_Comment_Query 的构造函数 __construct()

3.2 WP_Comment_Query 的重要属性

3.3 WP_Comment_Query 的重要方法

4. WP_Comment_Query 的参数详解

5. WP_Comment_Query 的高级用法

5.1 date_query 参数

5.2 meta_query 参数