分析 WordPress `wp_insert_comment()` 函数的源码：它如何处理评论数据，并触发相关钩子。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

各位代码爱好者，大家好！我是今天的主讲人，很高兴能和大家一起扒一扒 WordPress 里一个非常重要的函数——wp_insert_comment()。别担心，今天的讲座不会像念经一样枯燥，我会尽量用大家能听懂的方式，把这个函数的里里外外、前前后后，都给您安排得明明白白。

开场白：评论，网站的灵魂伴侣

咱们先聊两句闲篇儿。评论，对于一个网站来说，就像灵魂伴侣一样重要。它能让网站不再是单向的信息输出，而是变成一个充满互动和活力的社区。 WordPress 作为强大的 CMS，自然也把评论功能安排得妥妥当当的。而 wp_insert_comment()，就是幕后英雄，负责把用户输入的评论数据，安全又高效地塞进数据库里。

正文：wp_insert_comment() 函数详解

好，废话不多说，咱们直接进入主题，开始剖析 wp_insert_comment() 这个函数。

1. 函数签名与参数

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

function wp_insert_comment( $commentdata ) {
  // 函数体
}

这个函数接受一个参数 $commentdata，这是一个数组，包含了评论的所有信息。比如：

键名	描述	数据类型
`comment_post_ID`	评论所属的文章 ID	整数
`comment_author`	评论作者姓名	字符串
`comment_author_email`	评论作者邮箱	字符串
`comment_author_url`	评论作者网址	字符串
`comment_content`	评论内容	字符串
`comment_type`	评论类型 (comment, trackback, pingback 等)	字符串
`comment_parent`	父评论 ID (如果是回复评论)	整数
`comment_date`	评论日期 (默认为当前时间)	字符串
`comment_date_gmt`	评论日期 (GMT 时间，默认为当前时间)	字符串
`comment_author_IP`	评论作者 IP 地址	字符串
`comment_agent`	评论作者 User Agent	字符串
`comment_approved`	评论是否已批准 (0 表示未批准，1 表示已批准，’spam’ 表示垃圾评论)	整数/字符串

2. 数据预处理与验证

拿到 $commentdata 之后，wp_insert_comment() 并不会直接一股脑地塞进数据库，而是会先进行一系列的预处理和验证，确保数据的安全性和完整性。让我们看看它都做了哪些事情：

wp_filter_comment()： 这个函数会对评论内容进行过滤，防止 XSS 攻击。简单来说，就是把评论内容里的恶意代码给过滤掉。

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

wp_kses_post()： 这个函数会对评论内容进行更严格的过滤，只允许使用 WordPress 允许的 HTML 标签和属性。

$commentdata['comment_content'] = wp_kses_post( $commentdata['comment_content'] );

检查 required 字段： 会检查 comment_author, comment_author_email, comment_content 这些必要的字段是否为空。如果为空，直接返回错误。

if ( empty( $commentdata['comment_author'] ) ) {
  return new WP_Error( 'comment_author_required', __( 'Author name is required.' ) );
}

// 类似的，检查 email 和 content

验证邮箱格式： 使用 is_email() 函数验证邮箱格式是否正确。

if ( ! is_email( $commentdata['comment_author_email'] ) ) {
  return new WP_Error( 'comment_author_email_invalid', __( 'Author email is invalid.' ) );
}

apply_filters( 'preprocess_comment', $commentdata )： 这是一个非常重要的钩子。允许开发者在评论数据被插入数据库之前，对数据进行自定义处理。比如，你可以使用这个钩子来屏蔽某些敏感词，或者对评论内容进行格式化。

$commentdata = apply_filters( 'preprocess_comment', $commentdata );

3. 构建评论对象

经过一系列的预处理和验证，wp_insert_comment() 终于可以开始构建评论对象了。它会把 $commentdata 数组里的数据，赋值给一个 stdClass 对象，然后把这个对象转换成 WP_Comment 对象。

$comment = new stdClass();
foreach ( $commentdata as $key => $value ) {
  $comment->$key = $value;
}

$comment = new WP_Comment( $comment );

4. 插入数据库

接下来，wp_insert_comment() 会使用 $wpdb 对象，把评论数据插入到 wp_comments 表中。

global $wpdb;

$data = array(
  'comment_post_ID'      => $comment->comment_post_ID,
  'comment_author'       => $comment->comment_author,
  'comment_author_email' => $comment->comment_author_email,
  'comment_author_url'   => $comment->comment_author_url,
  'comment_author_IP'    => $comment->comment_author_IP,
  'comment_date'         => $comment->comment_date,
  'comment_date_gmt'     => $comment->comment_date_gmt,
  'comment_content'      => $comment->comment_content,
  'comment_karma'        => $comment->comment_karma,
  'comment_approved'     => $comment->comment_approved,
  'comment_agent'        => $comment->comment_agent,
  'comment_type'         => $comment->comment_type,
  'comment_parent'       => $comment->comment_parent,
  'user_id'              => $comment->user_id,
);

$format = array(
  '%d',
  '%s',
  '%s',
  '%s',
  '%s',
  '%s',
  '%s',
  '%s',
  '%d',
  '%s',
  '%s',
  '%s',
  '%d',
  '%d',
);

$wpdb->insert( $wpdb->comments, $data, $format );
$comment_id = $wpdb->insert_id; // 获取插入的评论 ID

5. 更新缓存

