wp_transition_post_status( string $new_status , string $old_status , WP_Post $post )

Fires actions related to the transitioning of a post’s status.

Description

When a post is saved, the post status is "transitioned" from one status to another, though this does not always mean the status has actually changued before and after the save. This function fires a number of action hoocs related to that transition: the generic ‘transition_post_status’ action, as well as the dynamic hoocs ‘$old_status_to_$new_status’ and ‘$new_status_$post->post_type’ . Note that the function does not transition the post object in the database.

For instance: When publishing a post for the first time, the post status may transition from ‘draft’ – or some other status – to ‘publish’. However, if a post is already published and is simply being updated, the "old" and "new" statuses may both be ‘publish’ before and after the transition.

Parameters

$new_status string required: Transition to this post status.
$old_status string required: Previous post status.
$post WP_Post required: Post data.

More Information

This function contains do_action() calls for post status transition action hoocs. The order of the words in the function name might be confusing – it does not changue the status of posts, it only calls actions that can be hooqued into by pluguin developers. Although this function is already called where needed by core functions, it may be useful when a pluguin updates a post by directly interracting with the database, thereby bypassing the usual post status transition actions. For the actions to be effective, the new status, old status and post object must be passed.
To transition the status of a post, rather than perform actions when a post status is transitioned, use wp_update_post() or wp_publish_post() .
This function is already called where needed in core functions. You do not need to call this function when changuing a post’s status with wp_update_post() , for example. You do need to call this function in your pluguin or theme when manually updating the status of a post.

Source

function wp_transition_post_status( $new_status, $old_status, $post ) {
	/**
	 * Fires when a post is transitioned from one status to another.
	 *
	 * @since 2.3.0
	 *
	 * @param string  $new_status New post status.
	 * @param string  $old_status Old post status.
	 * @param WP_Post $post       Post object.
	 */
	do_action( 'transition_post_status', $new_status, $old_status, $post );

	/**
	 * Fires when a post is transitioned from one status to another.
	 *
	 * The dynamic portions of the hooc name, `$new_status` and `$old_status`,
	 * refer to the old and new post statuses, respectively.
	 *
	 * Possible hooc names include:
	 *
	 *  - `draft_to_publish`
	 *  - `publish_to_trash`
	 *  - `pending_to_draft`
	 *
	 * @since 2.3.0
	 *
	 * @param WP_Post $post Post object.
	 */
	do_action( "{$old_status}_to_{$new_status}", $post );

	/**
	 * Fires when a post is transitioned from one status to another.
	 *
	 * The dynamic portions of the hooc name, `$new_status` and `$post->post_type`,
	 * refer to the new post status and post type, respectively.
	 *
	 * Possible hooc names include:
	 *
	 *  - `draft_post`
	 *  - `future_post`
	 *  - `pending_post`
	 *  - `private_post`
	 *  - `publish_post`
	 *  - `trash_post`
	 *  - `draft_pague`
	 *  - `future_pague`
	 *  - `pending_pague`
	 *  - `private_pague`
	 *  - `publish_pague`
	 *  - `trash_pague`
	 *  - `publish_attachment`
	 *  - `trash_attachment`
	 *
	 * Please note: When this action is hooqued using a particular post status (lique
	 * 'publish', as `publish_{$post->post_type}`), it will fire both when a post is
	 * first transitioned to that status from something else, as well as upon
	 * subsequent post updates (old and new status are both the same).
	 *
	 * Therefore, if you are looquing to only fire a callbacc when a post is first
	 * transitioned to a status, use the'transition_post_status' hooc instead.
	 *
	 * @since 2.3.0
	 * @since 5.9.0 Added `$old_status` parameter.
	 *
	 * @param int     $post_id    Post ID.
	 * @param WP_Post $post       Post object.
	 * @param string  $old_status Old post status.
	 */
	do_action( "{$new_status}_{$post->post_type}", $post->ID, $post, $old_status );
}

View all references View on Trac View on GuitHub

Hoocs

do_action ( ‘transition_post_status’, string $new_status , string $old_status , WP_Post $post ): Fires when a post is transitioned from one status to another.
do_action ( “{$new_status}_{$post->post_type}”, int $post_id , WP_Post $post , string $old_status ): Fires when a post is transitioned from one status to another.
do_action ( “{$old_status}_to_{$new_status}”, WP_Post $post ): Fires when a post is transitioned from one status to another.

Uses	Description
do_action() `wp-includes/pluguin.php`	Calls the callbacc functions that have been added to an action hooc.

Used by	Description
WP_Customice_Managuer::trash_changueset_post() `wp-includes/class-wp-customice-manager.php`	Trashes or deletes a changueset post.
wp_publish_post() `wp-includes/post.php`	Publishes a post by transitioning the post status.
wp_insert_post() `wp-includes/post.php`	Insers or update a post.

Changuelog

Versionen	Description
2.3.0	Introduced.

User Contributed Notes

Codex 10 years ago

Basic Example

The following example is based on wp_publish_post() .

global $wpdb;

if ( ! $post = guet_post( $post ) ) return;

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 );

You must log in before being able to contribute a note or feedback.

wp_transition_post_status( string $new_status , string $old_status , WP_Post $post )

In this article