WordPress Wiki - Plugin/API の訳 by tai

Plugin/API

WordPress プラグイン API

このページでは WordPress のプラグイン開発者が利用可能な API（Application Programming Interface）フックを説明します。 バージョン1.2以上が対象です。

このページを読んでいるということはプラグインの作成に興味を持っているのだと思います。ぜひユーザーの 希望リストに目を通してください。

ハロー、ドリーは WordPress の最初のプラグインです。このプラグインのコ メント付ソースはプラグインの動作を理解するうえで役に立つでしょうし、自分のプラグインを作成する際に使用する構造やシンタックスに対するガイ ド役にもなるでしょう。また、こちらの入門の記事もお役に立つでしょう。

このページの各項目では、便利で利用可能なすべての機能と、プラグインの「方法」と「理由」の全般につい て説明しま す。

プラグイン作者のための一般的なガイドライン

  1. プラグインが必要とするイメージ等のプラグイン固有のファイルは、wp-content フォルダーにアップロードして保管するようにしてください。このフォルダの中身は WordPress をアップデートしても上書きされません。このガイドラ インに従えば、すべてのプラグインファイルをひとつのフォルダーに収めることができるので、エンドユーザの利便性が確実に高まります。wp- content フォルダ内に作成するサブフォルダに関する制限はありません。

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

WordPress はカスタマイズを容易にするためのフックを提供しています。 フックには2種類あります：
  1. アクションをするフック。
  2. フィルタリングをするフック。

コーディングの観点から見れば、アクションとフィルタリングは同一です。add_action 関数は add_filter 関数の別名に過ぎません。しかし実際にはそれぞれ別の役割があります。将来のバージョンでは分離す るかもしれないので、あなたの目的に応じて正しい関数を使用するようにしてください。

アクションとフィルタリング、どちらを使用しても同じ目的を達成できることがあります。例えば、 publish_post にアクションを加えたり、the_content にフィルタを加えたりする場合です。これはそのコンテンツにアクセスしたときに一度だけ変更を加えるか、それともアクセスするたびに変更を加えるかによっ て選択してください。

アクション

アクションは、投稿やテンプレートの変更、そのほかユーザが行 うと思われるほぼすべてのイベントにフックされています。これはデータに 対する永続的もしくは一度だけの変更を行う場合に適しています。（あるいは、投稿が更新されたときにそれをメールで送信するような任意のアクションを行う 場合）

アクションの追加

次のようなphpの関数を作成してみましょう：

<?php
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 source code を検索し て確認してくだ さい - テキスト「do_action」を探して、二つ目のパラメータを確認します）


また、関数は渡された値（または、投稿番号を付け直すような本当にファンキーなこと をするアクションなら、新しい同等な値）を 返さなくてはなりません。さもなければ、他のプラグインを壊すかもしれません！ 1.2 の generic_ping（publish_post にフック）は この必要はありません。その結果として publish_post へのより下位のフックは動作しません。

さらに、アクションは WordPress 内でアクセス可能なグローバル変数を処理することもできます（TableVariables を参照）。

関数の外（一般的には実行スペース内）で、次のように add_action(フック, アクション, プライオリティ {オプション}) を使用して登録します：
add_action('publish_post','email_friends');

プライオリティはオプションで、10がデフォルトです。小さい数ほどプライオリティは上になります（プラ イオリティ9のアクションはプライオリティ10の アクションのより先に実行されます）。 最も高いプライオリティは0です。 複数のアクションに同じプライオリティレベルを持たせることも可能です。この場合最初に読み込まれたアクションが最初に実行されます。

wp-content/plugins ディレクトリ内の新しいファイルにコードを保存し、そ れを作動（activate）させてください。

現時点でのアクション用フック

publish_post
投稿IDが渡されます。 投稿ステータスが変更されて公開されたときや、ある投稿を始めて公開する時に呼び出されます。注意：1.2のこのアクションにフックを追加するときはプラ イ オリティを０から９の間に設定してください。generic_ping フックはバグだらけで、下位のプライオリティのフックが作動しません。
edit_post
投稿IDが渡されます。投稿が編集されるたびに呼び出されます。
delete_post
投稿IDが渡されます。投稿が削除される時にいつでも呼び出されます。
comment_post
コメントIDが渡されます。wp-comments.php を通してコメントが追加され る 時に呼び出されます。
trackback_post
コメントIDが渡されます。wp-trackback.php を通してコメントが追加さ れ る時に呼び出されます。
pingback_post
コメントIDが渡されます。xmlrpc.php を通してコメントが追加される時に呼び 出 されます。
edit_comment
コメントが編集される時にいつでも呼び出されます。
delete_comment
コメントが削除される時に呼び出されます。
file_upload
upload.php（これは実装されていないようです！）経由でファイルがアップ ロードされる時呼び出されます。
template_save
templates.php 経由でファイルが保存される時に呼び出されます。
shutdown
すべての出力が送られた時に呼び出されます。 register_shutdown_function() によく似ています。
wp_head
WPドキュメントの <head> 内の関数を実行さ せます。スタイルや一連のスクリプトの echo に便利です。
admin_head
wp_headと同じですが、管理画面の <head> 部分で実行 されます。
admin_footer
管理画面のフッター部分の外で HTML が閉じられる前に呼び出されます。

