wp_transition_comment_status() │ WP 2.7.0

Calls special hooks when the status of a comment changes from one to another: for example, from unapproved to approved.

This function does not change the status of the comment, but only triggers 3 hooks. The function is called from other functions after the status of the comment has been changed to notify plugins, themes, and core functions about the change in the comment status.

To actually change the status of the comment, use the functions: wp_update_comment() from which this function is specifically called.

The function will trigger the following 2 hooks if the status of the updated comment differs from its previous status:

// Triggers whenever the status changes
do_action( 'transition_comment_status', $new_status, $old_status, $comment );

// triggers when the specified status changes to the specified one
do_action( "comment_{$old_status}_to_{$new_status}", $comment );

And the third hook always triggers when the function is called:

do_action( "comment_{$new_status}_{$comment_type}", $comment_ID, $comment );

The function is called every time the following functions are invoked:

Possible values for $new_status and $old_status
  • unapproved
  • approved
  • delete

Comment statuses like: 0, hold, 1, approve will correspond to one of these names:

0         => 'unapproved',
'hold'    => 'unapproved',
1         => 'approved',
'approve' => 'approved',

That is, all hook names look like this:

  • transition_comment_status
  • comment_unapproved_to_approved
  • comment_unapproved_to_delete
  • comment_approved_to_unapproved
  • comment_approved_to_delete
  • comment_delete_to_approved
  • comment_delete_to_unapproved
  • comment_unapproved_{$comment_type}
  • comment_approved_{$comment_type}
  • comment_delete_{$comment_type}
Hooks from the function

Returns

null. Nothing.

Usage

wp_transition_comment_status( $new_status, $old_status, $comment );
$new_status(string) (required)
Name of the new status. Can be: 0, hold, unapproved, 1, approve, approved, delete
$old_status(string) (required)
Name of the old status. Can be one of the values of $new_status.
$comment(object) (required)
The comment object.

Examples

0

#1 Usage example

Send an email when a comment is approved.

add_action( 'comment_unapproved_to_approved', 'approve_comment_callback' );

function approve_comment_callback( $comment ){

	// the comment changed its status from disapproved to approved
	// do something here
	// for example, send a letter to somewhere

	// wp_mail( $comment->comment_author_email, $subject, $notification );
}

Changelog

Since 2.7.0 Introduced.

wp_transition_comment_status() code WP 6.9.1

wp-includes/comment.php 
function wp_transition_comment_status( $new_status, $old_status, $comment ) {
	/*
	 * Translate raw statuses to human-readable formats for the hooks.
	 * This is not a complete list of comment status, it's only the ones
	 * that need to be renamed.
	 */
	$comment_statuses = array(
		0         => 'unapproved',
		'hold'    => 'unapproved', // wp_set_comment_status() uses "hold".
		1         => 'approved',
		'approve' => 'approved',   // wp_set_comment_status() uses "approve".
	);
	if ( isset( $comment_statuses[ $new_status ] ) ) {
		$new_status = $comment_statuses[ $new_status ];
	}
	if ( isset( $comment_statuses[ $old_status ] ) ) {
		$old_status = $comment_statuses[ $old_status ];
	}

	// Call the hooks.
	if ( $new_status !== $old_status ) {
		/**
		 * Fires when the comment status is in transition.
		 *
		 * @since 2.7.0
		 *
		 * @param string     $new_status The new comment status.
		 * @param string     $old_status The old comment status.
		 * @param WP_Comment $comment    Comment object.
		 */
		do_action( 'transition_comment_status', $new_status, $old_status, $comment );

		/**
		 * Fires when the comment status is in transition from one specific status to another.
		 *
		 * The dynamic portions of the hook name, `$old_status`, and `$new_status`,
		 * refer to the old and new comment statuses, respectively.
		 *
		 * Possible hook names include:
		 *
		 *  - `comment_unapproved_to_approved`
		 *  - `comment_spam_to_approved`
		 *  - `comment_approved_to_unapproved`
		 *  - `comment_spam_to_unapproved`
		 *  - `comment_unapproved_to_spam`
		 *  - `comment_approved_to_spam`
		 *
		 * @since 2.7.0
		 *
		 * @param WP_Comment $comment Comment object.
		 */
		do_action( "comment_{$old_status}_to_{$new_status}", $comment );
	}
	/**
	 * Fires when the status of a specific comment type is in transition.
	 *
	 * The dynamic portions of the hook name, `$new_status`, and `$comment->comment_type`,
	 * refer to the new comment status, and the type of comment, respectively.
	 *
	 * Typical comment types include 'comment', 'pingback', or 'trackback'.
	 *
	 * Possible hook names include:
	 *
	 *  - `comment_approved_comment`
	 *  - `comment_approved_pingback`
	 *  - `comment_approved_trackback`
	 *  - `comment_unapproved_comment`
	 *  - `comment_unapproved_pingback`
	 *  - `comment_unapproved_trackback`
	 *  - `comment_spam_comment`
	 *  - `comment_spam_pingback`
	 *  - `comment_spam_trackback`
	 *
	 * @since 2.7.0
	 *
	 * @param string     $comment_id The comment ID as a numeric string.
	 * @param WP_Comment $comment    Comment object.
	 */
	do_action( "comment_{$new_status}_{$comment->comment_type}", $comment->comment_ID, $comment );
}

statuses (of post comment user)

Comments