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

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

プラグイン API

提供: WordPress Codex 日本語版
2015年6月15日 (月) 18:29時点におけるMiccweb (トーク | 投稿記録)による版 (用例)

移動先: 案内検索

このページ「プラグイン API」は一部未翻訳です。和訳や日本語情報を加筆してくださる協力者を求めています

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


関数名の衝突の回避

あなたのプラグインで命名した関数と、同じ名前を持つプラグインを誰かが作成している可能性があります!


This is a problem because PHP does not allow multiple functions with the same name. If two plugins provide function with the same name, or a plugin provides a function with a name the same as a WordPress function, the blog could cease to function. There are two ways to avoid this problem.

The first solution is to prefix every function in your plugin with a unique set of characters. If your name is John Q. Public, you might declare your functions as function jqp_output() {...}. The likelihood that someone with the same initials does the same thing with their plugin is possible, but low.

The second - and possibly easier - solution is to enclose your plugin functions in a class and call the class methods statically. This sounds more complicated than it is.

Consider this class, which expands on the examples provided above:

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'));

This class, called emailer has a method send that implements the plugin functionality.

The add_action() function outside of the class adds the action to WordPress that tells it to call the send method when a post is published. The array used in the second parameter tells the plugin system to call the static method of the class 'emailer' named 'send'.

The function send is protected from the global namespace by the class declaration. It is not possible to call send() directly, and so any other function named send will not collide with this one. If you did want to call send(), you would need to use a scope resolution operator, like this: emailer::send()

The above example is for static methods. If you have an instance of a class then that won't work. To call a method of an instance you need to pass the instance as a variable. Consider the above example modified to take this into account:

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'));

Classes are a complicated subject. Read more about them in the PHP documentation on classes.



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 を探すことです。

プラガブル関数

Besides the hooks (actions and filters) described above, another way for a plugin to modify WordPress's behavior is to override WordPress functions. In fact, there is a small set of functions WordPress intends for plugins to redefine. These are called Pluggable Functions and they are defined in wp-includes/pluggable.php. WordPress loads these functions only if they are still undefined after all plugins have been loaded. For more details examine wp-settings.php file.

アクティベーション/Deactivation/アンインストール

If your plugin has tasks to complete only at activation or deactivation time, it can use register_activation_hook and register_deactivation_hook. Many plugins do not need to use these, as the plugins only modify current behavior. However, if your plugin (for example) needs to change a default option on activation, it can use these functions.

Creating Tables with Plugins has an example using the register_activation_hook function to make the database compatible with the current version of the plugin.

The register_uninstall_hook /en gives your plugin the option of cleaning up after itself when it is deleted from the WordPress installation. Users have reasons to temporarily deactivate plugins, so do not do anything from the deactivation hook that would lose any user settings. This is what the uninstall hook is for.


関連

外部資料

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