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

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

「プラグイン API」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(アクション関数の作成: 新章追加)
(WordPress にフックする: 最新マージ)
165行目: 165行目:
 
</div>
 
</div>
  
関数の定義が済んだら、次のステップはこの関数を WordPress に”フック”、もしくは”登録(register)”します。これを行なうには、プラグインファイルのグローバルな実行スペース(?global execution space)で <code>add_action()</code> を呼び出します:
+
関数の定義が済んだら、次のステップはこの関数を WordPress に”フック”、もしくは”登録(register)”します。これを行なうには、プラグインファイルのグローバルな実行スペース(?global execution space)で <code>[[Function Reference/add_action|add_action()]]</code> を呼び出します:
  
 
<pre>
 
<pre>
 
  add_action ( 'hook_name', 'your_function_name', [priority], [accepted_args] );
 
  add_action ( 'hook_name', 'your_function_name', [priority], [accepted_args] );
 
 
</pre>
 
</pre>
  
 
引数:  
 
引数:  
* <code>hook_name</code> WordPress によって提供されているアクションフックの名称で、関数がどのイベントと関連するのかを示します
+
; <tt>hook_name</tt> :
* <code>your_function_name</code> <code>hook_name</code> で設定されたイベントに続いて実行させたい関数の名称です。これは標準の PHP 関数、WordPress コアに含まれる関数、プラグインファイルで定義した関数 (上記の <code>'email_friends'</code> など) です
+
WordPress によって提供されているアクションフックの名称で、関数がどのイベントと関連するのかを示します
* <code>priority</code> は任意の整数の引数で、特定のアクションに関連した関数の実行時の順番を指定することができます(デフォルト: 10)。数字が小さいほど先に実行され、同じ数字の場合はアクションに追加された順番で実行されます
+
 
* <code>accepted_args</code> は任意の整数の引数で、関数が取ることのできる引数の数を定義します (デフォルト: 1) 。フックによっては2つ以上の引数を関数に渡すことができるので、その場合に役に立ちます。このパラメータはリリース 1.5.1 で導入されました
+
; <tt>your_function_name</tt> :
 +
<code>hook_name</code> で設定されたイベントに続いて実行させたい関数の名称です。これは標準の PHP 関数、WordPress コアに含まれる関数、プラグインファイルで定義した関数 (上記の <code>'email_friends'</code> など) です
 +
 
 +
; <tt>priority</tt> :
 +
任意の整数の引数で、特定のアクションに関連した関数の実行時の順番を指定することができます(デフォルト: 10)。数字が小さいほど先に実行され、同じ数字の場合はアクションに追加された順番で実行されます
 +
 
 +
; <tt>accepted_args</tt> :
 +
任意の整数の引数で、関数が取ることのできる引数の数を定義します (デフォルト: 1) 。フックによっては2つ以上の引数を関数に渡すことができるので、その場合に役に立ちます。このパラメータはリリース 1.5.1 で導入されました
 +
 
 +
; <tt>Return Value</tt> :
 +
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:
  
 
上記の例として、プラグインファイルには次のような行が入ります:
 
上記の例として、プラグインファイルには次のような行が入ります:
187行目: 197行目:
  
 
<div id="Install_and_Activate">
 
<div id="Install_and_Activate">
 +
 
=== インストールと有効化 ===
 
=== インストールと有効化 ===
 
</div>
 
</div>

2015年5月15日 (金) 14:20時点における版

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


Avoiding Function Name Collisions

It is possible that someone has created a plugin with a function named the same as one in your plugin!

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;
}

注意: 他のプラグインや 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/フィルターフック一覧 を参照してください。

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

場合によっては、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 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 現在のもので、いくつかは 関数リファレンス で説明を見つけることができます:

  • 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

外部資料

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