wp_transition_post_status

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

Description

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

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 changed before and after the save. This function fires a number of action hooks related to that transition: the generic action, as well as the dynamic hooks and . 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 (3)

0. $new_status (string)
Transition to this post status.
1. $old_status (string)
Previous post status.
2. $post (WP_Post)
Post data.

Usage

  1. if ( !function_exists( 'wp_transition_post_status' ) ) { 
  2. require_once ABSPATH . WPINC . '/post.php'; 
  3.  
  4. // Transition to this post status. 
  5. $new_status = ''; 
  6.  
  7. // Previous post status. 
  8. $old_status = ''; 
  9.  
  10. // Post data. 
  11. $post = null; 
  12.  
  13. // NOTICE! Understand what this does before running. 
  14. $result = wp_transition_post_status($new_status, $old_status, $post); 
  15.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/post.php  
  1. function wp_transition_post_status( $new_status, $old_status, $post ) { 
  2. /** 
  3. * Fires when a post is transitioned from one status to another. 
  4. * @since 2.3.0 
  5. * @param string $new_status New post status. 
  6. * @param string $old_status Old post status. 
  7. * @param WP_Post $post Post object. 
  8. */ 
  9. do_action( 'transition_post_status', $new_status, $old_status, $post ); 
  10.  
  11. /** 
  12. * Fires when a post is transitioned from one status to another. 
  13. * The dynamic portions of the hook name, `$new_status` and `$old status`,  
  14. * refer to the old and new post statuses, respectively. 
  15. * @since 2.3.0 
  16. * @param WP_Post $post Post object. 
  17. */ 
  18. do_action( "{$old_status}_to_{$new_status}", $post ); 
  19.  
  20. /** 
  21. * Fires when a post is transitioned from one status to another. 
  22. * The dynamic portions of the hook name, `$new_status` and `$post->post_type`,  
  23. * refer to the new post status and post type, respectively. 
  24. * Please note: When this action is hooked using a particular post status (like 
  25. * 'publish', as `publish_{$post->post_type}`), it will fire both when a post is 
  26. * first transitioned to that status from something else, as well as upon 
  27. * subsequent post updates (old and new status are both the same). 
  28. * Therefore, if you are looking to only fire a callback when a post is first 
  29. * transitioned to a status, use the {@see 'transition_post_status'} hook instead. 
  30. * @since 2.3.0 
  31. * @param int $post_id Post ID. 
  32. * @param WP_Post $post Post object. 
  33. */ 
  34. do_action( "{$new_status}_{$post->post_type}", $post->ID, $post );