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

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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(冒頭のみ和訳、taiさんの和訳へリンク!)
(taiさんによる翻訳 [http://wp.tekapo.com/2008/01/30/wordpress-plugin-api/ わーどぷれすっ! » Plugin API の訳]を転載(許可受領)(和訳済み部分も差し替え)、リンク微調整)
1行目: 1行目:
'''taiさんのサイトで和訳されています: [http://wp.tekapo.com/2008/01/30/wordpress-plugin-api/ わーどぷれすっ! » Plugin API の訳]'''
 
 
 
<div id="Introduction">
 
<div id="Introduction">
 
== はじめに ==
 
== はじめに ==
 
</div>
 
</div>
  
このページでは、[[:ja:Plugins|WordPress プラグイン]]の開発者が利用できる API(Application Programming Interface)フックと、その使い方について説明します。
+
このページでは [[プラグイン|WordPress のプラグイン]]開発者が利用可能な API (Application Programming Interface) フックとその使用方法を説明します。
  
プラグインの開発方法の概要(および多くの詳細)については、 [[:en:Writing a Plugin|「Writing a Plugin」]] を読んであることを前提としています。<br />
+
この文章は、プラグイン開発方法の概説 (そして多くの詳細) が書かれている [[Writing a Plugin]]/[[:en:Writing a Plugin|en]] をすでに読んでいることを前提としています。また、この文章は特に、WordPress がプラグインを作動させるのに使用する「フック (hook)」 (別名「フィルター (filter)」、「アクション (action)」) のAPI について書かれています。
本ページでは、WordPress がプラグインを動かすために使う「フック(Hook)」の API(「フィルター(Filter)」「アクション(Action)」)について、具体的に説明していきます。
+
  
注: 以下の情報は WordPress バージョン 1.2 以上が対象です。バージョン 1.1.x 以前では、改造のことを「ハック(hacks)」といい、WordPress 本体のソースコードの編集も伴いました。
+
メモ: この情報は WordPress のバージョン 1.2 以上が対象です。バージョン 1.2 以前は、改造は「ハック」と呼ばれ、WordPress の本体コードの修正が含まれていました。
  
 
<div id="Hooks.2C_Actions_and_Filters">
 
<div id="Hooks.2C_Actions_and_Filters">
== フック(Hook)・アクション(Action)・フィルター(Filter) ==
+
== フック、アクション&フィルタ ==
 
</div>
 
</div>
  
フックとは、プラグインを WordPress 本体に「引っ張り込む・接続(hook into)」できるように、WordPress が用意している仕組みです。プラグインの関数を特定のタイミングで呼び出すことによって、プラグインを動作させることができます。フックには次の 2種類があります。
+
WordPress はプラグインを WordPress 本体に “引っ張り込む (hook into)” ためのフックを提供しています。これはつまり、特定のタイミングでプラグインの関数を呼び出したり、それによってプラグインを作動させたりするためのものです。フックには次の 2 種類があります:
  
# [[#Actions|Actions]]: Actions are the hooks that the WordPress core launches at specific points during execution, or when specific events occur. Your plugin can specify that one or more of its PHP functions are executed at these points, using the Action API.
+
# [[#Actions|アクション]]: アクションは、実行中の特定のポイントもしくは特定のイベント発生時に WordPress のコアが起動させるフックです。アクション API を使用して、これらのポイントで実行中の PHP 関数を一つ以上指定することができます。
# [[#Filters|Filters]]: Filters are the hooks that WordPress launches to modify text of various types before adding it to the database or sending it to the browser screen. Your plugin can specify that one or more of its PHP functions is executed to modify specific types of text at these times, using the Filter API.
+
# [[#Filters|フィルター]]: フィルターは、データベースに追加する前やブラウザのスクリーンに送り出す前にさまざまなタイプのテキストを改造するために WordPress が起動させるフックです。プラグインは、フィルター API を使用して、これらのタイミングで特定のタイプのテキストを改造するために一つ以上の PHP 関数の実行を指定することがきます。
  
You can sometimes accomplish the same goal with either an action or a filter.  For example, if you want your plugin to change the text of a post, you might add an action function to <tt>publish_post</tt> (so the post is modified as it is saved to the database), or a filter function to <tt>the_content</tt> (so the post is modified as it is displayed in the browser screen).
+
場合によっては、アクションとフィルターのどちらでも同じ目的を達成することができます。例えば、プラグインに投稿のテキストを変更させるには、<code>publish_post</code> にアクション関数を追加してもいいですし(これにより、この投稿はデータベース保存時に変更されます)、<code>the_content</code> にフィルター関数を追加してもかまいません(これにより、この投稿はブラウザに表示されるときに変更されます)。
  
 
<div id="Actions">
 
<div id="Actions">
== アクション(Action) ==
+
== アクション ==
 
</div>
 
</div>
  
'''Actions''' are triggered by specific events that take place in WordPress, such as publishing a post, changing themes, or displaying a page of the admin panel. Your plugin can respond to the event by executing a PHP function, which might do one or more of the following:
+
'''アクション'''は、WordPress で発生する特定のイベント、例えば投稿の公開、テーマの変更、管理画面の表示などによって始動させらせます。プラグインは PHP 関数を実行することによってこのイベントに反応することができます。このイベントへの反応には次のようなものがあります:
* Modify database data
+
* データベースのデータの変更
* Send an email message
+
* メールメッセージの送信
* Modify what is displayed in the browser screen (admin or end-user)
+
* ブラウザ画面(管理画面もしくは読者が閲覧する画面)に表示する項目の変更
  
The basic steps to making this happen (described in more detail below) are:
+
実行の基本的なステップ(詳細はさらに下の章で説明します):
# Create the PHP function that should execute when the event occurs, in your plugin file.
+
# イベント発生時に実行する PHP 関数をプラグインファイル内に作成
# Hook to the action in WordPress, by calling <tt>add_action</tt>
+
# <code>add_action</code> を呼び出して WordPress にフック
# Put your PHP function in a plugin file, and activate it.
+
# プラグイン内の PHP 関数が挿入され、始動される
  
 
<div id="Create_an_Action_Function">
 
<div id="Create_an_Action_Function">
=== Create an Action Function ===
+
=== アクション関数の作成 ===
 
</div>
 
</div>
  
The first step in creating an action in your plugin is to create a PHP function with the action functionality of your plugin, and put it in your plugin file (your plugin file must go into the ''wp-content/plugins'' directory). For example, if you want your friends to get an email message whenever you create a new post, you might define the following function:
+
プラグイン内にアクションを作成する最初のステップは、プラグインのアクション機能をもった PHP 関数を作成し、それをプラグインファイルに入れることです(プラグインファイルは ''<code>wp-content/plugins</code>'' ディレクトリに置きます)。例えば、新しい投稿を作成するたびに友達にメールを送信するプラグインを作成するには、次のような関数を定義します:
  
 
<pre>
 
<pre>
52行目: 49行目:
 
</pre>
 
</pre>
  
For most actions, your function should accept a single parameter (usually the post or comment ID, depending on the action). Some actions take more than one parameter -- check the documentation for the action (if available) or the WordPress source code for more information. Besides the one parameter, you can also access the global variables of WordPress, and call other WordPress functions (or functions in your plugin file).
+
たいていのアクションでは、関数は一つのパラメータ(通常は、アクションによるが、投稿もしくはコメント ID)を受け取ります。アクションによっては複数のパラメータを取ります。詳細については(もしあれば)アクションのドキュメントか WordPress のソースコードを参照してください。パラメータ以外にも WordPress のグローバル変数にアクセスしたり、WordPress の他の関数(もしくはプラグインファイル内の関数)を呼び出したりすることができます。
  
'''NOTE''': Keep in mind that other plugins or the WordPress core may already be using the function name you have thought of. See [[:en:Writing a Plugin#Avoiding Function Name Collisions|Avoiding Function Name Collisions]] for more information.
+
'''注意''': 他のプラグインや WordPress コアで使用されている関数名は使用しないよう気をつけてください。詳しくは [[Writing a Plugin#Avoiding Function Name Collisions|Avoiding Function Name Collisions(関数名の衝突を避ける)]]/[[:en:Writing a Plugin#Avoiding Function Name Collisions|en]] を参照してください。
  
 
<div id="Hook_to_WordPress">
 
<div id="Hook_to_WordPress">
=== Hook to WordPress ===
+
=== WordPress にフックする ===
 
</div>
 
</div>
  
After your function is defined, the next step is to "hook" or register it with WordPress. To do this, call <tt>add_action()</tt> in the global execution space of your plugin file:
+
関数の定義が済んだら、次のステップはこの関数を WordPress に”フック”、もしくは”登録(register)”します。これを行なうには、プラグインファイルのグローバルな実行スペース(?global execution space)で <code>add_action()</code> を呼び出します:
  
 
<pre>
 
<pre>
67行目: 64行目:
 
</pre>
 
</pre>
  
where:  
+
引数:  
* <tt>hook_name</tt> is the name of an action hook provided by WordPress, that tells what event your function should be associated with.
+
* <code>hook_name</code> WordPress によって提供されているアクションフックの名称で、関数がどのイベントと関連するのかを示します
* <tt>your_function_name</tt> is the name of the function that you want to be executed following the event specified by <tt>hook_name</tt>. This can be a standard php function, a function present in the WordPress core, or a function defined by you in the plugin file (such as <tt>'email_friends'</tt> defined above).
+
* <code>your_function_name</code> <code>hook_name</code> で設定されたイベントに続いて実行させたい関数の名称です。これは標準の PHP 関数、WordPress コアに含まれる関数、プラグインファイルで定義した関数 (上記の <code>'email_friends'</code> など) です
* <tt>priority</tt> is an optional integer argument that can be used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.
+
* <code>priority</code> は任意の整数の引数で、特定のアクションに関連した関数の実行時の順番を指定することができます(デフォルト: 10)。数字が小さいほど先に実行され、同じ数字の場合はアクションに追加された順番で実行されます
* <tt>accepted_args</tt> is an optional integer argument defining how many arguments your function can accept (default 1), useful because some hooks can pass more than one argument to your function. This parameter is new in release 1.5.1.
+
* <code>accepted_args</code> は任意の整数の引数で、関数が取ることのできる引数の数を定義します (デフォルト: 1) 。フックによっては2つ以上の引数を関数に渡すことができるので、その場合に役に立ちます。このパラメータはリリース 1.5.1 で導入されました
  
In the example above, we would put the following line in the plugin file:
+
上記の例として、プラグインファイルには次のような行が入ります:
  
 
<pre>
 
<pre>
79行目: 76行目:
 
</pre>
 
</pre>
  
Likewise, you can also [[#Removing Actions and Filters|Remove Actions]] from action hooks.  See that section for details.
+
同様に、アクションフックから[[#Removing Actions and Filters|アクションを取り除く]]こともできます。詳しくは該当のセクションを参照してください。
  
 
<div id="Install_and_Activate">
 
<div id="Install_and_Activate">
=== Install and Activate ===
+
=== インストールと有効化 ===
 
</div>
 
</div>
  
The last step in getting your action hook to work is to install the file and activate the plugin. The PHP function you wrote and the <tt>add_action</tt> call must go into a PHP file together, and the PHP file must be installed in the ''wp-content/plugins'' directory. Once it is installed, you will need to visit the admin section of WordPress and activate your plugin; see [[:ja:Managing Plugins|Managing Plugins]] for more details.
+
アクションフックを動作させる最後のステップは、ファイルのインストールとプラグインの有効化です。作成した PHP 関数と <code>add_action</code> の呼び出しは両方とも一つの PHP ファイルに入れる必要があります。また、この PHP ファイルは ''<code>wp-content/plugins</code>'' ディレクトリにインストールする必要があります。インストール後、プラグインの管理画面を開き、有効化します。詳細は[[プラグインの管理]]を参照してください。
  
 
<div id="Current_Hooks_For_Actions">
 
<div id="Current_Hooks_For_Actions">
=== Current Hooks For Actions ===
+
=== 現行のアクションフック ===
 
</div>
 
</div>
  
See [[:en:Plugin API/Action Reference|Plugin API/Action Reference]] for a current list of action hooks in WordPress, and links to previous versions of WordPress.
+
WordPress のアクションフックの現行リストと WordPress の以前のバージョンのリンクは [[プラグイン API/アクションフック一覧]] を参照してください。
  
 
<div id="Filters">
 
<div id="Filters">
== フィルター(Filter) ==
+
== フィルター ==
 
</div>
 
</div>
  
'''Filters''' are functions that WordPress passes data through, at certain points in execution, just before taking some action with the data (such as adding it to the database or sending it to the browser screen). Filters sit between the database and the browser (when WordPress is generating pages), and between the browser and the database (when WordPress is adding new posts and comments to the database); most input and output in WordPress passes through at least one filter. WordPress does some  filtering by default, and your plugin can add its own filtering.
+
'''フィルター'''は、実行中の特定のポイント、データに何かのアクション(データベースへの追加やブラウザスクリーンに送り出すなど)を行なう前にデータが通過する関数です。フィルターはデータベースとブラウザの間に位置し(WordPress がページを生成するとき)、ブラウザとデータベースの間にも位置します(WordPress が新しい投稿やコメントをデータベースに追加するとき)。WordPress のほとんど入力と出力は最低ひとつはフィルターを通過します。WordPress はデフォルトでいくつかのフィルタリングを行なっていて、プラグインで追加することができます。
  
The basic steps to adding your own filters to WordPress (described in more detail below) are:
+
WordPress にフィルタを追加する基本的(詳細はさらに下で説明)な手順は:
# Create the PHP function that filters the data.
+
# データをフィルタリングする関数を作成
# Hook to the filter in WordPress, by calling <tt>add_filter</tt>
+
# <code>add_filter</code> を呼び出して WordPress のフィルタにフック
# Put your PHP function in a plugin file, and activate it.
+
# 作成した PHP 関数をプラグインファイルに入れ、有効化
  
 
<div id="Create_a_Filter_Function">
 
<div id="Create_a_Filter_Function">
=== Create a Filter Function ===
+
=== フィルター関数の作成 ===
 
</div>
 
</div>
  
A filter function takes as input the unmodified data, and returns modified data (or in some cases, a null value to indicate the data should be deleted or disregarded). If the data is not modified by your filter, then the original data must be returned so that subsequent plugins can continue to modify the value if necessary.
+
フィルター関数は、未変更のデータを入力として受け取り、変更したデータを返します(場合によっては、そのデータが削除されたり無視されたりすることを示すために null 値になります)。データがフィルタによって変更されていない場合はオリジナルのデータが返され、必要な場合はその後のプラグインでその値を変更を続けることができます。
  
So, the first step in creating a filter in your plugin is to create a PHP function to do the filtering, and put it in your plugin file (your plugin file must go into the ''wp-content/plugins'' directory). For example, if you want to make sure that your posts and comments contain no profanity, you might define a global variable with a list of forbidden words, and then create the following PHP function:  
+
さて、プラグイン内にフィルタを作成する最初のステップはフィルタリングを行なう PHP 関数を作成することです。そしてこの関数をプラグインファイル(プラグインファイルは ''<code>wp-content/plugins</code>'' ディレクトリに入れます)に入れます。例えば、投稿やコメントにののしり言葉を載せないようにするには、禁止語句のリストを持ったグローバル変数を定義し、次の PHP 関数を作成します:
  
 
<pre>
 
<pre>
122行目: 119行目:
 
</pre>
 
</pre>
  
'''NOTE''': Keep in mind that other plugins or the WordPress core may already be using the function name you have thought of. See [[:en:Writing a Plugin#Avoiding Function Name Collisions|Avoiding Function Name Collisions]] for more information.
+
'''注意''': 他のプラグインや WordPress コアで使用されている関数名は使用しないよう気をつけてください。詳しくは [[Writing a Plugin#Avoiding Function Name Collisions|Avoiding Function Name Collisions(関数名の衝突を避ける)]]/[[:en:Writing a Plugin#Avoiding Function Name Collisions|en]] を参照してください。
  
 
<div id="Hook_in_your_Filter">
 
<div id="Hook_in_your_Filter">
=== Hook in your Filter ===
+
=== フィルターにフックする ===
 
</div>
 
</div>
  
After your function is defined, the next step is to "hook" or register it with WordPress. To do this, call <tt>add_filter</tt> in the global execution space of your plugin file:
+
関数の定義が済んだら、次のステップはこの関数を WordPress に”フック”、もしくは”登録(register)”します。これを行なうには、プラグインファイルのグローバルな実行スペース(?global execution space)で <code>add_filter</code> を呼び出します:
  
 
<pre>
 
<pre>
 
add_filter('hook_name', 'your_filter', [priority], [accepted_args]);
 
add_filter('hook_name', 'your_filter', [priority], [accepted_args]);
 
 
</pre>
 
</pre>
  
where:
+
引数:
* <tt>hook_name</tt> is the name of a filter hook provided by WordPress, which defines when your filter should be applied.
+
* <code>hook_name</code> WordPress によって提供されているフィルターフックの名称で、フィルターがいつ適用されるのかを定義します
* <tt>your_filter</tt> is the name of the function that you want to use for filtering. This can be a standard PHP function, a function present in the WordPress core, or a function defined by you in the plugin file.
+
* <code>your_filter</code> はフィルタリングに使用する関数名です。これは標準の PHP 関数、WordPress コアに含まれる関数、プラグインファイルで定義した関数です
* <tt>priority</tt> is an optional integer argument that can be used to specify the order in which the functions associated with a particular filter are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the filter.
+
* <code>priority</code> は任意の整数の引数で、特定のフィルタに関連した関数の実行時の順番を指定することができます(デフォルト: 10)。数字が小さいほど先に実行され、同じ数字の場合はフィルターに追加された順番で実行されます
* <tt>accepted_args</tt> is an optional integer argument defining how many arguments your function can accept (default 1), useful because some hooks can pass more than one argument to your function. This parameter is new in release 1.5.1.
+
* <code>accepted_args</code> は任意の整数の引数で、関数が取ることのできる引数を定義します (デフォルト: 1) 。フックによっては2つ以上の引数を関数に渡すことができるので、その場合に役に立ちます。このパラメータはリリース 1.5.1 で導入されました
  
In the example above, we would put the following in the main executing section of the plugin file, to tell WordPress to filter comments for profanity:
+
上記の例として、プラグインファイルの主要実行セクションには次のような行が入り、コメントからののしり言葉をフィルタリングします:
  
 
<pre>
 
<pre>
147行目: 143行目:
 
</pre>
 
</pre>
  
You can also remove filters from filter hooks using the WordPress function <tt>remove_filter()</tt>.  See [[#Removing Actions and Filters|Removing Actions and Filters]].
+
また、WordPress の関数 <code>remove_filter()</code> を使用して、フィルターフックからフィルターを取り除くこともできます。詳しくは [[#Removing Actions and Filters|アクションとフィルターを取り除く]] を参照してください。
  
 
<div id="Install_and_Activate">
 
<div id="Install_and_Activate">
=== Install and Activate ===
+
=== インストールと有効化 ===
 
</div>
 
</div>
  
The last step in getting your filter hook to work is to install the file and activate the plugin. The PHP function you wrote and the <tt>add_filter</tt> call must go into a PHP file together, and the PHP file must be installed in the ''wp-content/plugins'' directory. Once it is installed, you will need to visit the admin section of WordPress and activate your plugin; see [[:ja:Managing Plugins|Managing Plugins]] for more details.
+
フィルターフックを動作させる最後のステップは、ファイルのインストールとプラグインの有効化です。作成した PHP 関数と <code>add_filter</code> の呼び出しは両方とも一つの PHP ファイルに入れる必要があります。また、この PHP ファイルは ''<code>wp-content/plugins</code>'' ディレクトリにインストールする必要があります。インストール後、プラグインの管理画面を開き有効化します。詳細は[[プラグインの管理]]を参照してください。
  
 
<div id="Current_Hooks_for_Filters">
 
<div id="Current_Hooks_for_Filters">
=== Current Hooks for Filters ===
+
=== 現行のフィルターフック ===
 
</div>
 
</div>
  
See [[:en:Plugin API/Filter Reference|Plugin API/Filter Reference]] for a current list of filter hooks in WordPress, and links to previous versions of WordPress.
+
WordPress のフィルターフックの現行リストと WordPress の以前のバージョンのリンクは [[プラグイン API/フィルターフック一覧]] を参照してください。
  
 
<div id="Removing_Actions_and_Filters">
 
<div id="Removing_Actions_and_Filters">
== Removing Actions and Filters ==
+
== アクションとフィルターの除去 ==
 
</div>
 
</div>
  
In some cases, you may find that you want your plugin to disable one of the actions or filters built into WordPress, or added by another plugin. You can do that by calling <tt>remove_filter('filter_hook','filter_function')</tt> or <tt>remove_action('action_hook','action_function')</tt>.
+
場合によっては、WordPress に組み込まれていたり他のプラグインで追加されたりしているアクションやフィルターの一つをプラグインで無効にする必要があるかもしれません。これは
 +
<code>remove_filter(’filter_hook’,'filter_function’)</code> もしくは <code>remove_action(’action_hook’,'action_function’)</code> を呼び出すことによって可能です。
  
For example, <tt>remove_action('publish_post','generic_ping');</tt> would prevent your weblog from sending pings whenever a new post is created.
+
例えば、<code>remove_action(’publish_post’,'generic_ping’);</code> は、新規投稿作成時に ping (トラックバック、ピンバック)を送信しないようにします。
  
Note that if a hook was registered using a priority other than the default of 10, then you must also specify the priority in the call to <tt>remove_action()</tt>. Also note that in general, you shouldn't remove anything unless you know what it does and why it does it -- check the WordPress or other plugin source code to be sure.
+
もしデフォルトの 10 以外のプライオリティでフックを登録してる場合は、<code>remove_action()</code> への呼び出しでもプライオリティを設定するよう注意してください。また、通常は、WordPress や他のプラグインのソースコードを見て確認し、そのアクションやフィルターがどんなもので何をしているのか分からなければ取り除かないほうがいいでしょう。
  
 
<div id="Filters_and_Actions_Applied_By_Default">
 
<div id="Filters_and_Actions_Applied_By_Default">
== Filters and Actions Applied By Default ==
+
== デフォルトで適用されるフィルターとアクション ==
 
</div>
 
</div>
  
The most reliable way to find the filters and actions enabled by default in WordPress is to search for <tt>add_filter</tt> and <tt>add_action</tt> in the WordPress core files.
+
WordPress でデフォルトで有効になっているフィルターやアクションを見つける一番信頼できる方法は WordPress のコアファイル内で <code>add_filter</code> <code>add_action</code> を探すことです。
  
 
=== WordPress 2.1 ===
 
=== WordPress 2.1 ===
  
In WordPress 2.1, most of the default filters and actions are added from the file <tt>wp-includes/default-filters.php</tt>. A few others are in the following files:
+
[[Version 2.1|WordPress 2.1]] ではデフォルトフィルターとアクションのほとんどが <code>wp-includes/default-filters.php</code> に追加されています。その他に次のファイルに含まれています。
* <tt>wp-admin/admin-ajax.php</tt>
+
* <code>wp-admin/admin-ajax.php</code>
* <tt>wp-admin/admin-functions.php</tt>
+
* <code>wp-admin/admin-functions.php</code>
* <tt>wp-admin/custom-header.php</tt>
+
* <code>wp-admin/custom-header.php</code>
* <tt>wp-admin/edit.php</tt>
+
* <code>wp-admin/edit.php</code>
* <tt>wp-admin/index.php</tt>
+
* <code>wp-admin/index.php</code>
* <tt>wp-admin/options-permalink.php</tt>
+
* <code>wp-admin/options-permalink.php</code>
* <tt>wp-admin/upload-functions.php</tt>
+
* <code>wp-admin/upload-functions.php</code>
* <tt>wp-admin/upload.php</tt>
+
* <code>wp-admin/upload.php</code>
* <tt>wp-includes/bookmark.php</tt>
+
* <code>wp-includes/bookmark.php</code>
* <tt>wp-includes/general-template.php</tt>
+
* <code>wp-includes/general-template.php</code>
* <tt>wp-includes/kses.php</tt>
+
* <code>wp-includes/kses.php</code>
* <tt>wp-includes/plugin.php</tt>
+
* <code>wp-includes/plugin.php</code>
* <tt>wp-includes/rewrite.php</tt>
+
* <code>wp-includes/rewrite.php</code>
* <tt>wp-includes/template-loader.php</tt>
+
* <code>wp-includes/template-loader.php</code>
* <tt>wp-includes/theme.php</tt>
+
* <code>wp-includes/theme.php</code>
  
 
=== WordPress 1.5 ===
 
=== WordPress 1.5 ===
  
Most default filters and actions are added in <tt>wp-includes/default-filters.php</tt> in WordPress 1.5.
+
WordPress 1.5 ではデフォルトフィルターとアクションのほとんどのが <code>wp-includes/default-filters.php</code> に追加されています。
  
 
<div id="Functions_You_Can_Override">
 
<div id="Functions_You_Can_Override">
== Functions You Can Override ==
+
== オーバーライドできる関数 ==
 
</div>
 
</div>
  
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 that WordPress intends for plugins to redefine. WordPress loads these functions only if they are still undefined after all plugins have been loaded, to facilitate this.
+
上記のフック (アクションとフィルター) の他に、プラグインで WordPress の挙動を変更するもう一つの方法が WordPress 関数のオーバーライドです。実際、プラグインでの再定義を意図した関数がいくつかあります。この実行ため、WordPress はこれらの関数のうち、すべてのプラグインの読み込み後も定義されていない関数だけを読み込みます。
  
These functions are defined in file <tt>wp-includes/pluggable.php</tt>. Here is a list (current as of Version 2.1); documentation for at least some of them can be found in the [[関数リファレンス|Function Reference]]:
+
これらの関数は <code>wp-includes/pluggable.php</code> ファイルで定義されています。次のリストはバージョン 2.1 現在のもので、いくつかは [[関数リファレンス]] で説明を見つけることができます:
* <tt>set_current_user</tt>
+
* <code>set_current_user</code>
* <tt>wp_set_current_user</tt>
+
* <code>wp_set_current_user</code>
* <tt>wp_get_current_user</tt>
+
* <code>wp_get_current_user</code>
* <tt>get_currentuserinfo</tt>
+
* <code>get_currentuserinfo</code>
* <tt>get_userdata</tt>
+
* <code>get_userdata</code>
* <tt>update_user_cache</tt>
+
* <code>update_user_cache</code>
* <tt>get_userdatabylogin</tt>
+
* <code>get_userdatabylogin</code>
* <tt>wp_mail</tt>
+
* <code>wp_mail</code>
* <tt>wp_login</tt>
+
* <code>wp_login</code>
* <tt>is_user_logged_in</tt>
+
* <code>is_user_logged_in</code>
* <tt>auth_redirect</tt>
+
* <code>auth_redirect</code>
* <tt>check_admin_referer</tt>
+
* <code>check_admin_referer</code>
* <tt>wp_redirect</tt>
+
* <code>wp_redirect</code>
* <tt>wp_get_cookie_login</tt>
+
* <code>wp_get_cookie_login</code>
* <tt>wp_setcookie</tt>
+
* <code>wp_setcookie</code>
* <tt>wp_clearcookie</tt>
+
* <code>wp_clearcookie</code>
* <tt>wp_notify_postauthor</tt>
+
* <code>wp_notify_postauthor</code>
* <tt>wp_notify_moderator</tt>
+
* <code>wp_notify_moderator</code>
* <tt>wp_new_user_notification</tt>
+
* <code>wp_new_user_notification</code>
* <tt>wp_verify_nonce</tt>
+
* <code>wp_verify_nonce</code>
* <tt>wp_create_nonce</tt>
+
* <code>wp_create_nonce</code>
* <tt>wp_salt</tt>
+
* <code>wp_salt</code>
* <tt>wp_hash</tt>
+
* <code>wp_hash</code>
  
 
== 外部資料 ==
 
== 外部資料 ==
  
* [http://wp.tekapo.com/2008/01/30/wordpress-plugin-api/ わーどぷれすっ! » Plugin API の訳] -- 当ページの taiさんによる完訳
+
* [http://wp.tekapo.com/2008/01/30/wordpress-plugin-api/ わーどぷれすっ! » Plugin API の訳] -- 当ページの転載元(許可受領)
* [http://hiromasa.zone.ne.jp/ hiromasa.zone : o) » 「WordPress プラグイン作成時のノウハウ」]
+
* [http://zone.maple4ever.net/ hiromasa.zone : o) » 「WordPress プラグイン作成時のノウハウ」]
  
{{原文|Plugin API}}
+
{{原文|Plugin API|46009}}
  
 
{{DEFAULTSORT:ふらくいんAPI}}
 
{{DEFAULTSORT:ふらくいんAPI}}

2008年4月4日 (金) 19:49時点における版

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

この文章は、プラグイン開発方法の概説 (そして多くの詳細) が書かれている Writing a Plugin/en をすでに読んでいることを前提としています。また、この文章は特に、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(関数名の衝突を避ける)/en を参照してください。

WordPress にフックする

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

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

引数:

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

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

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 コアで使用されている関数名は使用しないよう気をつけてください。詳しくは Avoiding Function Name Collisions(関数名の衝突を避ける)/en を参照してください。

フィルターにフックする

関数の定義が済んだら、次のステップはこの関数を 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最新版との差分