• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

プラグイン API

提供: WordPress Codex 日本語版
移動先: 案内検索

この項目「プラグイン API」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

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

この文章は、プラグイン開発方法の概説 (そして多くの詳細) を示した「プラグインの作成」を読んでいることを前提としています。また、この文章は、特に、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 にフィルター関数を追加してもかまいません(これにより、この投稿はブラウザに表示されるときに変更されます)。


関数リファレンス

フィルター関数
アクション関数
アクティベーション/Deactivation/アンインストール 関数


アクション

アクションは、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 コアで使用されている関数名は使用しないよう気をつけてください。詳しくは 関数名の衝突を避けるを参照してください。

関数名の衝突の回避

あなたのプラグインで使った名前と同じ名前の関数を持ったプラグインを誰かが作成済みの可能性があります。

PHP は複数の関数が同じ名前を持つことを禁止しているので、これは問題です。2つのプラグインが同名の関数を提供したり、プラグインが WordPress の関数と同名の関数を提供したりすると、ブログは機能しない可能性があります。この問題を回避する方法が2つあります。

最初の解決方法はプラグイン内のすべての関数をユニークな文字列で始まる名前にします。例えばあなたの名前が John Q. Public なら、関数を function jqp_output() {...} のように定義できます。同じイニシャルの誰かが同じことを自分のプラグインで行えますが、可能性は低いでしょう。

次の方法は — こちらの方がたぶん簡単でしょう — プラグインの機能をクラスに閉じ込めてクラスメソッドを静的に呼び出します。これは実際より複雑に聞こえますね。

先ほどの例を拡張する次のようなクラスを考えましょう:

class emailer {
  static function send( $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;
  }
}

add_action( 'publish_post', array( 'emailer', 'send' ) );

この emailer というクラスはプラグインの機能を実現する send メソッドを持ちます。

クラスの外にある add_action() 関数は、投稿が公開された時に send メソッドを呼び出すように WordPress にアクションを追加します。第2引数の配列は、クラス emailersend という静的メソッドを呼び出すことをプラグインシステムへ伝えます。

関数 send はクラス宣言によってグローバル名前空間から保護されます。send() を直接呼び出すのは不可能で、send と名付けられた他の関数がこれと衝突することはありません。もし send() を呼び出したければ、次のようなスコープ解決演算子を使う必要があります: emailer::send()

上の例は静的メソッドを利用しました。もしクラスのインスタンスを使った場合、これは動作しません。インスタンスのメソッドを呼び出すにはインスタンスを変数として渡す必要があります。これを考慮して上の例を書き換えてみましょう:

class emailer {
  function send( $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;
  }
}
$myEmailClass = new emailer();
add_action( 'publish_post', array( $myEmailClass, 'send' ) );

クラスは複雑な話題です。詳しくは クラスに関する PHP のドキュメント をお読みください。

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) 。フックによっては2つ以上の引数を関数に渡すことができるので、その場合に役に立ちます。このパラメータはリリース 1.5.1 で導入されました

Return Value 

The (optionally modified) value of the first argument passed to the filter function. In the example above, we would put the following line in the plugin file:

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

add_action('publish_post', 'email_friends');

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

インストールと有効化

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

現行のアクションフック

WordPress のアクションフックの現行リストと WordPress の以前のバージョンのリンクは プラグイン API/アクションフック一覧 を参照してください。

フィルター

フィルターは、実行中の特定のポイント、データに何かのアクション(データベースへの追加やブラウザスクリーンに送り出すなど)を行なう前にデータが通過する関数です。フィルターはデータベースとブラウザの間に位置し(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;
}

Why does this work without a loop? Because $profanities is an array, and str_ireplace loops through the array for you. The str_ireplace function is used instead of str_replace because str_ireplace is case insensitive.


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

フィルターにフックする

関数の定義が済んだら、次のステップはこの関数を 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) 。フックによっては2つ以上の引数を関数に渡すことができるので、その場合に役に立ちます。このパラメータはリリース 1.5.1 で導入されました

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

add_filter('comment_text','filter_profanity');

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

インストールと有効化

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

現行のフィルターフック

WordPress のフィルターフックの現行リストと WordPress の以前のバージョンのリンクは プラグイン API/フィルターフック一覧 を参照してください。

用例

この例では、as described by Ozh on the wp-hackers email list, for a plugin to modify (or overwrite) the default bloginfo() function. これは、コア関数の動作を変更する必要になります。

add_filter( 'bloginfo', 'mybloginfo', 1, 2 );
add_filter( 'bloginfo_url', 'mybloginfo', 1, 2 );

function mybloginfo( $result='', $show='' ) {
	switch ( $show ) {
		case 'wpurl':
			$result = SITE_URL;
			break;
		case 'template_directory':
			$result = TEMPL_DIR;
			break;
		default: 
	}
	return $result;
}

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

場合によっては、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_filteradd_action を探すことです。

プラガブル関数

ここまでに述べてきたフック(アクションやフィルター)のほかに、プラグインで WordPress 関数を上書きすることで、 WordPress の振る舞いを変更することができます。 実際のところ、プラグインでWordPress関数の小さいセットを再定義することがあります。これらは Pluggable Functions と呼ばれ、これらは wp-includes/pluggable.php で定義されています。全てのプラグインが読み込まれた時点で関数が未定義ならば、 WordPress はこれらの関数を読み込みます。より詳細は wp-settings.php のファイルを参照してください。

有効化/無効化/アンインストール

あなたのプラグインを有効化または無効化する時に実行するタスクがあるならば、 register_activation_hook register_deactivation_hook が使えます。 多くのプラグインは WordPress の現在の挙動を変更するだけなので、これらの関数は必要ないかもしれません。しかしながら、例えばあなたのプラグインを有効化する時にデフォルトのオプションを変更する必要がある場合、これらの関数を使えます。

Creating Tables with Plugins には、プラグインの最新バージョンとの間でデータベースの互換性を保つ為 register_activation_hook関数を利用した例があります。

register_uninstall_hook /en は、 WordPress のインストールページからあなたのプラグインが削除された時に、自分自身を削除した後にクリーンアップを行う為の手段を提供します。ユーザーには一時的にプラグインを無効化する理由があるわけですから、この無効化時のフックからユーザーの設定を損なうかもしれないことをしてはなりません。そのような操作はアンインストールのフックによって行います。


関連

外部資料

最新英語版: WordPress Codex » Plugin API最新版との差分