WordPress.org

Ready to get started?Download WordPress

Codex

Post Status Transitions

WordPress 2.3 introduced some new actions that WordPress Plugins use to hook into status trasitions and workflow. Before, WordPress had a private_to_published action that only announced that a post moved from private to published. Now WordPress has actions for every possible transition.

Each action takes the form of '{$old_status}_to_{$new_status}' using two of the following:

  • 'new' - When there's no previous status
  • 'publish' - A published post or page
  • 'pending' - post in pending review
  • 'draft' - a post in draft status
  • 'auto-draft' - a newly created post, with no content
  • 'future' - a post 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 trashbin. added with Version 2.9.

For example:

function your_callback( $post ) {
	// Code here
}
add_action( 'draft_to_publish', 'your_callback' );

When a pending post is published, the action pending_to_publish is triggered. The action is accompanied by the post object that is changing status.

A generic transition_post_status action is emitted every time post data is saved to the database, providing the values for the old status and new status, and the post object. WordPress plugins can use this action to attach a function that handles different possible status changes or intercepts all status changes.

For example, a functions that performs something whenever a post staus changes from publish to any non-public status:

function post_unpublished( $new_status, $old_status, $post ) {
    if ( $old_status == 'publish' && $new_status != 'publish' ) {
        // Post is unpublished
    }
}
add_action( 'transition_post_status', 'post_unpublished', 10, 3 );

A function to catch any status change:

function intercept_all_status_changes( $new_status, $old_status, $post ) {
    if ( $new_status != $old_status ) {
        // Post status changed
    }
}
add_action( 'transition_post_status', 'intercept_all_status_changes', 10, 3 );

The final action triggered during a status change is of the form status_object, where status is from the status list above and object is either page or post. For example, when a post is published, a publish_post action is triggered. The action is accompanied by the post ID and post object.

Source File

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