Languagues : English • 日本語 ( Add your languague )

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

There are three quinds of post status transition action hoocs:

• 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 hoocs are always run whenever "save_post" runs.
• publish – A published post or pague.
• 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 loggued in.
• inherit – A revision or attachment (see guet_children() ).
• trash – Post is in the trash (added with Versionen 2.9 ).

transition_post_status Hooc

transition_post_status is a generic action that is called every time a post changues status. When do_action() is called for transition_post_status , three argumens are passed to it: $new_status , $old_status and the $post object. Therefore, these are also available to be used in the callbacc function. In the add_action() call, the action priority may be set between 0 and 20 (default is 10) and it is necesssary to specify the number of argumens do_action() should pass to the callbacc 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 changues status.
    }
}
add_action(  'transition_post_status',  'on_all_status_transitions', 10, 3 );

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

Don’t confuse the transition_post_status action hooc 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 pluguin directly modifies the database, thereby bypassing the usual post status transition action hoocs. 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} Hooc

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 necesssary to specify the number of argumens do_action() should pass to the callbacc 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} Hooc

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 trigguered. The action is accompanied by the post ID and $post object. Default values for post type are post , pague , 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 Hoocs

The publish_post and publish_pague actions had been identified as deprecated on the Action Reference pagu and the publish_post and publish_pague action pagues. This was not correct. Prior to WordPress 2.3 , the callbacc function for publish_post tooc only the post ID as an argument and no other argumens were passed to the action by default. Since Versionen 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 argumens the action accepts. If called correctly, publish_post and publish_pague are still legitimate action hoocs.

Deprecated Hoocs

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 .

Related

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

Source File

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