wp_transition_post_status

WordPress Version: 5.9

/**
 * Fires actions related to the transitioning of a post's status.
 *
 * 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 {@see 'transition_post_status'} action, as well as the dynamic hooks
 * {@see '$old_status_to_$new_status'} and {@see '$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.
 *
 * @since 2.3.0
 *
 * @param string  $new_status Transition to this post status.
 * @param string  $old_status Previous post status.
 * @param WP_Post $post Post data.
 */
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 hook name, `$new_status` and `$old_status`,
     * refer to the old and new post statuses, respectively.
     *
     * Possible hook 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 hook name, `$new_status` and `$post->post_type`,
     * refer to the new post status and post type, respectively.
     *
     * Possible hook names include:
     *
     *  - `draft_post`
     *  - `future_post`
     *  - `pending_post`
     *  - `private_post`
     *  - `publish_post`
     *  - `trash_post`
     *  - `draft_page`
     *  - `future_page`
     *  - `pending_page`
     *  - `private_page`
     *  - `publish_page`
     *  - `trash_page`
     *  - `publish_attachment`
     *  - `trash_attachment`
     *
     * Please note: When this action is hooked using a particular post status (like
     * '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 looking to only fire a callback when a post is first
     * transitioned to a status, use the {@see 'transition_post_status'} hook 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);
}

WordPress Version: 5.8

/**
 * Fires actions related to the transitioning of a post's status.
 *
 * 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 {@see 'transition_post_status'} action, as well as the dynamic hooks
 * {@see '$old_status_to_$new_status'} and {@see '$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.
 *
 * @since 2.3.0
 *
 * @param string  $new_status Transition to this post status.
 * @param string  $old_status Previous post status.
 * @param WP_Post $post Post data.
 */
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 hook name, `$new_status` and `$old_status`,
     * refer to the old and new post statuses, respectively.
     *
     * @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 hook name, `$new_status` and `$post->post_type`,
     * refer to the new post status and post type, respectively.
     *
     * Possible hook names include:
     *
     *  - `draft_post`
     *  - `future_post`
     *  - `pending_post`
     *  - `private_post`
     *  - `publish_post`
     *  - `trash_post`
     *  - `draft_page`
     *  - `future_page`
     *  - `pending_page`
     *  - `private_page`
     *  - `publish_page`
     *  - `trash_page`
     *  - `publish_attachment`
     *  - `trash_attachment`
     *
     * Please note: When this action is hooked using a particular post status (like
     * '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 looking to only fire a callback when a post is first
     * transitioned to a status, use the {@see 'transition_post_status'} hook instead.
     *
     * @since 2.3.0
     *
     * @param int     $post_id Post ID.
     * @param WP_Post $post    Post object.
     */
    do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
}

WordPress Version: 5.6

/**
 * Fires actions related to the transitioning of a post's status.
 *
 * 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 {@see 'transition_post_status'} action, as well as the dynamic hooks
 * {@see '$old_status_to_$new_status'} and {@see '$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.
 *
 * @since 2.3.0
 *
 * @param string  $new_status Transition to this post status.
 * @param string  $old_status Previous post status.
 * @param WP_Post $post Post data.
 */
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 hook name, `$new_status` and `$old_status`,
     * refer to the old and new post statuses, respectively.
     *
     * @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 hook name, `$new_status` and `$post->post_type`,
     * refer to the new post status and post type, respectively.
     *
     * Please note: When this action is hooked using a particular post status (like
     * '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 looking to only fire a callback when a post is first
     * transitioned to a status, use the {@see 'transition_post_status'} hook instead.
     *
     * @since 2.3.0
     *
     * @param int     $post_id Post ID.
     * @param WP_Post $post    Post object.
     */
    do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
}

WordPress Version: 4.6

/**
 * Fires actions related to the transitioning of a post's status.
 *
 * 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 {@see 'transition_post_status'} action, as well as the dynamic hooks
 * {@see '$old_status_to_$new_status'} and {@see '$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.
 *
 * @since 2.3.0
 *
 * @param string  $new_status Transition to this post status.
 * @param string  $old_status Previous post status.
 * @param WP_Post $post Post data.
 */
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 hook name, `$new_status` and `$old status`,
     * refer to the old and new post statuses, respectively.
     *
     * @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 hook name, `$new_status` and `$post->post_type`,
     * refer to the new post status and post type, respectively.
     *
     * Please note: When this action is hooked using a particular post status (like
     * '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 looking to only fire a callback when a post is first
     * transitioned to a status, use the {@see 'transition_post_status'} hook instead.
     *
     * @since 2.3.0
     *
     * @param int     $post_id Post ID.
     * @param WP_Post $post    Post object.
     */
    do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
}

WordPress Version: 4.3

/**
 * Fires actions related to the transitioning of a post's status.
 *
 * 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 'transition_post_status' action, as well as the dynamic hooks
 * `"{$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.
 *
 * @since 2.3.0
 *
 * @param string  $new_status Transition to this post status.
 * @param string  $old_status Previous post status.
 * @param WP_Post $post Post data.
 */
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 hook name, `$new_status` and `$old status`,
     * refer to the old and new post statuses, respectively.
     *
     * @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 hook name, `$new_status` and `$post->post_type`,
     * refer to the new post status and post type, respectively.
     *
     * Please note: When this action is hooked using a particular post status (like
     * '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 looking to only fire a callback when a post is first
     * transitioned to a status, use the {@see 'transition_post_status'} hook instead.
     *
     * @since 2.3.0
     *
     * @param int     $post_id Post ID.
     * @param WP_Post $post    Post object.
     */
    do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
}

