「関数リファレンス/add action」の版間の差分

2014年3月31日 (月) 09:58時点における版

説明

特定のアクションに関数をフックします。

この関数は add_filter() のエイリアスです。

アクションフックの一覧についてはアクションフック一覧をご覧ください。アクションは（通常は）WordPress コアが do_action() を呼び出すときにトリガーされます。

使い方

<?php add_action( $hook, $function_to_add, $priority, $accepted_args ); ?>

パラメータ

$hook

（文字列） （必須） $function_to_add がフックされるアクション名。アクションフック名一に覧ついては プラグイン API/アクションフック一覧 を参照。テーマまたはプラグインファイル内のアクション名も指定できる。または特別なタグ "all" を使えば、すべてのフックで関数が呼び出される。

初期値： なし

$function_to_add

（コールバック） （必須） フックする関数名。注: 'callback' タイプとして PHP ドキュメンテーションに掲載されている文字列形式構文のみが有効

初期値： なし

$priority

（整数） （オプション） 特定のアクションに関連づけられている関数が実行される優先順序を指定する。少ない数であれば早く実行され、同じ数の優先度である関数はアクションに追加された順序で実行される。

初期値： 10

$accepted_args

（整数） （オプション） フックした関数が受け入れられる引数の数。WordPress 1.5.1 以降では、フックした関数は、対応する do_action() あるいは apply_filters() が実行される時に、余分に引数を取ることができます。例えば、アクション comment_id_not_found は、これにフックする関数に、リクエストされたコメントの ID を渡すことができます。

初期値： 1

戻り値

(boolean) 

常に true。

用例

単純なフック

ブログに投稿したときに、メールで友人に知らせます。

function email_friends( $post_ID )  {
   $friends = 'bob@example.org, susie@example.org';
   wp_mail( $friends, "sally's blog updated", 'I just put something on my blog: http://blog.example.com' );

   return $post_ID;
}
add_action( 'publish_post', 'email_friends' );

利用できる引数

フックした関数は、オプションとしてアクションコールから引数を受け入れることができます（引数が渡されるように設定されている場合）。以下の単純化したサンプルでは、echo_comment_id 関数は $comment_id 引数を受け取ります。これは、do_action() コールを実行する際に comment_id_not_found を使っている場合に自動的に渡される引数です。

function echo_comment_id( $comment_id ) {
   echo 'Comment ID ' . $comment_id . ' could not be found';
}
add_action( 'comment_id_not_found', 'echo_comment_id', 10, 1 );

注

フックしたい関数の引数の数および名称を見つけたいときは、コアのコード内で一致する do_action() コールを探します。たとえば、'save_post' 関数にフックしたいときは、post.php で次の行を探しましょう。

<?php do_action( 'save_post', $post_ID, $post, $update ); ?>

add_actionの呼び出しは次のようになります。

<?php add_action( 'save_post', 'my_save_post', 10, 3 ); ?>

そして関数は以下のようになります。

function my_save_post( $post_ID, $post, $update ) {
   // do stuff here
}

add_action をクラス内で使う

add_action フックをクラスを使って構築されたプラグインやテーマ内で使うには、add_action コール内にそのクラスの関数名とともに $this を追加してください。以下はその例です。

class MyPluginClass {
    public function __construct() {
         //add your actions to the constructor!
         add_action( 'save_post', array( $this, 'myplugin_save_posts' ) );
    }
    
    public function myplugin_save_posts() {
         //do stuff here...
    }
}

更新履歴

1.2.0 以降

ソースファイル

add_action() は wp-includes/plugin.php にあります。

関連資料

アクション: has_action(), add_action(), do_action(), do_action_ref_array(), did_action(), remove_action(), remove_all_actions()

最新英語版： WordPress Codex » Function Reference/add_action （最新版との差分）