プラグインの作成

出典: WordPress Codex 日本語版

目次

はじめに

WordPress 1.2 より前では、WordPress の振舞いを変更したいと思ったとき、WordPress のソースコードを編集 (もしくは「いじる」) 必要がありました。ところが、現在の WordPress では、プラグインを使用して、コア部分に対して簡単に機能の変更や追加を行うことができます。プラグインという仕掛けの基本的なアイディアは、WordPress のコアを比較的単純に保ち、しかしながらプラグインによって入出力の内容を変更できるぐらい柔軟であるようにすることです。定義は以下の通りです:

WordPress プラグイン 
WordPress プラグインは PHP 言語で記述された、プログラムないし1つ以上の関数の集まりであり、WordPress ウェブログに (WordPress プラグイン・アプリケーション・インターフェース (API) で提供されるアクセスポイントやメソッドを使ってウェブログとシームレスに統合された) 特定の機能やサービスを追加します。

この記事は、WordPress の基本的な機能や PHP プログラミングに親しんでいることを前提としています。

資料

  • プラグイン・リソースでは、プラグイン開発者のための総合的な記事やリソースの一覧があります。外部サイトの記事や特別なトピックもあります。
  • プラグインについて学ぶ他のよい方法は、上手に書かれたプラグインの PHP ソースコードを眺めることです。例えば、Hello Dolly のように WordPress に同梱されているプラグインです。
  • プラグインを作成したら、プラグインの提出と宣伝/en を読んで、広く配布する方法を学んでください。

プラグインの作成

この節では、うまく構成された WordPress プラグインを作るために考慮すべき事項について、順序立てて説明していきます。

名前、ファイル、格納位置

プラグインの名前

プラグイン作成での最初の作業は、プラグインが何を行うかを考えて、プラグインの名前 (できれば唯一の) 名前を生成することです。プラグインやプラグインが参照する他の配布サイトをチェックして、考えた名前が他にない唯一のものであることを検証してください。名称案で Google 検索してみるのもいいでしょう。多くのプラグイン開発者は、プラグインの動作を表す名称にしています。例えば、天気 (weather) に関するプラグインは、たいてい名前に「weather」という単語を含むでしょう。プラグイン名は、複数の単語であって構いません。

訳注: プラグインの名称には日本語文字列は使えません。英数字、空白と一部の記号のみとしてください。英単語が好ましいですが、日本語圏専用ならば、日本語をローマ字綴りしたものものでもよいでしょう。

プラグイン・ファイル

次は、選択したプラグイン名に由来する名前の PHP ファイルを作ります。例えば、プラグインの名前が「Fabulous Functionality」(驚くべき機能) であれば、PHP ファイルは fabfunc.php としていいでしょう。ここでも、他にない唯一の名前を選んでください。あなたのプラグインをインストールする人々は、この PHP ファイルを WordPress のプラグインディレクトリー wp-content/plugins/ に配置しますが、同じファイル名の PHP ファイルであるプラグインは複数存在できないのです。

他の選択肢は、プラグインを複数のファイルに分割することです。プラグインは最低でも1つの PHP ファイルが必要です。他には、JavaScript ファイル、CSS ファイル、画像ファイル、言語ファイル等を含むことができます。もし複数のファイルがあれば、ディレクトリーおよび PHP ファイルに対して、他にない唯一の名前を選んでください。この例では fabfunc や fabfunc.php でしょう。プラグインの全ファイルをそのディレクトリーに配置し、プラグインの利用者には、ディレクトリー全体を wp-content/plugins/ 配下にインストールするよう告知してください。

以後は、「プラグインの PHP ファイル」とは、 wp-content/plugins/ ディレクトリーまたはサブディレクトリーに置かれた、プラグインの主たる PHP ファイルを示します。

説明書

もし、プラグインを http://wordpress.org/extend/plugins/ (訳注: 公式プラグインディレクトリー) にホストしたいなら、readme.txt ファイルを定められた書式で作成して、プラグインに含める必要があります。書式の説明については http://wordpress.org/extend/plugins/about/readme.txt を参照ください (訳注: 英文です)。

紹介ページ

また、プラグインの「紹介ページ」となるウェブページを作成するのも有用です。このページで説明することは、プラグインのインストール方法、プラグインが何をするものか、動作する WordPress バージョン、プラグインのバージョンごとの変更点、プラグインの使い方、です。

ファイル・ヘッダー

ここでは、プラグインのメイン PHP ファイルにいくつか情報を記載してみます。

標準プラグイン情報

