[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)




/wp-includes/ -> comment.php (summary)

Core Comment API

File Size: 3514 lines (113 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 2 files

Defines 65 functions


Functions that are not part of a class:

check_comment( $author, $email, $url, $comment, $user_ip, $user_agent, $comment_type )   X-Ref
Check whether a comment passes internal checks to be allowed to add.

If manual comment moderation is set in the administration, then all checks,
regardless of their type and whitelist, will fail and the function will
return false.

If the number of links exceeds the amount in the administration, then the
check fails. If any of the parameter contents match the blacklist of words,
then the check fails.

If the comment author was approved before, then the comment is automatically

If all checks pass, the function will return true.

return: bool If all checks pass, true, otherwise false.
param: string $author       Comment author name.
param: string $email        Comment author email.
param: string $url          Comment author URL.
param: string $comment      Content of the comment.
param: string $user_ip      Comment author IP address.
param: string $user_agent   Comment author User-Agent.
param: string $comment_type Comment type, either user-submitted comment,

get_approved_comments( $post_id, $args = array()   X-Ref
Retrieve the approved comments for post $post_id.

return: int|array $comments The approved comments, or number of comments if `$count`
param: int   $post_id The ID of the post.
param: array $args    Optional. See WP_Comment_Query::__construct() for information on accepted arguments.

get_comment( &$comment = null, $output = OBJECT )   X-Ref
Retrieves comment data given a comment ID or comment object.

If an object is passed then the comment data will be cached and then returned
after being passed through a filter. If the comment is empty, then the global
comment variable will be used, if it is set.

return: WP_Comment|array|null Depends on $output value.
param: WP_Comment|string|int $comment Comment to retrieve.
param: string                $output  Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to

get_comments( $args = '' )   X-Ref
Retrieve a list of comments.

The comment list can be for the blog as a whole or for an individual post.

return: int|array List of comments or number of found comments if `$count` argument is true.
param: string|array $args Optional. Array or string of arguments. See WP_Comment_Query::__construct()

get_comment_statuses()   X-Ref
Retrieve all of the WordPress supported comment statuses.

Comments have a limited set of valid status values, this provides the comment
status values and descriptions.

return: array List of comment statuses.

get_default_comment_status( $post_type = 'post', $comment_type = 'comment' )   X-Ref
Gets the default comment status for a post type.

return: string Expected return value is 'open' or 'closed'.
param: string $post_type    Optional. Post type. Default 'post'.
param: string $comment_type Optional. Comment type. Default 'comment'.

get_lastcommentmodified( $timezone = 'server' )   X-Ref
The date the last comment was modified.

return: string|false Last comment modified date on success, false on failure.
param: string $timezone Which timezone to use in reference to 'gmt', 'blog', or 'server' locations.

get_comment_count( $post_id = 0 )   X-Ref
The amount of comments in a post or total comments.

A lot like wp_count_comments(), in that they both return comment stats (albeit with different types).
The wp_count_comments() actually caches, but this function does not.

return: array The amount of spam, approved, awaiting moderation, and total comments.
param: int $post_id Optional. Comment amount in post if > 0, else total comments blog wide.

add_comment_meta( $comment_id, $meta_key, $meta_value, $unique = false )   X-Ref
Add meta data field to a comment.

return: int|bool Meta ID on success, false on failure.
param: int $comment_id Comment ID.
param: string $meta_key Metadata name.
param: mixed $meta_value Metadata value.
param: bool $unique Optional, default is false. Whether the same key should not be added.

delete_comment_meta( $comment_id, $meta_key, $meta_value = '' )   X-Ref
Remove metadata matching criteria from a comment.

You can match based on the key, or key and value. Removing based on key and
value, will keep from removing duplicate metadata with the same key. It also
allows removing all metadata matching key, if needed.

return: bool True on success, false on failure.
param: int $comment_id comment ID
param: string $meta_key Metadata name.
param: mixed $meta_value Optional. Metadata value.

get_comment_meta( $comment_id, $key = '', $single = false )   X-Ref
Retrieve comment meta field for a comment.

return: mixed Will be an array if $single is false. Will be value of meta data field if $single
param: int $comment_id Comment ID.
param: string $key Optional. The meta key to retrieve. By default, returns data for all keys.
param: bool $single Whether to return a single value.

update_comment_meta( $comment_id, $meta_key, $meta_value, $prev_value = '' )   X-Ref
Update comment meta field based on comment ID.

Use the $prev_value parameter to differentiate between meta fields with the
same key and comment ID.

If the meta field for the comment does not exist, it will be added.

return: int|bool Meta ID if the key didn't exist, true on successful update, false on failure.
param: int $comment_id Comment ID.
param: string $meta_key Metadata key.
param: mixed $meta_value Metadata value.
param: mixed $prev_value Optional. Previous value to check before removing.

wp_queue_comments_for_comment_meta_lazyload( $comments )   X-Ref
Queues comments for metadata lazy-loading.

param: WP_Comment[] $comments Array of comment objects.

wp_set_comment_cookies( $comment, $user, $cookies_consent = true )   X-Ref
Sets the cookies used to store an unauthenticated commentator's identity. Typically used
to recall previous comments by this commentator that are still held in moderation.

param: WP_Comment $comment         Comment object.
param: WP_User    $user            Comment author's user object. The user may not exist.
param: boolean    $cookies_consent Optional. Comment author's consent to store cookies. Default true.

sanitize_comment_cookies()   X-Ref
Sanitizes the cookies sent to the user already.

Will only do anything if the cookies have already been created for the user.
Mostly used after cookies had been sent to use elsewhere.

wp_allow_comment( $commentdata, $avoid_die = false )   X-Ref
Validates whether this comment is allowed to be made.

return: int|string|WP_Error Allowed comments return the approval status (0|1|'spam').
param: array $commentdata Contains information on the comment.
param: bool  $avoid_die   When true, a disallowed comment will result in the function

check_comment_flood_db()   X-Ref
Hooks WP's native database-based comment-flood check.

This wrapper maintains backward compatibility with plugins that expect to
be able to unhook the legacy check_comment_flood_db() function from
'check_comment_flood' using remove_action().

wp_check_comment_flood( $is_flood, $ip, $email, $date, $avoid_die = false )   X-Ref
Checks whether comment flooding is occurring.

Won't run, if current user can manage options, so to not block

return: bool Whether comment flooding is occurring.
param: bool   $is_flood  Is a comment flooding occurring?
param: string $ip        Comment author's IP address.
param: string $email     Comment author's email address.
param: string $date      MySQL time string.
param: bool   $avoid_die When true, a disallowed comment will result in the function

separate_comments( &$comments )   X-Ref
Separates an array of comments into an array keyed by comment_type.

return: WP_Comment[] Array of comments keyed by comment_type.
param: WP_Comment[] $comments Array of comments

get_comment_pages_count( $comments = null, $per_page = null, $threaded = null )   X-Ref
Calculate the total number of comment pages.

return: int Number of comment pages.
param: WP_Comment[] $comments Optional. Array of WP_Comment objects. Defaults to $wp_query->comments.
param: int          $per_page Optional. Comments per page.
param: bool         $threaded Optional. Control over flat or threaded comments.

get_page_of_comment( $comment_ID, $args = array()   X-Ref
Calculate what page number a comment will appear on for comment paging.

return: int|null Comment page number or null on error.
param: int   $comment_ID Comment ID.
param: array $args {

wp_get_comment_fields_max_lengths()   X-Ref
Retrieves the maximum character lengths for the comment form fields.

return: array Maximum character length for the comment form fields.

wp_check_comment_data_max_lengths( $comment_data )   X-Ref
Compares the lengths of comment data against the maximum character limits.

return: WP_Error|true WP_Error when a comment field exceeds the limit,
param: array $comment_data Array of arguments for inserting a comment.

wp_blacklist_check( $author, $email, $url, $comment, $user_ip, $user_agent )   X-Ref
Does comment contain blacklisted characters or words.

return: bool True if comment contains blacklisted content, false if comment does not
param: string $author The author of the comment
param: string $email The email of the comment
param: string $url The url used in the comment
param: string $comment The comment content
param: string $user_ip The comment author's IP address
param: string $user_agent The author's browser user agent

wp_count_comments( $post_id = 0 )   X-Ref
Retrieve total comments for blog or single post.

The properties of the returned object contain the 'moderated', 'approved',
and spam comments for either the entire blog or single post. Those properties
contain the amount of comments that match the status. The 'total_comments'
property contains the integer of total comments.

The comment stats are cached and then retrieved, if they already exist in the

return: object|array Comment stats.
param: int $post_id Optional. Post ID.

wp_delete_comment( $comment_id, $force_delete = false )   X-Ref
Trashes or deletes a comment.

The comment is moved to trash instead of permanently deleted unless trash is
disabled, item is already in the trash, or $force_delete is true.

The post comment count will be updated if the comment was approved and has a
post ID available.

return: bool True on success, false on failure.
param: int|WP_Comment $comment_id   Comment ID or WP_Comment object.
param: bool           $force_delete Whether to bypass trash and force deletion. Default is false.

wp_trash_comment( $comment_id )   X-Ref
Moves a comment to the Trash

If trash is disabled, comment is permanently deleted.

return: bool True on success, false on failure.
param: int|WP_Comment $comment_id Comment ID or WP_Comment object.

wp_untrash_comment( $comment_id )   X-Ref
Removes a comment from the Trash

return: bool True on success, false on failure.
param: int|WP_Comment $comment_id Comment ID or WP_Comment object.

wp_spam_comment( $comment_id )   X-Ref
Marks a comment as Spam

return: bool True on success, false on failure.
param: int|WP_Comment $comment_id Comment ID or WP_Comment object.

wp_unspam_comment( $comment_id )   X-Ref
Removes a comment from the Spam

return: bool True on success, false on failure.
param: int|WP_Comment $comment_id Comment ID or WP_Comment object.

wp_get_comment_status( $comment_id )   X-Ref
The status of a comment by ID.

return: false|string Status might be 'trash', 'approved', 'unapproved', 'spam'. False on failure.
param: int|WP_Comment $comment_id Comment ID or WP_Comment object

wp_transition_comment_status( $new_status, $old_status, $comment )   X-Ref
Call hooks for when a comment status transition occurs.

Calls hooks for comment status transitions. If the new comment status is not the same
as the previous comment status, then two hooks will be ran, the first is
{@see 'transition_comment_status'} with new status, old status, and comment data. The
next action called is {@see comment_$old_status_to_$new_status'}. It has the
comment data.

The final action will run whether or not the comment statuses are the same. The
action is named {@see 'comment_$new_status_$comment->comment_type'}.

param: string $new_status New comment status.
param: string $old_status Previous comment status.
param: object $comment Comment data.

_clear_modified_cache_on_transition_comment_status( $new_status, $old_status )   X-Ref
Clear the lastcommentmodified cached value when a comment status is changed.

Deletes the lastcommentmodified cache key when a comment enters or leaves
'approved' status.

param: string $new_status The new comment status.
param: string $old_status The old comment status.

wp_get_current_commenter()   X-Ref
Get current commenter's name, email, and URL.

Expects cookies content to already be sanitized. User of this function might
wish to recheck the returned array for validity.

return: array Comment author, email, url respectively.

wp_insert_comment( $commentdata )   X-Ref
Inserts a comment into the database.

return: int|false The new comment's ID on success, false on failure.
param: array $commentdata {

wp_filter_comment( $commentdata )   X-Ref
Filters and sanitizes comment data.

Sets the comment data 'filtered' field to true when finished. This can be
checked as to whether the comment should be filtered and to keep from
filtering the same comment more than once.

return: array Parsed comment information.
param: array $commentdata Contains information on the comment.

wp_throttle_comment_flood( $block, $time_lastcomment, $time_newcomment )   X-Ref
Whether a comment should be blocked because of comment flood.

return: bool Whether comment should be blocked.
param: bool $block Whether plugin has already blocked comment.
param: int $time_lastcomment Timestamp for last comment.
param: int $time_newcomment Timestamp for new comment.

wp_new_comment( $commentdata, $avoid_die = false )   X-Ref
Adds a new comment to the database.

Filters new comment to ensure that the fields are sanitized and valid before
inserting comment into database. Calls {@see 'comment_post'} action with comment ID
and whether comment is approved by WordPress. Also has {@see 'preprocess_comment'}
filter for processing the comment data before the function handles it.

We use `REMOTE_ADDR` here directly. If you are behind a proxy, you should ensure
that it is properly set, such as in wp-config.php, for your environment.

See {@link https://core.trac.wordpress.org/ticket/9235}

return: int|false|WP_Error The ID of the comment on success, false or WP_Error on failure.
param: array $commentdata {
param: bool $avoid_die Should errors be returned as WP_Error objects instead of

wp_new_comment_notify_moderator( $comment_ID )   X-Ref
Send a comment moderation notification to the comment moderator.

return: bool True on success, false on failure.
param: int $comment_ID ID of the comment.

wp_new_comment_notify_postauthor( $comment_ID )   X-Ref
Send a notification of a new comment to the post author.

return: bool True on success, false on failure.
param: int $comment_ID Comment ID.

wp_set_comment_status( $comment_id, $comment_status, $wp_error = false )   X-Ref
Sets the status of a comment.

The {@see 'wp_set_comment_status'} action is called after the comment is handled.
If the comment status is not in the list, then false is returned.

return: bool|WP_Error True on success, false or WP_Error on failure.
param: int|WP_Comment $comment_id     Comment ID or WP_Comment object.
param: string         $comment_status New comment status, either 'hold', 'approve', 'spam', or 'trash'.
param: bool           $wp_error       Whether to return a WP_Error object if there is a failure. Default is false.

wp_update_comment( $commentarr )   X-Ref
Updates an existing comment in the database.

Filters the comment and makes sure certain fields are valid before updating.

return: int Comment was updated if value is 1, or was not updated if value is 0.
param: array $commentarr Contains information on the comment.

wp_defer_comment_counting( $defer = null )   X-Ref
Whether to defer comment counting.

When setting $defer to true, all post comment counts will not be updated
until $defer is set to false. When $defer is set to false, then all
previously deferred updated post comment counts will then be automatically
updated without having to call wp_update_comment_count() after.

return: bool
param: bool $defer

wp_update_comment_count( $post_id, $do_deferred = false )   X-Ref
Updates the comment count for post(s).

When $do_deferred is false (is by default) and the comments have been set to
be deferred, the post_id will be added to a queue, which will be updated at a
later date and only updated once per post ID.

If the comments have not be set up to be deferred, then the post will be
updated. When $do_deferred is set to true, then all previous deferred post
IDs will be updated along with the current $post_id.

return: bool|void True on success, false on failure or if post with ID does
param: int|null $post_id     Post ID.
param: bool     $do_deferred Optional. Whether to process previously deferred

wp_update_comment_count_now( $post_id )   X-Ref
Updates the comment count for the post.

return: bool True on success, false on '0' $post_id or if post with ID does not exist.
param: int $post_id Post ID

discover_pingback_server_uri( $url, $deprecated = '' )   X-Ref
Finds a pingback server URI based on the given URL.

Checks the HTML for the rel="pingback" link and x-pingback headers. It does
a check for the x-pingback headers first and returns that, if available. The
check for the rel="pingback" has more overhead than just the header.

return: false|string False on failure, string containing URI on success.
param: string $url URL to ping.
param: int $deprecated Not Used.

do_all_pings()   X-Ref
Perform all pingbacks, enclosures, trackbacks, and send to pingback services.

do_trackbacks( $post_id )   X-Ref
Perform trackbacks.

param: int|WP_Post $post_id Post object or ID to do trackbacks on.

generic_ping( $post_id = 0 )   X-Ref
Sends pings to all of the ping site services.

return: int Same as Post ID from parameter
param: int $post_id Post ID.

pingback( $content, $post_id )   X-Ref
Pings back the links found in a post.

param: string $content Post content to check for links. If empty will retrieve from post.
param: int|WP_Post $post_id Post Object or ID.

privacy_ping_filter( $sites )   X-Ref
Check whether blog is public before returning sites.

return: mixed Empty string if blog is not public, returns $sites, if site is public.
param: mixed $sites Will return if blog is public, will not return if not public.

trackback( $trackback_url, $title, $excerpt, $ID )   X-Ref
Send a Trackback.

Updates database when sending trackback to prevent duplicates.

return: int|false|void Database query from update.
param: string $trackback_url URL to send trackbacks.
param: string $title Title of post.
param: string $excerpt Excerpt of post.
param: int $ID Post ID.

weblog_ping( $server = '', $path = '' )   X-Ref
Send a pingback.

param: string $server Host of blog to connect to.
param: string $path Path to send the ping.

pingback_ping_source_uri( $source_uri )   X-Ref
Default filter attached to pingback_ping_source_uri to validate the pingback's Source URI

return: string
param: string $source_uri

xmlrpc_pingback_error( $ixr_error )   X-Ref
Default filter attached to xmlrpc_pingback_error.

Returns a generic pingback error code unless the error code is 48,
which reports that the pingback is already registered.

return: IXR_Error
param: IXR_Error $ixr_error

clean_comment_cache( $ids )   X-Ref
Removes a comment from the object cache.

param: int|array $ids Comment ID or an array of comment IDs to remove from cache.

update_comment_cache( $comments, $update_meta_cache = true )   X-Ref
Updates the comment cache of given comments.

Will add the comments in $comments to the cache. If comment ID already exists
in the comment cache then it will not be updated. The comment is added to the
cache using the comment group with the key using the ID of the comments.

param: WP_Comment[] $comments          Array of comment objects
param: bool         $update_meta_cache Whether to update commentmeta cache. Default true.

_prime_comment_caches( $comment_ids, $update_meta_cache = true )   X-Ref
Adds any comments from the given IDs to the cache that do not already exist in cache.

param: int[] $comment_ids       Array of comment IDs.
param: bool  $update_meta_cache Optional. Whether to update the meta cache. Default true.

_close_comments_for_old_posts( $posts, $query )   X-Ref
Close comments on old posts on the fly, without any extra DB queries. Hooked to the_posts.

return: array
param: WP_Post  $posts Post data object.
param: WP_Query $query Query object.

_close_comments_for_old_post( $open, $post_id )   X-Ref
Close comments on an old post. Hooked to comments_open and pings_open.

return: bool $open
param: bool $open Comments open or closed
param: int $post_id Post ID

wp_handle_comment_submission( $comment_data )   X-Ref
Handles the submission of a comment, usually posted to wp-comments-post.php via a comment form.

This function expects unslashed data, as opposed to functions such as `wp_new_comment()` which
expect slashed data.

return: WP_Comment|WP_Error A WP_Comment object on success, a WP_Error object on failure.
param: array $comment_data {

wp_register_comment_personal_data_exporter( $exporters )   X-Ref
Registers the personal data exporter for comments.

return: array $exporters An array of personal data exporters.
param: array $exporters An array of personal data exporters.

wp_comments_personal_data_exporter( $email_address, $page = 1 )   X-Ref
Finds and exports personal data associated with an email address from the comments table.

return: array $return An array of personal data.
param: string $email_address The comment author email address.
param: int    $page          Comment page.

wp_register_comment_personal_data_eraser( $erasers )   X-Ref
Registers the personal data eraser for comments.

return: array $erasers An array of personal data erasers.
param: array $erasers An array of personal data erasers.

wp_comments_personal_data_eraser( $email_address, $page = 1 )   X-Ref
Erases personal data associated with an email address from the comments table.

return: array
param: string $email_address The comment author email address.
param: int    $page          Comment page.

Generated: Wed Nov 21 08:20:01 2018 Cross-referenced by PHPXref 0.7