wp_transition_post_status()
概述
wp_transition_post_status() 是一个 WordPress 核心函数，用于触发与文章状态转换相关的动作钩子。它不直接改变数据库中的文章状态，而是通过 do_action() 调用钩子，允许插件开发者监听状态变化事件。
关键要点
- 函数作用：触发三个动作钩子：通用的 'transition_post_status'、动态的 '{$old_status}_to_{$new_status}' 和 '{$new_status}_{$post->post_type}'，用于处理文章状态转换时的自定义逻辑。
- 参数要求：必须传入 $new_status（新状态）、$old_status（旧状态）和 $post（WP_Post 对象）三个参数，以确保钩子正确执行。
- 使用场景：通常在插件或主题中手动更新文章状态时调用，例如直接操作数据库绕过标准流程时；使用 wp_update_post() 或 wp_publish_post() 等核心函数时无需手动调用。
- 注意事项：状态转换不一定意味着状态实际改变（如更新已发布的文章时，旧状态和新状态可能相同），钩子仍会触发；动态钩子名称基于状态和文章类型生成，需注意其触发条件。
代码示例
global $wpdb;
if ( ! $post = get_post( $post ) ) return;
if ( 'publish' == $post->post_status ) return;
$wpdb->update( $wpdb->posts, array( 'post_status' => 'publish' ), array( 'ID' => $post->ID ) );
clean_post_cache( $post->ID );
$old_status = $post->post_status;
$post->post_status = 'publish';
wp_transition_post_status( 'publish', $old_status, $post );Fires actions related to the transitioning of a post’s status.
Description
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. This function fires a number of action hooks related to that transition: the generic ‘transition_post_status’ action, as well as the dynamic hooks ‘$old_status_to_$new_status’ and ‘$new_status_$post->post_type’. Note that the function does not transition the post object in the database.
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 published and is simply being updated, the “old” and “new” statuses may both be ‘publish’ before and after the transition.
Parameters
$new_statusstringrequired-
Transition to this post status.
$old_statusstringrequired-
Previous post status.
$postWP_Postrequired-
Post data.
Source
function wp_transition_post_status( $new_status, $old_status, $post ) {
/**
* Fires when a post is transitioned from one status to another.
*
* @since 2.3.0
*
* @param string $new_status New post status.
* @param string $old_status Old post status.
* @param WP_Post $post Post object.
*/
do_action( 'transition_post_status', $new_status, $old_status, $post );
/**
* Fires when a post is transitioned from one status to another.
*
* The dynamic portions of the hook name, `$new_status` and `$old_status`,
* refer to the old and new post statuses, respectively.
*
* Possible hook names include:
*
* - `draft_to_publish`
* - `publish_to_trash`
* - `pending_to_draft`
*
* @since 2.3.0
*
* @param WP_Post $post Post object.
*/
do_action( "{$old_status}_to_{$new_status}", $post );
/**
* Fires when a post is transitioned from one status to another.
*
* The dynamic portions of the hook name, `$new_status` and `$post->post_type`,
* refer to the new post status and post type, respectively.
*
* Possible hook names include:
*
* - `draft_post`
* - `future_post`
* - `pending_post`
* - `private_post`
* - `publish_post`
* - `trash_post`
* - `draft_page`
* - `future_page`
* - `pending_page`
* - `private_page`
* - `publish_page`
* - `trash_page`
* - `publish_attachment`
* - `trash_attachment`
*
* 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 'transition_post_status' hook instead.
*
* @since 2.3.0
* @since 5.9.0 Added `$old_status` parameter.
*
* @param int $post_id Post ID.
* @param WP_Post $post Post object.
* @param string $old_status Old post status.
*/
do_action( "{$new_status}_{$post->post_type}", $post->ID, $post, $old_status );
}
Hooks
- do_action( ‘transition_post_status’, string $new_status, string $old_status, WP_Post $post )
-
Fires when a post is transitioned from one status to another.
- do_action( “{$new_status}_{$post->post_type}”, int $post_id, WP_Post $post, string $old_status )
-
Fires when a post is transitioned from one status to another.
- do_action( “{$old_status}_to_{$new_status}”, WP_Post $post )
-
Fires when a post is transitioned from one status to another.
Changelog
| Version | Description |
|---|---|
| 2.3.0 | Introduced. |
Skip to note 2 content
Codex
Basic Example
The following example is based on wp_publish_post() .
global $wpdb; if ( ! $post = get_post( $post ) ) return; if ( 'publish' == $post->post_status ) return; $wpdb->update( $wpdb->posts, array( 'post_status' => 'publish' ), array( 'ID' => $post->ID ) ); clean_post_cache( $post->ID ); $old_status = $post->post_status; $post->post_status = 'publish'; wp_transition_post_status( 'publish', $old_status, $post );