Plugin API の訳

ずーーっと前に訳していた WordPress – Plugin/API を Codex の新しいのを元に更新しました。

いずれ日本語版の Codex にもコピーするつもりです。誤字脱字誤訳、より良い訳がありましたらお知らせください。また、（たしか）原文のライセンスが GPL なんでこの訳も GPL です。

以下、Plugin API « WordPress Codex の訳です。

目次

• 1 はじめに
• 2 フック、アクション、フィルター
• 3 アクション
  • 3.1 アクション関数の作成
  • 3.2 WordPress へのフック
  • 3.3 インストールと有効化
  • 3.4 現行のアクションフック
• 4 フィルター
  • 4.1 フィルター関数の作成
  • 4.2 フィルターへのフック
  • 4.3 インストールと有効化
  • 4.4 現行のフィルターフック
• 5 アクションとフィルターの除去
• 6 デフォルトで適用されるフィルターとアクション
  • 6.1 WordPress 2.1
  • 6.2 WordPress 1.5
• 7 オーバーライド可能な関数

はじめに

このページでは WordPress のプラグイン開発者が利用可能な API （Application Programming Interface) フックとその使用方法を説明します。

この文章は、プラグイン開発方法の概説 (そして多くの詳細) が書かれている Writing a Plugin をすでに読んでいることを前提としています。また、この文章は特に、WordPress がプラグインを作動させるのに使用する「フック (hook)」 (別名「フィルター (filter)」、「アクション (action)」) のAPI について書かれています。

メモ: この情報は WordPress のバージョン 1.2 以上が対象です。バージョン 1.2 以前は、改造は「ハック」と呼ばれ、WordPress の本体コードの修正が含まれていました。

フック、アクション&フィルタ

WordPress はプラグインを WordPress 本体に “引っ張り込む (hook into)” ためのフックを提供しています。これはつまり、特定のタイミングでプラグインの関数を呼び出したり、それによってプラグインを作動させたりするためのもの です。フックには次の 2 種類があります:

1. アクション: アクションは、実行中の特定のポイントもしくは特定のイベント発生時に WordPress のコアが起動させるフックです。アクション API を使用して、これらのポイントで実行中の PHP 関数を一つ以上指定することができます。
2. フィ ルター: フィルターは、データベースに追加する前やブラウザのスクリーンに送り出す前にさまざまなタイプのテキストを改造するために WordPress が起動させるフックです。プラグインは、フィルター API を使用して、これらのタイミングで特定のタイプのテキストを改造するために一つ以上の PHP 関数の実行を指定することがきます。

場合によっては、アクションとフィルターのどちらでも同じ目的を達成することができます。例えば、プラグインに投稿のテキストを変更させるには、publish_post にアクション関数を追加してもいいですし（これにより、この投稿はデータベース保存時に変更されます）、the_content にフィルター関数を追加してもかまいません（これにより、この投稿はブラウザに表示されるときに変更されます）。

アクション

アクションは、WordPress で発生する特定のイベント、例えば投稿の公開、テーマの変更、管理画面の表示などによって始動させらせます。プラグインは PHP 関数を実行することによってこのイベントに反応することができます。このイベントへの反応には次のようなものがあります:

• データベースのデータの変更
• メールメッセージの送信
• ブラウザ画面（管理画面もしくは読者が閲覧する画面）に表示する項目の変更

実行の基本的なステップ（詳細はさらに下の章で説明します）:

1. イベント発生時に実行する PHP 関数をプラグインファイル内に作成
2. add_action を呼び出して WordPress にフック
3. プラグイン内の PHP 関数が挿入され、始動される

アクション関数の作成

プラグイン内にアクションを作成する最初のステップは、プラグインのアクション機能をもった PHP 関数を作成し、それをプラグインファイルに入れることです（プラグインファイルは wp-content/plugins ディレクトリに置きます）。例えば、新しい投稿を作成するたびに友達にメールを送信するプラグインを作成するには、次のような関数を定義します:

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

た いていのアクションでは、関数は一つのパラメータ（通常は、アクションによるが、投稿もしくはコメント ID）を受け取ります。アクションによっては複数のパラメータを取ります。詳細については（もしあれば）アクションのドキュメントか WordPress のソースコードを参照してください。パラメータ以外にも WordPress のグローバル変数にアクセスしたり、WordPress の他の関数（もしくはプラグインファイル内の関数）を呼び出したりすることができます。

