Update the descriptions for transition_post_status() and the {$new_stats}_{$post->post_type} hook with more information about the expected behavior of transitioning post statuses.

In some cases, the values of `$old_status` and `$new_status` may be the same thing before and after a post status is "transitioned". An example of this would be the scenario where a published post is being updated: the status before and after the update both equal 'publish'.

Further, the documentation clarifies that if the intent is to only execute code when initially transitioningto a post status from something else, the 'transition_post_status' hook should be used instead of one of the dynamic hooks to avoid confusion.

Props Idealien for the initial patch.
Fixes #31099.

Built from https://develop.svn.wordpress.org/trunk@31461


git-svn-id: http://core.svn.wordpress.org/trunk@31442 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2015-02-14 09:11:28 +00:00
parent fd6448247b
commit 542a4bd98b
2 changed files with 16 additions and 10 deletions

View File

@ -3919,16 +3919,14 @@ function wp_set_post_categories( $post_ID = 0, $post_categories = array(), $appe
/** /**
* Transition the post status of a post. * Transition the post status of a post.
* *
* Calls hooks to transition post 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.
* *
* The first is 'transition_post_status' with new status, old status, and post data. * 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
* The next action called is 'OLDSTATUS_to_NEWSTATUS' the 'NEWSTATUS' is the * published and is simply being updated, the "old" and "new" statuses may both be 'publish'
* $new_status parameter and the 'OLDSTATUS' is $old_status parameter; it has the * before and after the transition.
* 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 * @since 2.3.0
* *
@ -3966,6 +3964,14 @@ function wp_transition_post_status( $new_status, $old_status, $post ) {
* The dynamic portions of the hook name, `$new_status` and `$post->post_type`, * The dynamic portions of the hook name, `$new_status` and `$post->post_type`,
* refer to the new post status and post type, respectively. * 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 * @since 2.3.0
* *
* @param int $post_id Post ID. * @param int $post_id Post ID.

View File

@ -4,7 +4,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '4.2-alpha-31460'; $wp_version = '4.2-alpha-31461';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.