云策 WordPress 开发者社区

函数文档

wp_insert_comment()

查看官方原文 ↗
💡 云策文档标注

概述

wp_insert_comment() 函数用于向 WordPress 数据库插入新评论，接受一个包含评论数据的数组参数，并返回新评论的 ID 或失败时返回 false。该函数处理评论的默认值、元数据存储，并在插入后触发相关 Hook。

关键要点

  • 参数 $commentdata 为必需数组，包含评论作者、内容、日期、类型等字段，每个字段有默认值。
  • 函数返回 int|false，成功时返回新评论 ID，失败时返回 false。
  • 支持可选 comment_meta 参数，用于存储评论的元数据。
  • 插入后触发 wp_insert_comment Hook，并更新评论计数和缓存。
  • 注意 $comment_type 参数长度不能超过 20 个字符。

代码示例

function ic_wp_insert_comment( $field, $postId ) {
    $current_user = wp_get_current_user();

    if ( comments_open( $postId ) ) {
        $data = array(
            'comment_post_ID'      => $postId,
            'comment_content'      => $field['comment'],
            'comment_parent'       => $field['comment_parent'],
            'user_id'              => $current_user->ID,
            'comment_author'       => $current_user->user_login,
            'comment_author_email' => $current_user->user_email,
            'comment_author_url'   => $current_user->user_url,
            'comment_meta'         => array(
                'property_district' => $field['property_district'],
                'property_estate'   => $field['property_estate'],
                'custom_tag'       => $field['custom_tag'],
            )
        );

        $comment_id = wp_insert_comment( $data );
        if ( ! is_wp_error( $comment_id ) ) {
            return $comment_id;
        }
    }

    return false;
}

注意事项

  • 手动设置 comment_date 时，必须同时指定 comment_date_gmt。
  • $comment_type 参数默认值为 'comment'，且长度限制为 20 个字符。
  • 函数内部使用 wp_unslash() 处理数据，并调用 wpdb::insert() 插入数据库。
📄 原文内容

Inserts a comment into the database.

Parameters

$commentdataarrayrequired
Array of arguments for inserting a new comment.

  • comment_agent string
    The HTTP user agent of the $comment_author when the comment was submitted. Default empty.
  • comment_approved int|string
    Whether the comment has been approved. Default 1.
  • comment_author string
    The name of the author of the comment. Default empty.
  • comment_author_email string
    The email address of the $comment_author. Default empty.
  • comment_author_IP string
    The IP address of the $comment_author. Default empty.
  • comment_author_url string
    The URL address of the $comment_author. Default empty.
  • comment_content string
    The content of the comment. Default empty.
  • comment_date string
    The date the comment was submitted. To set the date manually, $comment_date_gmt must also be specified.
    Default is the current time.
  • comment_date_gmt string
    The date the comment was submitted in the GMT timezone.
    Default is $comment_date in the site’s GMT timezone.
  • comment_karma int
    The karma of the comment. Default 0.
  • comment_parent int
    ID of this comment’s parent, if any. Default 0.
  • comment_post_ID int
    ID of the post that relates to the comment, if any.
    Default 0.
  • comment_type string
    Comment type. Default 'comment'.
  • comment_meta array
    Optional. Array of key/value pairs to be stored in commentmeta for the new comment.
  • user_id int
    ID of the user who submitted the comment. Default 0.

Return

int|false The new comment’s ID on success, false on failure.

Source

