Difference between revisions of "Post Status Transitions"

Latest revision as of 12:51, 16 May 2015

Languages: English • 日本語 (Add your language)

1 transition_post_status Hook
2 {old_status}_to_{new_status} Hook
3 {status}_{post_type} Hook
4 Not Deprecated Hooks
5 Deprecated Hooks
6 Related
7 Source File

WordPress 2.3 introduced some new actions that plugins can use to hook into post status transitions. Prior to Version 2.3, WordPress had a private_to_published (deprecated) action that only announced when a post transitioned from private to published. As of Version 2.3, there are actions for every possible transition.

There are three kinds of post status transition action hooks:

transition_post_status
{old_status}_to_{new_status}
{status}_{post_type}

All three actions are called by wp_transition_post_status() in wp-includes/post.php.

The available post statuses are:

new – When there’s no previous status (this means these hooks are always run whenever "save_post" runs.
publish – A published post or page.
pending – A post pending review.
draft – A post in draft status.
auto-draft – A newly created post with no content.
future – A post scheduled to publish in the future.
private – Not visible to users who are not logged in.
inherit – A revision or attachment (see get_children()).
trash – Post is in the trash (added with Version 2.9).

transition_post_status Hook

transition_post_status is a generic action that is called every time a post changes status. When do_action() is called for transition_post_status, three arguments are passed to it: $new_status, $old_status and the $post object. Therefore, these are also available to be used in the callback function. In the add_action() call, the action priority may be set between 0 and 20 (default is 10) and it is necessary to specify the number of arguments do_action() should pass to the callback function.

function on_all_status_transitions( $new_status, $old_status, $post ) {
    if ( $new_status != $old_status ) {
        // A function to perform actions any time any post changes status.
    }
}
add_action(  'transition_post_status',  'on_all_status_transitions', 10, 3 );

function post_unpublished( $new_status, $old_status, $post ) {
    if ( $old_status == 'publish'  &&  $new_status != 'publish' ) {
        // A function to perform actions when a post status changes from publish to any non-public status.
    }
}
add_action( 'transition_post_status', 'post_unpublished', 10, 3 );

Don’t confuse the transition_post_status action hook with the wp_transition_post_status() function or the private function _transition_post_status(). The function wp_transition_post_status() is used to call the post status transition actions and can be found in wp-includes/post.php. This function would be useful if your plugin directly modifies the database, thereby bypassing the usual post status transition action hooks. If you want 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().

{old_status}_to_{new_status} Hook

An {old_status}_to_{new_status} action will execute when a post transitions from {old_status} to {new_status}. The action is accompanied by the $post object. In the add_action() function call, the action priority may be set between 0 and 20 (default is 10) and it is necessary to specify the number of arguments do_action() should pass to the callback function.

function on_publish_pending_post( $post ) {
    // A function to perform when a pending post is published.
}
add_action(  'pending_to_publish',  'on_publish_pending_post', 10, 1 );

{status}_{post_type} Hook

A {status}_{post_type} action will execute when a post of type {post_type} transitions to {status} from any other status. For example, when a post is published, a publish_post action is triggered. The action is accompanied by the post ID and $post object. Default values for post type are post, page, attachment, revision, navigation. Additionally, custom post types may also be used.

function on_post_publish( $ID, $post ) {
    // A function to perform actions when a post is published.
}
add_action(  'publish_post',  'on_post_publish', 10, 2 );

function on_post_scheduled( $ID, $post ) {
    // A function to perform actions when a post is scheduled to be published.
}
add_action(  'future_post',  'on_post_scheduled', 10, 2 );

Not Deprecated Hooks

The publish_post and publish_page actions had been identified as deprecated on the Action Reference page and the publish_post and publish_page action pages. This was not correct. Prior to WordPress 2.3, the callback function for publish_post took only the post ID as an argument and no other arguments were passed to the action by default. Since Version 2.3, both the post ID and the $post object are passed to the action and the add_action() call should specify the action priority and the number of arguments the action accepts. If called correctly, publish_post and publish_page are still legitimate action hooks.

Deprecated Hooks

private_to_published is deprecated but may be replaced with private_to_publish.

publish_future_post is deprecated but may be replaced with future_to_publish.

transition_post_status
wp_transition_post_status()
publish_post
publish_page
Post Types
add_action()
wp_update_post()
wp_publish_post()

Source File

See wp_transition_post_status() in wp-includes/post.php.

Codex