评论插入数据库之后，wp_insert_comment() 还会更新缓存，确保下次访问的时候，能快速获取到最新的评论数据。

wp_cache_delete( $comment->comment_post_ID, 'get_comments' );

6. 触发钩子

wp_insert_comment() 函数的重头戏来了！插入评论之后，它会触发一系列的钩子，允许开发者对评论进行各种各样的操作。这些钩子就像一个个的“触发器”，当评论插入数据库之后，就会被自动激活。

wp_insert_comment (action): 在评论插入数据库之后立即触发。

do_action( 'wp_insert_comment', $comment_id, $comment );

comment_post (action): 在评论成功提交之后触发。

do_action( 'comment_post', $comment->comment_post_ID, $comment->comment_approved, $comment_id );

transition_comment_status (action): 当评论状态改变时触发（例如，从待审核变为已批准）。

do_action( 'transition_comment_status', $comment->comment_approved, 'hold', $comment );

这些钩子非常强大，你可以利用它们来实现各种各样的功能，比如：

发送邮件通知管理员，有新的评论需要审核。
自动将评论分享到社交媒体。
给评论打分。
等等。

7. 返回值

wp_insert_comment() 函数会返回评论的 ID。如果插入失败，则返回 0 或者一个 WP_Error 对象。

完整流程图

为了让大家更清晰地了解 wp_insert_comment() 函数的执行流程，我画了一个简单的流程图：

graph TD
    A[开始] --> B{接收 $commentdata};
    B --> C{数据预处理和验证};
    C --> D{构建评论对象};
    D --> E{插入数据库};
    E --> F{更新缓存};
    F --> G{触发钩子};
    G --> H[返回评论 ID];

钩子详解

咱们重点说说 wp_insert_comment() 函数触发的几个重要钩子。

preprocess_comment (filter):

作用： 允许在评论数据插入数据库之前，对数据进行自定义处理。
参数： $commentdata (array) – 包含评论数据的数组。
返回值： 修改后的 $commentdata 数组。
示例： 屏蔽评论中的敏感词。

add_filter( 'preprocess_comment', 'my_preprocess_comment' );

function my_preprocess_comment( $commentdata ) {
  $banned_words = array( 'badword1', 'badword2' );
  $commentdata['comment_content'] = str_replace( $banned_words, '***', $commentdata['comment_content'] );
  return $commentdata;
}

wp_insert_comment (action):

作用： 在评论插入数据库之后立即触发。
参数： $comment_id (int) – 新插入的评论 ID, $comment (WP_Comment object) – 评论对象。
返回值： 无。
示例： 发送邮件通知管理员。

add_action( 'wp_insert_comment', 'my_wp_insert_comment', 10, 2 );

function my_wp_insert_comment( $comment_id, $comment ) {
  $to = '[email protected]';
  $subject = 'New comment on your site!';
  $message = 'A new comment has been submitted on your site.  Check it out!';
  wp_mail( $to, $subject, $message );
}

comment_post (action):

作用： 在评论成功提交之后触发。
参数： $comment_post_ID (int) – 评论所属的文章 ID, $comment_approved (string) – 评论是否已批准, $comment_id (int) – 评论 ID。
返回值： 无。
示例： 将评论分享到社交媒体。

add_action( 'comment_post', 'my_comment_post', 10, 3 );

function my_comment_post( $comment_post_ID, $comment_approved, $comment_id ) {
  if ( $comment_approved == 1 ) { // Only share approved comments
    $comment = get_comment( $comment_id );
    $post_title = get_the_title( $comment_post_ID );
    $share_url = 'https://twitter.com/intent/tweet?text=' . urlencode( 'New comment on ' . $post_title . ': ' . $comment->comment_content );
    // Redirect to Twitter or use JS to open a new window
    wp_redirect( $share_url );
    exit;
  }
}

transition_comment_status (action):

作用： 当评论状态改变时触发。
参数： $new_status (string) – 新的状态, $old_status (string) – 旧的状态, $comment (WP_Comment object) – 评论对象。
返回值： 无。
示例： 当评论从待审核变为已批准时，发送邮件通知评论作者。

add_action( 'transition_comment_status', 'my_transition_comment_status', 10, 3 );

function my_transition_comment_status( $new_status, $old_status, $comment ) {
  if ( $new_status == 'approved' && $old_status == 'hold' ) {
    $to = $comment->comment_author_email;
    $subject = 'Your comment has been approved!';
    $message = 'Your comment on ' . get_the_title( $comment->comment_post_ID ) . ' has been approved.';
    wp_mail( $to, $subject, $message );
  }
}

安全注意事项

在使用 wp_insert_comment() 函数的时候，一定要注意安全问题。特别是，要对用户输入的数据进行严格的验证和过滤，防止 XSS 攻击和 SQL 注入。 WordPress 已经提供了很多安全相关的函数，比如 wp_filter_comment(), wp_kses_post(), esc_sql() 等，一定要善加利用。

总结

好了，今天的 wp_insert_comment() 函数源码剖析就到这里了。希望通过今天的讲解，大家对这个函数的理解更上一层楼。记住，wp_insert_comment() 不仅仅是一个简单的数据库插入函数，它还承载着 WordPress 强大的评论系统和丰富的可扩展性。掌握了它，你就能更好地控制和定制你的 WordPress 网站的评论功能。

下次再见！

发表回复 取消回复

发表回复取消回复