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

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

プラグインの作成

提供: WordPress Codex 日本語版
移動先: 案内検索

この項目「プラグインの作成」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

はじめに

WordPress プラグインを使うと、WordPress サイトの変更、カスタマイズ、機能強化を簡単に行うことができます。WordPress のコアプログラムに手を入れる代わりに、プラグインで機能を付け加えることができるのです。定義は以下の通りです:

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

WordPress にない機能が欲しい場合や、既存の機能を変更したい場合は、まずプラグインレポジトリなどでを検索してすでに他の人がその機能を実装していないか探してみましょう。もし見つからない場合は、以下の記事で WordPress プラグインの作り方を学びましょう。

この記事は、WordPress の基本的な機能や PHP プログラミングを知っていることを前提に書かれています。

資料

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

訳注: プラグインを公式プラグインディレクトリでホスティングしたければ、公式ディレクトリで許されることとそうでないことのガイドラインもお読みください。

プラグインの作成

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

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

プラグインの名前

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

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

プラグイン・ファイル

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

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

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

説明書

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

WordPress プラグインレポジトリは "Requires" および "Tested up to" のバージョンを readme.txt ファイルの stable タグから取得します。

stable タグの readme.txt がプラグインを定義づけるものと見なされることに注意してください。そのため /trunk/readme.txt の stable タグが 4.3 であれば、/tags/4.3/readme.txt がプラグインの情報として表示されます。この場合、 /trunk/readme.txt の内容のうち使われるのは stable タグの指定のみということになります。つまり、 trunk/readme.txt の stable タグさえ適切なバージョンを指定していれば、 trunk で開発をしている時に、現在の stable バージョンにはない機能を意図せず公表してしまうことなく、開発中の情報を trunk/readme.txt に反映することができます。

紹介ページ

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

ファイル・ヘッダー

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

標準プラグイン情報

Read this in the plugin developer handbook. 最新はこちらをお読みください。(英語)

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

https://wordpress.org/plugins/about/readme.txt にある description のフォーマット または、自動生成 plugin 'readme.txt' generatorも参照ください。

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

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

License の行にはプラグインのライセンスの短い共通識別子を記入してください。これは、コードのライセンスを明示的に示すための簡単な方法として用意されています。

重要: ファイルは必ず UTF-8 エンコーディングにしてください。

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

ライセンス

Read this in the plugin developer handbook. 最新はプラグインディベロッパーハンドブックをお読みください。(英語)

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

訳注: 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, version 2, as
	published by the Free Software Foundation.

    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. 新しくカスタムのデータベーステーブルを作成します。この手法は、個々の投稿・ページ・添付ファイル・コメントに関連するデータを保管するのに適しています。データの種類としては、時間が経つにつれ大きくなるデータで、名前を持たないデータです。やり方はプラグインでのテーブル作成を見てください。

WordPress 設定機構

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

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

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

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

管理画面

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

プラグインの多言語化

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

プラグインの言語ファイルは自動的には読み込まれません。以下をプラグインのコードに含め、言語ファイルが必ず読み込まれるようにしてください。

	load_plugin_textdomain('your-unique-name', false, basename( dirname( __FILE__ ) ) . '/languages' );

文字列を取得するには、__('String name','your-unique-name'); を使って翻訳を返すか、_e('String name','your-unique-name'); をつかって翻訳を出力します。翻訳ファイルはプラグインの /languages フォルダに含めてください。

さまざまな国のユーザーがローカライズできるように、プラグインの国際化は強く推奨されています。国際化についての総合的なリファレンスが WordPress の翻訳ページにあります。

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

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

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

外部リソース

日本語

英語

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