プラグインの主たる PHP ファイルの先頭には、標準プラグイン情報ヘッダーを含まなければなりません。このヘッダーは、WordPress にプラグインの存在を認識させ、プラグイン管理画面に表示させます。これにより、プラグインを有効化して、読み込んで、機能を走らせることができます。ヘッダーが存在しない場合、プラグインは有効化も実行もできません。以下にヘッダー書式を示します。 

<?php
/*
Plugin Name: (プラグインの名前)
Plugin URI: (プラグインの説明と更新を示すページの URI)
Description: (プラグインの短い説明)
Version: (プラグインのバージョン番号。例: 1.0)
Author: (プラグイン作者の名前)
Author URI: (プラグイン作者の URI)
*/
?>

WordPress がプラグインを認識するのに必要な最低限の情報は、Plugin Name の行です。もし残りの情報があれば、プラグイン管理画面でプラグインのテーブルを作るのに使われます。各行の順番は不問です。

訳注: 原則として、情報はすべて英文で記載してください。ただし、日本語圏のみ配布するプラグインであれば、日本語でも構いません。

ライセンス

慣例として、標準プラグイン情報の次にプラグインのライセンス情報を書きます。多くのプラグインは WordPress と同じ GPL、ないし GPL 互換のライセンス (英文) を用いています。GPL ライセンスを示すには、プラグインに以下の行を含めてください。

訳注: GPL は英文でのみ効力を持ちます。このため、翻訳はしておりません。「作成年」は、プラグインの作成年 (西暦; 2008 など) に置き換えてください。プラグイン作者名は、ローマ字での記載を行なってください。 