sanitize_title:

フィルタ

フィルタは、データがそこに流れたりそこで変更されたりす る関数です。オンザフライのデータ変更に便利です（例えば頭字語を特定の単語 に追加するとき）。

フィルタの使用

フィルタはデータベース内のどんなデータもけっして変更しません。 その代わりに、データベースとブラウザの間に居座る姿を想像してください。 データベースからブラウザに流れるすべてのデータはフィルタを通過しなくてはなりません。フィルタを追加することによって、データベースの中身を変更せず にユーザーが見るものを変更することができます。

次のようなテキストを処理する php 関数を作成してみましょう：

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

（実際は自分で関数を書く必要はありません－－テキストを処理するどんな php 標準関数でも使用することができます（例えばstrtoupper）。

この関数の外で（一般的な実行スペース内)、次のように add_filter(フック, アクション, プライオリティ {オプション}) を使ってこれを登録します：
add_filter('comment_text','filter_profanity');

プライオリティはオプションで、10がデフォルトです。小さい数ほどプライオリティは上になります（プラ イオリティ9のアクションはプライオリティ10の アクションのより先に実行されます）。 最も高いプライオリティは0です。 複数のアクションに同じプライオリティレベルを持たせることも可能です。この場合最初に読み込まれたアクションが最初に実行されます。

wp-content/plugins ディレクトリ内の新しいファイルにこのコードを保存し、そ れを作動（activate）させます。

現時点のフィルター用フック

これらのほとんどがテ ンプ レートタグであることに注目してください。

format_to_edit:

format_to_post:

category_description

list_cats

comment_author

author_email

comment_email:

comment_excerpt

comment_url:

comment_text

single_post_title

the_date

the_time

the_weekday

the_weekday_date

the_title

the_title_rss

the_content
投稿内容を処理する関数。

the_excerpt

rewrite_rules
エコーアウトする前にパーマリンク設定スクリーン上のルールを渡します。ルールの修正や独 自ルールの追加に便利です。1.2以降で有効です。

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

API を使用するのはあなた一人ではありません--これはあらゆる種類の結果を達成するために開発者たちが使用するテクニックと同じものです。自分のプラ グインを動作させるためにはいくつかの API を取り除く必要があるかもしれません。これを行うには次を呼び出します
remove_filter('hook','filter') または remove_action('hook', 'action')。

例：remove_action('publish_post','generic_ping'); は、新しい投稿作成時は常にブログが ping を送らないようにします。

通常はその API の機能と原理を知らない限り、どの API も削除するべきであり ません。フックが追加されたファイル名は、あなたのチェックアウトを容易にするために提供されています。

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

投稿関連

wp-rdf.php:add_filter('the_content', 'trim');
template-functions-post.php:add_filter('the_content', 'convert_smilies');
template-functions-post.php:add_filter('the_content', 'convert_chars');
template-functions-post.php:add_filter('the_content', 'wpautop');
vars.php:add_filter('the_content', 'wptexturize');

functions.php:add_action('publish_post', 'generic_ping');

template-functions-post.php:add_filter('the_excerpt', 'convert_smilies');
template-functions-post.php:add_filter('the_excerpt', 'convert_chars');
template-functions-post.php:add_filter('the_excerpt', 'wpautop');
vars.php:add_filter('the_excerpt', 'wptexturize');

タイトル関連

template-functions-post.php:add_filter('the_title', 'convert_chars');
template-functions-post.php:add_filter('the_title', 'trim');
vars.php:add_filter('the_title', 'wptexturize');

vars.php:add_filter('single_post_title', 'wptexturize');

template-functions-post.php:add_filter('the_title_rss', 'strip_tags');

functions-formatting.php:add_action('sanitize_title', 'sanitize_title_with_dashes');

コメント関連

template-functions-comment.php:add_filter('comment_excerpt', 'convert_chars');

kses.php:add_filter('comment_author', 'wp_filter_kses');
template-functions-comment.php:add_filter('comment_author', 'wptexturize');
template-functions-comment.php:add_filter('comment_author', 'convert_chars');
vars.php:add_filter('comment_author', 'wptexturize');

template-functions-comment.php:add_filter('comment_email', 'antispambot');

template-functions-comment.php:add_filter('comment_url', 'clean_url');
wp-comments-popup.php:add_filter('comment_text', 'popuplinks');

template-functions-comment.php:add_filter('comment_text', 'convert_chars');
kses.php:add_filter('comment_text', 'wp_filter_kses');
template-functions-comment.php:add_filter('comment_text', 'make_clickable');
template-functions-comment.php:add_filter('comment_text', 'wpautop', 30);
template-functions-comment.php:add_filter('comment_text', 'balanceTags');
template-functions-comment.php:add_filter('comment_text', 'convert_smilies', 20)
;
vars.php:add_filter('comment_text', 'wptexturize');

カテゴリー関連

vars.php:add_filter('category_description', 'wptexturize');

vars.php:add_filter('list_cats', 'wptexturize');

その他

vars.php:add_action('wp_head', 'doGeoUrlHeader');

WordPress 認証の使用

‘メンバーのみ’の php スクリプトを作成するには（ス クリプトの最初にこれを置 きます） 
require('/path/to/wp-admin/auth.php')