注意: 他のプラグインや WordPress コアで使用されている関数名は使用しないよう気をつけてください。詳しくは Avoiding Function Name Collisions（関数名の衝突を避ける） を参照してください。

WordPress にフックする

関数の定義が済んだら、次のステップはこの関数を WordPress に”フック”、もしくは”登録（register）”します。これを行なうには、プラグインファイルのグローバルな実行スペース（？global execution space）で add_action() を呼び出します：

add_action ( 'hook_name', 'your_function_name', [priority], [accepted_args] );

引数:

• hook_name は WordPress によって提供されているアクションフックの名称で、関数がどのイベントと関連するのかを示します
• your_function_name は hook_name で設定されたイベントに続いて実行させたい関数の名称です。これは標準の PHP 関数、WordPress コアに含まれる関数、プラグインファイルで定義した関数 (上記の 'email_friends' など) です
• priority は任意の整数の引数で、特定のアクションに関連した関数の実行時の順番を指定することができます（デフォルト: 10）。数字が小さいほど先に実行され、同じ数字の場合はアクションに追加された順番で実行されます
• accepted_args は任意の整数の引数で、関数が取ることのできる引数の数を定義します (デフォルト: 1) 。フックによっては２つ以上の引数を関数に渡すことができるので、その場合に役に立ちます。このパラメータはリリース 1.5.1 で導入されました

上記の例として、プラグインファイルには次のような行が入ります:

add_action('publish_post', 'email_friends');

同様に、アクションフックからアクションを取り除くこともできます。詳しくは該当のセクションを参照してください。

インストールと有効化

アクションフックを動作させる最後のステップは、ファイルのインストールとプラグインの有効化です。作成した PHP 関数と add_action の呼び出しは両方とも一つの PHP ファイルに入れる必要があります。また、この PHP ファイルは wp-content/plugins ディレクトリにインストールする必要があります。インストール後、プラグインの管理画面を開き、有効化します。詳細はプラグインの管理を参照してください。

現行のアクションフック

WordPress のアクションフックの現行リストと WordPress の以前のバージョンのリンクは Plugin API/Action Reference を参照してください。

フィルター

フィ ルターは、実行中の特定のポイント、データに何かのアクション（データベースへの追加やブラウザスクリーンに送り出すなど）を行なう前にデータが通過する 関数です。フィルターはデータベースとブラウザの間に位置し（WordPress がページを生成するとき）、ブラウザとデータベースの間にも位置します（WordPress が新しい投稿やコメントをデータベースに追加するとき）。WordPress のほとんど入力と出力は最低ひとつはフィルターを通過します。WordPress はデフォルトでいくつかのフィルタリングを行なっていて、プラグインで追加することができます。

WordPress にフィルタを追加する基本的（詳細はさらに下で説明）な手順は:

1. データをフィルタリングする関数を作成
2. add_filter を呼び出して WordPress のフィルタにフック
3. 作成した PHP 関数をプラグインファイルに入れ、有効化

フィルター関数の作成

フィルター関数は、未変更のデータを入力として受け取り、変更したデータを返します（場合によっては、そのデータが削除されたり無視されたりするこ とを示すために null 値になります）。データがフィルタによって変更されていない場合はオリジナルのデータが返され、必要な場合はその後のプラグインでその値を変更を続けるこ とができます。

さて、プラグイン内にフィルタを作成する最初のステップはフィルタリングを行なう PHP 関数を作成することです。そしてこの関数をプラグインファイル（プラグインファイルは wp-content/plugins ディレクトリに入れます）に入れます。例えば、投稿やコメントにののしり言葉を載せないようにするには、禁止語句のリストを持ったグローバル変数を定義し、次の PHP 関数を作成します:

function filter_profanity($content) {
    global $profanities;
    foreach($profanities as $profanity) {
        $content=str_ireplace($profanity,'{censored}',$content);
    }
    return $content;
}

注意: 他のプラグインや WordPress コアで使用されている関数名は使用しないよう気をつけてください。詳しくは Avoiding Function Name Collisions（関数名の衝突を避ける） を参照してください。

フィルターにフックする

関数の定義が済んだら、次のステップはこの関数を WordPress に”フック”、もしくは”登録（register）”します。これを行なうには、プラグインファイルのグローバルな実行スペース（？global execution space）で add_filter を呼び出します:

add_filter('hook_name', 'your_filter', [priority], [accepted_args]);

引数:

• hook_name は WordPress によって提供されているフィルターフックの名称で、フィルターがいつ適用されるのかを定義します
• your_filter はフィルタリングに使用する関数名です。これは標準の PHP 関数、WordPress コアに含まれる関数、プラグインファイルで定義した関数です
• priority は任意の整数の引数で、特定のフィルタに関連した関数の実行時の順番を指定することができます（デフォルト: 10）。数字が小さいほど先に実行され、同じ数字の場合はフィルターに追加された順番で実行されます
• accepted_args は任意の整数の引数で、関数が取ることのできる引数を定義します (デフォルト: 1) 。フックによっては２つ以上の引数を関数に渡すことができるので、その場合に役に立ちます。このパラメータはリリース 1.5.1 で導入されました

上記の例として、プラグインファイルの主要実行セクションには次のような行が入り、コメントからののしり言葉をフィルタリングします:

add_filter('comment_text','filter_profanity');

また、WordPress の関数 remove_filter() を使用して、フィルターフックからフィルターを取り除くこともできます。詳しくは アクションとフィルターを取り除く を参照してください。

インストールと有効化

フィルターフックを動作させる最後のステップは、ファイルのインストールとプラグインの有効化です。作成した PHP 関数と add_filter の呼び出しは両方とも一つの PHP ファイルに入れる必要があります。また、この PHP ファイルは wp-content/plugins ディレクトリにインストールする必要があります。インストール後、プラグインの管理画面を開き有効化します。詳細はプラグインの管理を参照してください。

現行のフィルターフック

WordPress のアクションフックの現行リストと WordPress の以前のバージョンのリンクは Plugin API/Action Reference を参照してください。

アクションとフィルターの除去

場合によっては、WordPress に組み込まれていたり他のプラグインで追加されたりしているアクションやフィルターの一つをプラグインで無効にする必要があるかもしれません。これは remove_filter('filter_hook','filter_function') もしくは remove_action('action_hook','action_function') を呼び出すことによって可能です。

例えば、remove_action('publish_post','generic_ping'); は、新規投稿作成時に ping （トラックバック、ピンバック）を送信しないようにします。

もしデフォルトの 10 以外のプライオリティでフックを登録してる場合は、remove_action() への呼び出しでもプライオリティを設定するよう注意してください。また、通常は、WordPress や他のプラグインのソースコードを見て確認し、そのアクションやフィルターがどんなもので何をしているのか分からなければ取り除かないほうがいいでしょう。

デフォルトで適用されるフィルターとアクション

WordPress でデフォルトで有効になっているフィルターやアクションを見つける一番信頼できる方法は WordPress のコアファイル内で add_filter と add_action を探すことです。

WordPress 2.1

WordPress 2.1 ではデフォルトフィルターとアクションのほとんどが wp-includes/default-filters.php に追加されています。その他に次のファイルに含まれています。

• wp-admin/admin-ajax.php
• wp-admin/admin-functions.php
• wp-admin/custom-header.php
• wp-admin/edit.php
• wp-admin/index.php
• wp-admin/options-permalink.php
• wp-admin/upload-functions.php
• wp-admin/upload.php
• wp-includes/bookmark.php
• wp-includes/general-template.php
• wp-includes/kses.php
• wp-includes/plugin.php
• wp-includes/rewrite.php
• wp-includes/template-loader.php
• wp-includes/theme.php

WordPress 1.5

WordPress 1.5 ではデフォルトフィルターとアクションのほとんどのが wp-includes/default-filters.php に追加されています。

オーバーライドできる関数

上記のフック (アクションとフィルター) の他に、プラグインで WordPress の挙動を変更するもう一つの方法が WordPress 関数のオーバーライドです。実際、プラグインでの再定義を意図した関数がいくつかあります。この実行ため、WordPress はこれらの関数のうち、すべてのプラグインの読み込み後も定義されていない関数だけを読み込みます。

これらの関数は wp-includes/pluggable.php ファイルで定義されています。次のリストはバージョン 2.1 現在のもので、いくつかは 関数リファレンス（Function Reference） で説明を見つけることができます:

• set_current_user
• wp_set_current_user
• wp_get_current_user
• get_currentuserinfo
• get_userdata
• update_user_cache
• get_userdatabylogin
• wp_mail
• wp_login
• is_user_logged_in
• auth_redirect
• check_admin_referer
• wp_redirect
• wp_get_cookie_login
• wp_setcookie
• wp_clearcookie
• wp_notify_postauthor
• wp_notify_moderator
• wp_new_user_notification
• wp_verify_nonce
• wp_create_nonce
• wp_salt
• wp_hash