<?php
/*  Copyright 作成年 プラグイン作者名 (email : プラグイン作者のメールアドレス)

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/
?>

プラグインのプログラミング

ここでは、プラグインの実際の動作を作っていきましょう。この節は、プラグイン開発に関する一般的な考え方について書かれており、プラグインにとって必要な作業を果たす方法を説明しています。

WordPress プラグイン・フック

多くのプラグインが、WordPress 用プラグインフックと1つ以上接続することで、目的を果たしています。プラグインフックが動く方法は、WordPress が走る間のさまざまなタイミングで、いずれかのプラグインがその時点で走る関数を登録していないかを WordPress が確認し、もしあればその関数を走らせることによります。これらの関数は、WordPress のデフォルトの振舞いを変更します。

例えば、WordPress がブラウザーへの出力に投稿タイトルを追加する前に、「the_title」と呼ばれる「フィルター」フックに、いずれかのプラグインが関数を登録していないかを見ます。もしあれば、タイトルのテキストが、登録された各関数に順番に渡され、最後の結果が出力されます。すなわち、プラグインが出力されたタイトルに何か情報を追加したければ、「the_title」フィルター関数を登録すればよいのです。

他の例は、「wp_footer」と呼ばれる「アクション」フックです。WordPress が生成する HTML ページのまさに最後の段階で、「wp_footer」アクションフックに、いずれかのプラグインが関数を登録しているかどうかを確認し、順番にそれらを走らせます。

フィルターやアクションのフックに関数を登録する方法や、どんなプラグインフックが WordPress に用意されているかを学ぶには、プラグイン API を見てください。もし、WordPress のコードのある場所で、アクションまたはフィルターが欲しいと思ったものの、そこにフックがなければ、新しいフックとして提案することもできます (一般的に提案は受け入れられます)。やり方についてはバグの報告を見てください。

テンプレートタグ

他に、WordPress に新たな機能を追加する方法は、カスタムのテンプレートタグを作ることです。あなたのプラグインを使いたい人は、これらの「タグ」を、自身のテーマのサイドバー・投稿の内容部分、または適切な場所のどこにでも追加することができます。例えば、地理タグ (geotag) を投稿に追加するプラグインならば、サイドバー向けに geotag_list_states() というテンプレートタグ関数を定義するでしょう。これは投稿にタグ付けられた州 (state) をリストし、プラグインが提供する州ごとのアーカイブページにリンクします。

カスタムのテンプレートタグを定義するには、単に PHP 関数を書き、プラグイン利用者向けに、プラグインの紹介ページおよびプラグインのメイン PHP ファイルでドキュメントを示します。 関数のドキュメントにおいて、関数を使うためにテーマに何を書けばよいかの例を示すとき、<?php や ?> を含めるのがよいでしょう。

データベースにデータを保存する方法

多くのプラグインが、サイト所有者もしくはブログ利用者から何か入力してもらったら、フィルター関数、アクション関数やテンプレート関数で使うため、セッションの間でその値を保存しておく必要があります。この情報は、セッションを通じて維持させるため、WordPress データベースに保存しなければなりません。データベースにデータを保存するには、2つの基本的な手法があります:

  1. WordPress の「設定」機構 (後述) を使います。この手法は、比較的小さくて比較的変化が少ない、名前のついたデータを保管するのに適しています。データの種類としては、サイト所有者がプラグインの最初の設定を行うときに入力すると期待され、今後めったに変化しないという類いのデータです。
  2. 新しくカスタムのデータベーステーブルを作成します。この手法は、個々の投稿・ページ・添付ファイル・コメントに関連するデータを保管するのに適しています。データの種類としては、時間が経つにつれ大きくなるデータで、名前を持たないデータです。やり方はプラグインでのテーブル作成/en を見てください。

WordPress 設定機構

設定ページの作成/en に、自分用の設定値を自動的に保存するようなページの作り方の情報があります。

WordPress には、独立した、名前の付いたデータ (「設定」) を WordPress データベースに保存・更新・読出をする機構があります。設定値の取り得る形式は、文字列 (string)、配列 (array)、もしくは PHP オブジェクトです (オブジェクトは、保管時は「シリアライズ」もしくは文字列に変換され、読出時にオブジェクトに戻されます)。オプション名は文字列で、他にない唯一ものでなければなりません。なぜなら、WordPress や他のプラグインと衝突しないためです。

これは、プラグインが WordPress 設定にアクセスするために使える主たる関数です。 

add_option($name, $value, $deprecated, $autoload);
新しい設定を作ります。設定が存在すれば何もしません。
$name
必須 (string)。追加する設定の名前です。
$value
任意 (string)、デフォルトは空の文字列です。保管する設定値です。
$deprecated
任意 (string)、もはや WordPress で使われていません。次の $autoload パラメータを使いたいならば、この引数に空の文字列もしくは NULL を入れてください。
$autoload
任意、デフォルトは 'yes' (enum: 'yes' or 'no'). 'yes' を入れると、この設定は get_alloptions 関数によって自動的に読み出されます。 
get_option($option);
データベースから設定値を読み出します。
$option
必須 (string)。値を返してほしい設定の名前です。WordPress がインストールされたとき時点でのデフォルト設定の一覧は、設定リファレンス/enにあります。 
update_option($option_name, $newvalue);
データベースで設定値を更新または作成します。($deprecated や $autoload パラメータを使わないならば、add_option を呼ばなくて構いません)
$option_name
必須 (string)。更新したい設定の名前。
$newvalue
必須。設定の新しい値。

管理パネル

プラグインに、WordPress データベースに保管したい設定があれば (前節を参照)、プラグイン利用者が設定値を閲覧したり編集したりするための管理パネルを持ちたいと思うでしょう。このための手法は、管理メニューの追加/en で説明します。

プラグインの多言語化

プラグインのプログラミングを終えたら、(プラグインを配布する計画があれば) 「国際化」について考慮しましょう。国際化は、ソフトウェアを「ローカライズされた」状態にする処理です。ローカライズとは、ソフトウェアによって表示されるテキスト異なる言語に翻訳する処理です。WordPress は世界中で使用されていて、国際化やローカライズの仕掛け (プラグインのローカライズも対象) が組み込まれています。WordPress がローカライズに使用している GNU gettext の背景についてはWordPress の翻訳を見てください。

プラグインを国際化することは強く推奨されています。そうすれば、さまざまな国のユーザーがローカライズできます。処理は以下の順で行なわれます。

  • プラグインの翻訳に使う「テキスト領域 (text domain)」を決めます。通常、プラグインのファイル名 (.phpを除く) と同じものとし、インストールされたプラグインの間で唯一のもの (重複なし) としなければなりません。
  • プラグインがユーザーに表示する文章のテキスト文字列 (「メッセージ」と呼びます) を使うそれぞれにおいて、WordPress の gettext 関数の1つでそれらを囲みます。プラグインでは、第2引数を必要とすることに注意してください。選択した翻訳テキスト領域を渡すことで、WordPress コアの場合 ($domain 引数が空) と異なることを示します。
__($message, $domein) 
$message (メッセージ) を現在のロケール (地域) を使って $domein (領域) 用に翻訳します。式で使おうとするテキスト文字列をこの関数で囲んでください。
_e($message, $domain) 
$message (メッセージ) を現在のロケールを使って $domein (領域) 用に翻訳し、画面に表示します。直接表示するテキスト文字列をこの関数で囲んでください。
  • プラグイン用の POT ファイル (すべての翻訳可能メッセージを並べた翻訳カタログ) を作成し、プラグインと一緒に配布してください。ユーザーは、翻訳された MO ファイルをプラグインの PHP ファイルと同じディレクトリーに配置し、ファイル名は domain-ll_CC.mo とする必要があります。ここで、ll_CC はユーザーのロケール名です。POT ファイル、MO ファイル、ロケールについての情報はWordPress の翻訳を見てください。
  • 現在のロケールおよび、プラグインのテキスト領域用に翻訳を読み込むには、いずれかの gettext 関数を呼ぶ前に load_plugin_textdomain を呼んでください。ただし、セッション内のできるだけ遅い段階で実行します (なぜなら、多言語プラグインがロケールを変更することがあるためです)。考えられる実装の1つとしては、プラグイン内のすべての関数の先頭で呼ばれる初期化関数を定義することです。例えば、テキスト領域が「fabfunc」とすれば以下のようになります: 
$fabfunc_domain = 'fabfunc';
$fabfunc_is_setup = 0;

function fabfunc_setup()
{
   global $fabfunc_domain, $fabfunc_is_setup;

   if($fabfunc_is_setup) {
      return;
   } 

   load_plugin_textdomain($fabfunc_domain, 
   PLUGINDIR.'/'.dirname(plugin_basename(__FILE__)), 
   dirname(plugin_basename(__FILE__)));
}

もし、プラグインが自前のサブディレクトリーに入っていなければ、load_plugin_textdomain の第2引数以降を省略できます。

訳注: 第2引数は、WordPress 2.5 以前への互換用で、第3引数は WordPress 2.6 以降用です。

もし、この節を読んでいる理由が、テーマの国際化をしたいためならば、原則として上記の手順に従った上で、以下のように読み変えてください:

  • MO ファイルはテーマのディレクトリーに入れます (style.css と同じ場所)。
  • MO ファイルは ll_CC.mo という名前にしてください。ここで、ll_CC はロケールの名前です (つまり、テキスト領域はファイル名に含まれません)。
  • テキスト領域を読み込むには、以下のコード (必要ならば PHP のエスケープで囲って) をテーマの functions.php ファイルに書きます。your_domain は実際のテキスト領域に置き換えてください。 
load_theme_textdomain('your_domain');

プラグイン開発における推奨事項

最後の節は、プラグイン開発における雑多な推奨事項です。

  • プラグインのコードは WordPress コーディング基準に従ってください。同様にインラインドキュメント/en規約も考慮してください。
  • プラグインにあるすべての関数は、他にない唯一の名前を持たなければなりません。WordPress コア、他のプラグインやテーマの関数と違うものにしてください。これに従う1つのうまい方法としては、プラグインの関数すべての名前に、唯一の前置詞を付けることです。他のやり方としては、プラグインの関数をクラスの中で定義します (クラスの名前は他にない唯一のものにする必要があります)。
  • プラグインで、WordPress データベースの前置詞 (通常は「wp_」) をハードコードしないでください。代わりに、 $wpdb->prefix 変数を使うようにしてください。(訳注: $table_prefix も好ましくありません)
  • データベースの読み出しの負荷は軽いですが、書き込みは高負荷です。データベースは、データを取得してあなたに与えてくれる動作において非常に優秀で、これらの操作はたいてい素早いものです。しかしながら、データベースに変更を加えることは、より複雑な処理で、計算量を伴う高負荷なものです。そのため、データベースへの書き込み量が最小限になるよう努力してください。コードでは、まずプリペアードステートメントを使うようにしてください。そうすれば、必要十分の書き込み処理がなされます。
  • SELECT 文での選択は、必要な分だけ行なってください。データベースからのデータ取得は目にも止まらぬ速さだとしても、最低限のデータだけを選択することで、データベースへの負荷を軽減する努力をするべきです。もし、テーブル内の行数を数える必要があれば、SELECT * FROM を使ってはいけません。なぜなら、すべての行のすべてのデータが取り出されてしまい、メモリーを浪費してしまうからです。同様に、プラグインで、post_id と post_author のみが必要であれば、SELECT 文でこれら特定のフィールドを選択することで、データベース負荷を最小化できます。次のことを覚えておいてください: 同時に何百もの他のプロセスがデータベースにヒットするかもしれません。データベースやサーバーは、それらすべてのプロセスの間で自身のリソースを分配しなければならないのです。データベースに対してプラグインからのヒットを最小限にする方法を学べば、あなたのプラグインがリソースを食うと非難されることはないはずです。
  • (訳注: むしろ、データベースへの直接アクセスではなく、WordPress の API を利用してデータを取り出すようにしてみてください。API を使った場合、取り出したデータをメモリにキャッシュするため、データベースの読み込み処理が自動的に軽減されます)

外部リソース

原文・最新版： WordPress Codex » Writing a Plugin （最新版との差分）

"http://wpdocs.sourceforge.jp/%E3%83%97%E3%83%A9%E3%82%B0%E3%82%A4%E3%83%B3%E3%81%AE%E4%BD%9C%E6%88%90" より作成
他の言語