WordPress Version: 4.2

/**
 * Transition the post status of a 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.
 *
 * 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.
 *
 * @since 2.3.0
 *
 * @param string  $new_status Transition to this post status.
 * @param string  $old_status Previous post status.
 * @param WP_Post $post Post data.
 */
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 hook name, `$new_status` and `$old status`,
     * refer to the old and new post statuses, respectively.
     *
     * @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 hook name, `$new_status` and `$post->post_type`,
     * refer to the new post status and post type, respectively.
     *
     * Please note: When this action is hooked using a particular post status (like
     * '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 looking to only fire a callback when a post is first
     * transitioned to a status, use the {@see 'transition_post_status'} hook instead.
     *
     * @since 2.3.0
     *
     * @param int     $post_id Post ID.
     * @param WP_Post $post    Post object.
     */
    do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
}

WordPress Version: 4.1

/**
 * Transition the post status of a post.
 *
 * Calls hooks to transition post status.
 *
 * The first is 'transition_post_status' with new status, old status, and post data.
 *
 * The next action called is 'OLDSTATUS_to_NEWSTATUS' the 'NEWSTATUS' is the
 * $new_status parameter and the 'OLDSTATUS' is $old_status parameter; it has the
 * post data.
 *
 * The final action is named 'NEWSTATUS_POSTTYPE', 'NEWSTATUS' is from the $new_status
 * parameter and POSTTYPE is post_type post data.
 *
 * @since 2.3.0
 *
 * @param string  $new_status Transition to this post status.
 * @param string  $old_status Previous post status.
 * @param WP_Post $post Post data.
 */
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 hook name, `$new_status` and `$old status`,
     * refer to the old and new post statuses, respectively.
     *
     * @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 hook name, `$new_status` and `$post->post_type`,
     * refer to the new post status and post type, respectively.
     *
     * @since 2.3.0
     *
     * @param int     $post_id Post ID.
     * @param WP_Post $post    Post object.
     */
    do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
}

WordPress Version: 4.0

/**
 * Transition the post status of a post.
 *
 * Calls hooks to transition post status.
 *
 * The first is 'transition_post_status' with new status, old status, and post data.
 *
 * The next action called is 'OLDSTATUS_to_NEWSTATUS' the 'NEWSTATUS' is the
 * $new_status parameter and the 'OLDSTATUS' is $old_status parameter; it has the
 * post data.
 *
 * The final action is named 'NEWSTATUS_POSTTYPE', 'NEWSTATUS' is from the $new_status
 * parameter and POSTTYPE is post_type post data.
 *
 * @since 2.3.0
 *
 * @param string $new_status Transition to this post status.
 * @param string $old_status Previous post status.
 * @param object $post Post data.
 */
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 hook name, $new_status and $old status,
     * refer to the old and new post statuses, respectively.
     *
     * @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 hook name, $new_status and $post->post_type,
     * refer to the new post status and post type, respectively.
     *
     * @since 2.3.0
     *
     * @param int     $post_id Post ID.
     * @param WP_Post $post    Post object.
     */
    do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
}

WordPress Version: 3.9

/**
 * Transition the post status of a post.
 *
 * Calls hooks to transition post status.
 *
 * The first is 'transition_post_status' with new status, old status, and post data.
 *
 * The next action called is 'OLDSTATUS_to_NEWSTATUS' the 'NEWSTATUS' is the
 * $new_status parameter and the 'OLDSTATUS' is $old_status parameter; it has the
 * post data.
 *
 * The final action is named 'NEWSTATUS_POSTTYPE', 'NEWSTATUS' is from the $new_status
 * parameter and POSTTYPE is post_type post data.
 *
 * @since 2.3.0
 *
 * @link http://codex.wordpress.org/Post_Status_Transitions
 *
 * @param string $new_status Transition to this post status.
 * @param string $old_status Previous post status.
 * @param object $post Post data.
 */
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 hook name, $new_status and $old status,
     * refer to the old and new post statuses, respectively.
     *
     * @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 hook name, $new_status and $post->post_type,
     * refer to the new post status and post type, respectively.
     *
     * @since 2.3.0
     *
     * @param int     $post_id Post ID.
     * @param WP_Post $post    Post object.
     */
    do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
}

WordPress Version: 3.7

/**
 * Transition the post status of a post.
 *
 * Calls hooks to transition post status.
 *
 * The first is 'transition_post_status' with new status, old status, and post data.
 *
 * The next action called is 'OLDSTATUS_to_NEWSTATUS' the 'NEWSTATUS' is the
 * $new_status parameter and the 'OLDSTATUS' is $old_status parameter; it has the
 * post data.
 *
 * The final action is named 'NEWSTATUS_POSTTYPE', 'NEWSTATUS' is from the $new_status
 * parameter and POSTTYPE is post_type post data.
 *
 * @since 2.3.0
 * @link http://codex.wordpress.org/Post_Status_Transitions
 *
 * @uses do_action() Calls 'transition_post_status' on $new_status, $old_status and
 *  $post if there is a status change.
 * @uses do_action() Calls '{$old_status}_to_{$new_status}' on $post if there is a status change.
 * @uses do_action() Calls '{$new_status}_{$post->post_type}' on post ID and $post.
 *
 * @param string $new_status Transition to this post status.
 * @param string $old_status Previous post status.
 * @param object $post Post data.
 */
function wp_transition_post_status($new_status, $old_status, $post)
{
    do_action('transition_post_status', $new_status, $old_status, $post);
    do_action("{$old_status}_to_{$new_status}", $post);
    do_action("{$new_status}_{$post->post_type}", $post->ID, $post);
}