当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

プラグインの作成

提供: WordPress Codex 日本語版
2008年10月15日 (水) 01:06時点におけるLily (トーク | 投稿記録)による版 (表紙ページ → 紹介ページ)

移動先: 案内検索

はじめに

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

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

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

資料

  • プラグイン・リソースでは、プラグイン開発者のための総合的な記事やリソースの一覧があります。外部サイトの記事や特別なトピックもあります。
  • プラグインについて学ぶ他のよい方法は、上手に書かれたプラグインの 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 ファイルを示します。

説明書

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

WordPress 設定機構

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

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 がインストールされたとき時点でのデフォルト設定の一覧は、設定リファレンスにあります。
update_option($option_name, $newvalue);
データベースで設定値を更新または作成します。($deprecated$autoload パラメータを使わないならば、add_option を呼ばなくて構いません)
$option_name
必須 (string)。更新したい設定の名前。
$newvalue
必須。設定の新しい値。

管理パネル

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

プラグインの多言語化

Once you have the programming for your plugin done, another consideration (assuming you are planning on distributing your plugin) is internationalization. Internationalization is the process of setting up software so that it can be localized; localization is the process of translating text displayed by the software into different languages. WordPress is used all around the world, so it has internationalization and localization built into its structure, including localization of plugins. For background on WordPress's use of GNU gettext for localization, see WordPress の翻訳.

It is highly recommended that you internationalize your plugin, so that users from different countries can localize it. The process is fairly straightforward:

  • Choose a translation "text domain" name for your plugin. This is generally the same as your plugin file name (without the .php), and must be unique among plugins the user has installed.
  • Wherever your plugin uses literal text strings that will be displayed to the user (known as "messages"), wrap them in one of the two WordPress gettext functions. Note that in a plugin, you need to use the second argument, passing in the translation text domain name you chose, unlike in the core of WordPress (which leaves the $domain argument blank).
__($message, $domain) 
Translates $message using the current locale for $domain. Wrap text strings that you are going to use in calculations with this function.
_e($message, $domain) 
Translates $message using the current locale for $domain, and then prints it on the screen. Wrap text strings that you are directly printed with this function.
  • Create a POT file (translation catalog listing all the translatable messages) for your plugin, and distribute it with your plugin. Users will need to put their translated MO file in the same directory as your plugin's PHP file, and name it domain-ll_CC.mo, where ll_CC is the name of their locale. See WordPress の翻訳 for information on POT files, MO files, and locales.
  • Load the translations for the current locale and your text domain by calling load_plugin_textdomain before either of the gettext functions is called, but as late as possible in the session (because some multi-lingual plugins change the locale when they load). One possible implementation is to define an initialization function that is called at the top of all of your plugin functions. For instance, assuming your text domain is "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__)));
}

If your plugin isn't in its own subdirectory, you can leave out the second argument of load_plugin_textdomain.

If you are reading this section because you want to internationalize a Theme, you can basically follow the steps above, except:

  • The MO file goes into the theme directory (same place as style.css).
  • The MO file is named ll_CC.mo, where ll_CC is the name of the locale (i.e. the domain is NOT part of the file name).
  • To load the text domain, put the following (inside a PHP escape if necessary) in your theme's functions.php file:
load_theme_textdomain('your_domain');

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

This last section contains some random suggestions regarding plugin development.

  • The code of a plugin should follow the WordPress コード規約. Please consider the インラインドキュメント Standards as well.
  • All the functions in your plugin need to have unique names that are different from functions in the WordPress core, other plugins, and themes. For that reason, it is a good idea to use a unique function name prefix on all of your plugin's functions. Another possibility is to define your plugin functions inside a class (which also needs to have a unique name).
  • Do not hardcode the WordPress database table prefix (usually "wp_") into your plugins. Be sure to use the $wpdb->prefix variable instead.
  • Database reading is cheap, but writing is expensive. Databases are exceptionally good at fetching data and giving it to you, and these operations are (usually) lightning quick. Making changes to the database, though, is a more complex process, and computationally more expensive. As a result, try to minimize the amount of writing you do to the database. Get everything prepared in your code first, so that you can make only those write operations that you need.
  • SELECT only what you need. Even though databases fetch data blindingly fast, you should still try to reduce the load on the database by only selecting that data which you need to use. If you need to count the number of rows in a table don't SELECT * FROM, because all the data in all the rows will be pulled, wasting memory. Likewise, if you only need the post_id and the post_author in your plugin, then just SELECT those specific fields, to minimize database load. Remember: hundreds of other processes may be hitting the database at the same time. The database and server each have only so many resources to spread around amongst all those processes. Learning how to minimize your plugin's hit against the database will ensure that your plugin isn't the one that is blamed for abuse of resources.


外部リソース