Description

Transition the post status of a post.

This function calls hooks to transition a post's status. It does NOT change the status of the post. It only calls hooks to notify plugins, themes, and other core functions of the status change. To change the status of a post, use wp_update_post() or wp_publish_post().

This function is called after the status of a post has been changed to notify plugins, themes, and other core functions of the change by calling three actions.

The first is 'transition_post_status' with the new status, the old status, and the post data.

The next action called is 'OLDSTATUS_to_NEWSTATUS', where the 'NEWSTATUS' is the $new_status parameter and the 'OLDSTATUS' is $old_status parameter; it is passed the post object.

The final action is named 'NEWSTATUS_POSTTYPE', where 'NEWSTATUS' is from the $new_status parameter and 'POSTTYPE' is the post_type field from the $post data.

Usage

<?php wp_transition_post_status( $new_status, $old_status, $post ) ?>

Parameters

$new_status

(string) (required) Transition to this post status.

Default: None

$old_status

(string) (required) Previous post status.

Default: None

$post

(object) (required) Post data.

Default: None

Return Values

(void) 

This function does not return a value.

Examples

The following example is based on wp_publish_post().

<?php

global $wpdb;
	
$post = get_post( $post )

if ( 'publish' == $post->post_status )
    return;
	
$wpdb->update( $wpdb->posts, array( 'post_status' => 'publish' ), array( 'ID' => $post->ID ) );

clean_post_cache( $post->ID );
	
$old_status = $post->post_status;
$post->post_status = 'publish';
wp_transition_post_status( 'publish', $old_status, $post );

?>

Notes

• This function is already called where needed in core functions. You do not need to call this function when changing a post's status with wp_update_post(), for example. You do need to call this function in your plugin or theme when manually updating the status of a post, as shown in the example above.

Source Code

wp_transition_post_status() is located in wp-includes/post.php

Change Log

• Since 2.3.0

Related

Post Status Transitions - More information on how to hook into the actions called by this function.