do_action( ‘transition_post_status’, string $new_status, string $old_status, WP_Post $post )

User Contributed Notes

1. Skip to note 6 content

   Rolf Allard van Hagen 6 years ago

   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

   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 7 content

   Drew Jaynes 10 years ago

   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

   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 8 content

   Ashar Irfan 8 years ago

   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

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

   • This does not guarantee that it is the first time the post was published: it will fire if the post was published, changed to a different status, and then published again.

     crstauf 4 years ago
4. Skip to note 9 content

   Biplav 4 years ago

   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

   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.

   • It’s important to note that using anonymous functions in add_action() or add_filter() is in most cases an incredibly bad idea. This would make the code in the functions really hard to get rid of from another plugin or theme. In cases when your code is to be used in other people’s projects, anonymous functions are almost “immune” to being removed through remove_function() or remove_filter() and it’s rarely the case that one would look after this effect.

     Vladimir Vassilev 3 years ago
5. Skip to note 10 content

   Aurovrata Venet 4 years ago

   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

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

   • If there are plugins that introduce new status types, they may also be (untested) run through this hook.

     crstauf 4 years ago
   • This seems to be incomplete. List from old codex https://codex.wordpress.org/Post_Status_Transitions, section with title “The available post statuses are:”

     te-online 2 years ago