发布于 由admin

剖析 `wp_insert_comment()` 函数的源码，它如何处理评论的插入和相关的 `meta` 数据？

好的，各位观众老爷们，让咱们今天来扒一扒 WordPress 里面那个神秘的 wp_insert_comment() 函数的底裤，看看它是怎么把一条条评论塞进数据库，并且给它们贴上各种各样的“标签”（也就是评论的 meta 数据）的。准备好了吗？咱们这就开整！

1. 欢迎来到评论的世界

wp_insert_comment() 函数，顾名思义，就是用来插入评论的。它可不是一个简单的“插入”动作，它背后涉及了各种数据校验、过滤、钩子调用，以及与评论 meta 数据的交互。咱们一步一步来，把它给拆解了。

2. 函数签名与参数

首先，让我们看看 wp_insert_comment() 的函数签名：

/**
 * Inserts a comment into the database.
 *
 * @since 2.0.0
 *
 * @param array|object $commentarr Comment data. Must pass comment author name, email, and content.
 * @param bool         $wp_error   Optional. Whether to return a WP_Error object on failure. Default false.
 * @return int|WP_Error The comment ID on success. WP_Error on failure, if $wp_error is true. 0 on failure, if $wp_error is false.
 */
function wp_insert_comment( $commentarr = array(), $wp_error = false ) {
  // 函数体
}

简单来说，它接收两个参数：

  • $commentarr：一个数组或对象，包含了评论的各种信息，比如作者、邮箱、内容等等。这是最重要的参数。
  • $wp_error：一个布尔值，决定了如果插入失败，是返回 WP_Error 对象还是返回 0。

返回值：

  • 成功：返回新插入评论的 ID。
  • 失败：根据 $wp_error 的值，返回 WP_Error 对象或 0。

3. 数据预处理：洗干净才能下锅

在真正插入评论之前，wp_insert_comment() 会对传入的 $commentarr 进行一系列的预处理，确保数据的安全性、完整性和正确性。

  1. 类型转换： 如果 $commentarr 是一个对象，会把它转换成数组。

    if ( is_object( $commentarr ) ) {
  $commentarr = get_object_vars( $commentarr );
}

  2. 数据过滤： 使用 wp_filter_comment() 函数对评论内容进行过滤，防止 XSS 攻击。

    $commentarr['comment_content'] = wp_filter_comment( $commentarr['comment_content'] );

  3. 数据填充： 如果某些字段缺失，会尝试填充默认值。比如，如果 comment_date 字段为空，会使用当前时间。

    if ( empty( $commentarr['comment_date'] ) ) {
  $commentarr['comment_date'] = current_time( 'mysql' );
}

  4. 反垃圾邮件检查： 如果启用了反垃圾邮件功能（比如 Akismet），会调用相关函数进行检查。

  5. 钩子调用： 预处理过程中，会触发一些钩子，允许开发者自定义行为。

    • preprocess_comment：在评论数据被处理之前触发。

4. 数据校验：不合格的评论，滚粗！

预处理之后，wp_insert_comment() 会对评论数据进行严格的校验，确保满足最低要求。

  1. 必填字段检查： 检查 comment_author、comment_author_email 和 comment_content 这三个字段是否都存在且不为空。

    if ( empty( $commentarr['comment_author'] ) || empty( $commentarr['comment_author_email'] ) || empty( $commentarr['comment_content'] ) ) {
  return new WP_Error( 'comment_empty', __( 'Comment author name, email address, and comment text are required.' ) );
}

  2. 邮箱格式校验： 使用 is_email() 函数检查 comment_author_email 字段是否是一个有效的邮箱地址。

    if ( ! is_email( $commentarr['comment_author_email'] ) ) {
  return new WP_Error( 'comment_invalid_email', __( 'Comment author email address is invalid.' ) );
}

  3. 黑名单检查： 检查评论作者的 IP 地址和邮箱地址是否在黑名单中。

    $is_blacklisted = wp_blacklist_check( $commentarr['comment_author'], $commentarr['comment_author_email'], $commentarr['comment_author_url'], $commentarr['comment_author_IP'], $commentarr['comment_agent'] );

if ( $is_blacklisted ) {
  return new WP_Error( 'comment_blacklisted', __( 'Your comment has been blacklisted.' ) );
}

如果任何一个校验失败，wp_insert_comment() 会返回一个 WP_Error 对象（如果 $wp_error 为 true）或 0（如果 $wp_error 为 false），表示插入失败。

5. 插入评论：终于要进数据库了！

经过层层筛选和校验，合格的评论终于可以进入数据库了。

  1. 数据准备： 将评论数据转换成适合数据库查询的格式。

    $data = wp_unslash( $commentarr ); // 去掉反斜杠
$data = wp_array_slice_assoc( $data, array(
  'comment_post_ID',
  'comment_author',
  'comment_author_email',
  'comment_author_url',
  'comment_author_IP',
  'comment_date',
  'comment_date_gmt',
  'comment_content',
  'comment_karma',
  'comment_approved',
  'comment_agent',
  'comment_type',
  'comment_parent',
  'user_id',
) );
$data = wp_filter_kses( $data ); // 进行 HTML 过滤
$format = array(
  '%d',
  '%s',
  '%s',
  '%s',
  '%s',
  '%s',
  '%s',
  '%s',
  '%d',
  '%s',
  '%s',
  '%s',
  '%d',
  '%d',
);

  2. 数据库操作： 使用 $wpdb->insert() 方法将评论数据插入 wp_comments 表。

    $wpdb->insert( $wpdb->comments, $data, $format );
