「投稿ステータスの遷移」の版間の差分

2015年6月2日 (火) 09:42時点における版

概要

WordPress 2.3 から、プラグインが投稿ステータス変更ワークフローにフックをかけられるよう、幾つかの新しいアクションが追加されました。以前、WordPress はアクション private_to_published を持っており、これは投稿が非公開（private）から公開済み（published）になるときだけ呼び出されました。いま、WordPress は有り得るすべての遷移に関してアクションを持っています。

投稿ステータスの遷移について三種類のアクションフックがあります：

• transition_post_status/en
• {old_status}_to_{new_status} – old_status は以前の、new_status は新しいステータス。
• {status}_{post_type} – status は新しいステータス、post_type は投稿タイプ。

三種類のアクションは何れも wp_transition_post_status()/en から呼び出されます。この関数は wp-includes/post.php にあります。

投稿ステータスには下記の種類があります：

• new - 以前のステータスが存在しない状態。このステータスを含むフックは、"save_post" が実行されるとき毎回実行されます。
• publish – 投稿や固定ページが「公開済」。
• pending – 「承認待ち」の投稿。
• draft – 「下書き」の投稿。
• auto-draft – 「自動保存」。作成されたばかりの投稿で、コンテンツがない。
• future – 「予約済」。未来に公開を予定されている投稿。
• private – 「非公開」。ログインしていないユーザーには表示されない。
• inherit – 「継承」。リビジョンまたは添付ファイル（get_children() を参照のこと）。
• trash – 「ゴミ箱」にある投稿（バージョン 2.9 で追加）。

transition_post_status/en は、投稿ステータスが変わるとき毎回呼び出される包括的なアクションです。transition_post_status について do_action() が呼び出されるとき、3 つの引数が渡されます: $new_status, $old_status それと $post オブジェクトです。従ってコールバック関数はこれらを利用できます。add_action() を呼び出すとき、アクションの優先度を 0 から 20 で指定し（デフォルトは 10）、do_action() がコールバック関数へ渡す引数の個数を指定しなければなりません。

function on_all_status_transitions( $new_status, $old_status, $post ) {
    if ( $new_status != $old_status ) {
        // 投稿ステータスが任意に変わるとき実行する処理。
    }
}
add_action(  'transition_post_status',  'on_all_status_transitions', 10, 3 );

function post_unpublished( $new_status, $old_status, $post ) {
    if ( $old_status == 'publish'  &&  $new_status != 'publish' ) {
        // 投稿ステータスが公開済からそれ以外へ変化するとき実行する処理。
    }
}
add_action( 'transition_post_status', 'post_unpublished', 10, 3 );

アクションフック transition_post_status と、関数 wp_transition_post_status()/en またはプライベート関数 _transition_post_status()/en を混同しないでください。関数 wp_transition_post_status() は投稿ステータスの変化時にアクションを呼び出すために使用され、wp-includes/post.php にあります。この関数は、プラグインが直接データベースを変更したい場合に役立ちます（その場合、普通の投稿ステータス変化に関するアクションフックをバイパスします）。もし投稿ステータスの変化時にアクションを実行するのでなく、投稿のステータスを変えたい場合は、wp_update_post() または wp_publish_post() を使用してください。

{old_status}_to_{new_status} アクションは、投稿ステータスが {old_status} から {new_status} へ変わるときに実行されます。このアクションには $post（投稿）オブジェクトが渡されます。add_action() を呼び出すとき、アクションの優先度を 0 から 20 で指定し（デフォルトは 10）、do_action() がコールバック関数へ渡す引数の個数を指定しなければなりません。

function on_publish_pending_post( $post ) {
	// 承認待ちの投稿が公開されるとき実行する処理。
}
add_action( 'pending_to_publish', 'on_publish_pending_post', 10, 1 );

{status}_{post_type} アクションは、タイプが {post_type} の投稿が任意のステータスから {status} へ変化するときに実行されます。例えば、投稿が公開されると publish_post アクションが呼び出されます。このアクションには投稿 ID と $post（投稿）オブジェクトが渡されます。投稿タイプに指定できるデフォルトの値は post, page, attachment, revision, navigation の何れかです。さらにカスタム投稿タイプも使用できます。

function on_post_publish( $ID, $post ) {
    // 投稿が公開されるとき実行する処理。
}
add_action( 'publish_post', 'on_post_publish', 10, 2 );

function on_post_scheduled( $ID, $post ) {
    // 投稿の公開が予約されるときに実行する処理。
}
add_action( 'future_post', 'on_post_scheduled', 10, 2 );

private_to_published は非推奨となり、必要なら private_to_publish が使えます。

publish_future_post は非推奨となり、必要なら future_to_publish が使えます。

• アクション transition_post_status/en
• wp_transition_post_status()/en
• アクション publish_post/en
• アクション publish_page/en
• 投稿タイプ
• add_action()
• wp_update_post()
• wp_publish_post()

関数 wp_transition_post_status() は wp-includes/post.php をご覧ください。

最新英語版： WordPress Codex » Post_Status_Transitions （最新版との差分）