Make WordPress Core

Changeset 31461


Ignore:
Timestamp:
02/14/2015 09:10:29 AM (10 years ago)
Author:
DrewAPicture
Message:

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.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/post.php

    r31450 r31461  
    39203920 * Transition the post status of a post.
    39213921 *
    3922  * Calls hooks to transition post status.
    3923  *
    3924  * The first is 'transition_post_status' with new status, old status, and post data.
    3925  *
    3926  * The next action called is 'OLDSTATUS_to_NEWSTATUS' the 'NEWSTATUS' is the
    3927  * $new_status parameter and the 'OLDSTATUS' is $old_status parameter; it has the
    3928  * post data.
    3929  *
    3930  * The final action is named 'NEWSTATUS_POSTTYPE', 'NEWSTATUS' is from the $new_status
    3931  * parameter and POSTTYPE is post_type post data.
     3922 * When a post is saved, the post status is "transitioned" from one status to another,
     3923 * though this does not always mean the status has actually changed before and after
     3924 * the save.
     3925 *
     3926 * For instance: When publishing a post for the first time, the post status may transition
     3927 * from 'draft' – or some other status – to 'publish'. However, if a post is already
     3928 * published and is simply being updated, the "old" and "new" statuses may both be 'publish'
     3929 * before and after the transition.
    39323930 *
    39333931 * @since 2.3.0
     
    39663964     * The dynamic portions of the hook name, `$new_status` and `$post->post_type`,
    39673965     * refer to the new post status and post type, respectively.
     3966     *
     3967     * Please note: When this action is hooked using a particular post status (like
     3968     * 'publish', as `publish_{$post->post_type}`), it will fire both when a post is
     3969     * first transitioned to that status from something else, as well as upon
     3970     * subsequent post updates (old and new status are both the same).
     3971     *
     3972     * Therefore, if you are looking to only fire a callback when a post is first
     3973     * transitioned to a status, use the {@see 'transition_post_status'} hook instead.
    39683974     *
    39693975     * @since 2.3.0
Note: See TracChangeset for help on using the changeset viewer.