WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

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.

codex status change.png

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() {
	// 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 also emitted for every status change. It is accompanied by the new status, the old status, and the post object. WordPress Plugins can use this action to attach a function that intercepts all status changes.

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.

See the function wp_transition_post_status() for how these actions are formed. Use add_action() to attach functions to these actions.