$comment_id = $wpdb->insert_id;

  3. 更新文章评论计数： 如果评论被批准，需要更新文章的评论计数。

    if ( 1 === (int) $data['comment_approved'] ) {
  wp_update_comment_count_now( $data['comment_post_ID'] );
}

  4. 缓存清理： 清理与该文章相关的缓存，确保显示最新的评论数据。

    clean_comment_cache( $comment_id );
wp_cache_delete( $data['comment_post_ID'], 'get_page_children' );

6. 评论 Meta 数据：给评论贴标签

评论 Meta 数据允许我们为评论添加额外的、自定义的信息。比如，我们可以用 Meta 数据来存储评论的评分、用户投票等等。wp_insert_comment() 函数本身并不直接处理评论 Meta 数据，但是它提供了钩子，允许开发者在评论插入前后添加 Meta 数据。

  1. 钩子：

    • comment_post：在评论插入之后，但在 Meta 数据处理之前触发。
    • wp_insert_comment：在评论插入和 Meta 数据处理完成之后触发。

  2. 使用 add_comment_meta() 函数：

    我们可以使用 add_comment_meta() 函数来为评论添加 Meta 数据。

    add_comment_meta( $comment_id, $meta_key, $meta_value, $unique );
    • $comment_id：评论 ID。
    • $meta_key：Meta 数据的键名。
    • $meta_value：Meta 数据的值。
    • $unique：是否允许同一个评论拥有多个相同键名的 Meta 数据。

示例：

假设我们想在评论插入后，为它添加一个评分的 Meta 数据。

add_action( 'comment_post', 'my_add_comment_rating', 10, 2 );

function my_add_comment_rating( $comment_id, $comment_approved ) {
  if ( isset( $_POST['comment_rating'] ) ) {
    $rating = intval( $_POST['comment_rating'] );
    add_comment_meta( $comment_id, 'comment_rating', $rating, true );
  }
}

在这个例子中：

  • 我们使用了 comment_post 钩子，在评论插入之后触发 my_add_comment_rating() 函数。
  • my_add_comment_rating() 函数首先检查 $_POST 数组中是否存在 comment_rating 字段。
  • 如果存在，就将它的值转换成整数，并使用 add_comment_meta() 函数将它作为 comment_rating 的 Meta 数据添加到评论中。
  • $unique 参数设置为 true，表示同一个评论只能有一个 comment_rating 的 Meta 数据。

7. 错误处理：出错咱也得知道

wp_insert_comment() 函数在插入过程中，如果遇到错误，会返回一个 WP_Error 对象（如果 $wp_error 为 true）或 0（如果 $wp_error 为 false）。

示例：

$commentdata = array(
  'comment_post_ID' => 1,
  'comment_author' => 'John Doe',
  'comment_author_email' => 'invalid-email', // 故意设置一个无效的邮箱
  'comment_content' => 'This is a test comment.',
);

$comment_id = wp_insert_comment( $commentdata, true ); // 开启错误返回

if ( is_wp_error( $comment_id ) ) {
  echo 'Error: ' . $comment_id->get_error_message();
} else {
  echo 'Comment inserted with ID: ' . $comment_id;
}

在这个例子中，由于 comment_author_email 是一个无效的邮箱地址，wp_insert_comment() 函数会返回一个 WP_Error 对象。我们可以使用 is_wp_error() 函数来判断是否发生了错误，并使用 $comment_id->get_error_message() 方法来获取错误信息。

8. 总结：评论插入的完整流程

为了方便大家理解，我把 wp_insert_comment() 函数的完整流程用一个表格总结一下：

步骤 描述 涉及的关键函数/钩子
1. 数据预处理 将传入的 $commentarr 进行类型转换、过滤、填充等处理，确保数据的安全性、完整性和正确性。 wp_filter_comment(), preprocess_comment
2. 数据校验 对评论数据进行严格的校验，确保满足最低要求，比如必填字段检查、邮箱格式校验、黑名单检查等。 is_email(), wp_blacklist_check()
3. 插入评论 将评论数据插入 wp_comments 表。 $wpdb->insert(), wp_update_comment_count_now(), clean_comment_cache()
4. 处理 Meta 数据 使用钩子和 add_comment_meta() 函数为评论添加额外的、自定义的信息。 comment_post, wp_insert_comment, add_comment_meta()
5. 错误处理 如果插入过程中遇到错误，返回一个 WP_Error 对象或 0。 is_wp_error(), $wp_error->get_error_message()

9. 拓展：一些高级用法

  • 自定义评论类型： WordPress 允许我们创建自定义的评论类型，比如“回复”、“引用”等等。我们可以通过设置 comment_type 字段来实现。
  • 审核评论： 我们可以使用 wp_set_comment_status() 函数来审核评论，批准或拒绝它们。
  • 修改评论： 我们可以使用 wp_update_comment() 函数来修改已存在的评论。

10. 注意事项：写代码可不能马虎

  • 安全性： 永远要对用户输入的数据进行过滤和校验，防止 XSS 攻击和 SQL 注入。
  • 性能： 尽量避免在 comment_post 钩子中执行耗时的操作，以免影响评论插入的速度。
  • 兼容性： 如果你的代码需要在不同的 WordPress 版本上运行，要注意兼容性问题。

好了，各位观众老爷们，今天的 wp_insert_comment() 函数源码剖析就到这里了。希望通过这次深入的讲解，大家能够对 WordPress 评论插入的机制有一个更清晰的认识。记住，理解源码是成为 WordPress 大神的必经之路！下次再见！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注