function wp_insert_comment( $commentdata ) {
	global $wpdb;

	$data = wp_unslash( $commentdata );

	$comment_author       = ! isset( $data['comment_author'] ) ? '' : $data['comment_author'];
	$comment_author_email = ! isset( $data['comment_author_email'] ) ? '' : $data['comment_author_email'];
	$comment_author_url   = ! isset( $data['comment_author_url'] ) ? '' : $data['comment_author_url'];
	$comment_author_ip    = ! isset( $data['comment_author_IP'] ) ? '' : $data['comment_author_IP'];

	$comment_date     = ! isset( $data['comment_date'] ) ? current_time( 'mysql' ) : $data['comment_date'];
	$comment_date_gmt = ! isset( $data['comment_date_gmt'] ) ? get_gmt_from_date( $comment_date ) : $data['comment_date_gmt'];

	$comment_post_id  = ! isset( $data['comment_post_ID'] ) ? 0 : $data['comment_post_ID'];
	$comment_content  = ! isset( $data['comment_content'] ) ? '' : $data['comment_content'];
	$comment_karma    = ! isset( $data['comment_karma'] ) ? 0 : $data['comment_karma'];
	$comment_approved = ! isset( $data['comment_approved'] ) ? 1 : $data['comment_approved'];
	$comment_agent    = ! isset( $data['comment_agent'] ) ? '' : $data['comment_agent'];
	$comment_type     = empty( $data['comment_type'] ) ? 'comment' : $data['comment_type'];
	$comment_parent   = ! isset( $data['comment_parent'] ) ? 0 : $data['comment_parent'];

	$user_id = ! isset( $data['user_id'] ) ? 0 : $data['user_id'];

	$compacted = array(
		'comment_post_ID'   => $comment_post_id,
		'comment_author_IP' => $comment_author_ip,
	);

	$compacted += compact(
		'comment_author',
		'comment_author_email',
		'comment_author_url',
		'comment_date',
		'comment_date_gmt',
		'comment_content',
		'comment_karma',
		'comment_approved',
		'comment_agent',
		'comment_type',
		'comment_parent',
		'user_id'
	);

	if ( ! $wpdb->insert( $wpdb->comments, $compacted ) ) {
		return false;
	}

	$id = (int) $wpdb->insert_id;

	if ( 1 === (int) $comment_approved ) {
		wp_update_comment_count( $comment_post_id );

		$data = array();
		foreach ( array( 'server', 'gmt', 'blog' ) as $timezone ) {
			$data[] = "lastcommentmodified:$timezone";
		}
		wp_cache_delete_multiple( $data, 'timeinfo' );
	}

	clean_comment_cache( $id );

	$comment = get_comment( $id );

	// If metadata is provided, store it.
	if ( isset( $commentdata['comment_meta'] ) && is_array( $commentdata['comment_meta'] ) ) {
		foreach ( $commentdata['comment_meta'] as $meta_key => $meta_value ) {
			add_comment_meta( $comment->comment_ID, $meta_key, $meta_value, true );
		}
	}

	/**
	 * Fires immediately after a comment is inserted into the database.
	 *
	 * @since 2.8.0
	 *
	 * @param int        $id      The comment ID.
	 * @param WP_Comment $comment Comment object.
	 */
	do_action( 'wp_insert_comment', $id, $comment );

	return $id;
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘wp_insert_comment’, int $id, WP_Comment $comment )

Fires immediately after a comment is inserted into the database.

Uses Description
wp_cache_delete_multiple()wp-includes/cache.php

Deletes multiple values from the cache in one call.
get_gmt_from_date()wp-includes/formatting.php

Given a date in the timezone of the site, returns that date in UTC.
current_time()wp-includes/functions.php

Retrieves the current time based on specified type.
wpdb::insert()wp-includes/class-wpdb.php

Inserts a row into the table.
clean_comment_cache()wp-includes/comment.php

Removes a comment from the object cache.
wp_update_comment_count()wp-includes/comment.php

Updates the comment count for post(s).
add_comment_meta()wp-includes/comment.php

Adds meta data field to a comment.
wp_unslash()wp-includes/formatting.php

Removes slashes from a string or recursively removes slashes from strings within an array.
do_action()wp-includes/plugin.php

Calls the callback functions that have been added to an action hook.
get_comment()wp-includes/comment.php

Retrieves comment data given a comment ID or comment object.

Show 5 moreShow less

Used by Description
WP_REST_Comments_Controller::create_item()wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php

Creates a comment.
wp_new_comment()wp-includes/comment.php

Adds a new comment to the database.

Changelog

Version Description
5.5.0 Default value for $comment_type argument changed to comment.
4.4.0 Introduced the $comment_meta argument.
2.0.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Mehedi Foysal


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    function ic_wp_insert_comment( $field, $postId ) {
    $current_user = wp_get_current_user();

    if ( comments_open( $postId ) ) {
        $data = array(
            'comment_post_ID'      => $postId,
            'comment_content'      => $field['comment'],
            'comment_parent'       => $field['comment_parent'],
            'user_id'              => $current_user->ID,
            'comment_author'       => $current_user->user_login,
            'comment_author_email' => $current_user->user_email,
            'comment_author_url'   => $current_user->user_url,
            'comment_meta'         => array(
                'property_district' => $field['property_district'],
                'property_estate'   => $field['property_estate'],
                'custom_tag'       => $field['custom_tag'],
            )
        );

        $comment_id = wp_insert_comment( $data );
        if ( ! is_wp_error( $comment_id ) ) {
            return $comment_id;
        }
    }

    return false;
}