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.

Contents

Parameters

$new_status string
New post status.
$old_status string
Old post status.
$post WP_Post
Post object.

Top ↑

Source

File: wp-includes/post.php. View all references 

do_action( 'transition_post_status', $new_status, $old_status, $post );

View on Trac View on GitHub

Top ↑

Top ↑

Changelog

Changelog
Version Description
2.3.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 10You must log in to vote on the helpfulness of this note
    Contributed by Rolf Allard van Hagen —

    Please note that the name transition_post_status is misleading. The hook does not only fire on a post status transition but also when a post is updated while the status is not changed from one to another at all.

    So if you wish to really only do stuff on status transition and not on regular post updates, you will need to (at least) start with a basic bailout like this:

    /**
 * Do stuff only when posts are actually transitioned from one status to another.
 *
 * @param string  $new_status New post status.
 * @param string  $old_status Old post status.
 * @param WP_Post $post       Post object.
 */
function wpdocs_run_on_transition_only( $new_status, $old_status, $post ) {
    if ( $old_status == $new_status )
		return;

	// do stuff
}
add_action( 'transition_post_status', 'wpdocs_run_on_transition_only', 10, 3 );

    For doing stuff when moving in and out (!) of published status only, use 

    if ( $old_status == $new_status || $old_status != 'publish' && $new_status != 'publish' )
	return;

// do stuff
  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
    Contributed by Drew Jaynes —

    Sometimes you only want to fire a callback when a post status is transitioned to ‘publish’, i.e. coming from some other status other than publish (published posts retain the publish status even when updating).

    Only fire a callback when a post status is transitioned to publish

    /**
 * Fire a callback only when my-custom-post-type posts are transitioned to 'publish'.
 *
 * @param string  $new_status New post status.
 * @param string  $old_status Old post status.
 * @param WP_Post $post       Post object.
 */
function wpdocs_run_on_publish_only( $new_status, $old_status, $post ) {
	if ( ( 'publish' === $new_status && 'publish' !== $old_status )
		&& 'my-custom-post-type' === $post->post_type
	) {
			// do stuff
	}
}
add_action( 'transition_post_status', 'wpdocs_run_on_publish_only', 10, 3 );
  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note
    Contributed by Ashar Irfan —

    Example: Check if someone published a custom post type first time.

    // Check to see if user posted first time.
add_action( 'transition_post_status', 'some_function', 10, 3 );
function some_function( $new, $old, $post ) {
    if ( ( $new == 'publish' ) && ( $old != 'publish' ) && ( $post->post_type == 'your_post_type' ) ) {
		// do stuff
	} else {
		return;
	}
}
  4. Skip to note 4 content
    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
    Contributed by Biplav —

    If you are looking to hook something on a specific post status change you can also use this hook

    do_action( "{$old_status}_to_{$new_status}", $post );

    This could be used for two specific post status. For example if you are looking to hook something when a draft post is published you can use this hook like this,

     add_action( "draft_to_publish", function( $post ) { //do something here } );

    Of course this opens up a possibility for so many things and you don’t have to keep relying on transition_post_status which runs even when post status are not changed.

  5. Skip to note 5 content
    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
    Contributed by Aurovrata Venet —

    Status can be one of: publish, future, draft, pending, private

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