実際にプラグインを開発してみてわかった、かゆいところに手が届く解説

WordPressでは、その人気にふさわしく多くのプラグインが用意されています。
それに合わせて、プラグインの作り方を解説するサイトも多く、Codexにも解説ページが用意されています。

情報が豊富なのは良いことなのですが、今回SNSのカウントをキャッシュするプラグイン「Step by Step Social Count Cache」を開発するに当たり、「これは先に解説して欲しかった…」「え、なんでこれ解説がないの？」と悶々とすることが多々ありました。

そこで、初めてプラグインを作成する方がハマりやすいポイントも含めて解説します。

WordPressプラグインの解説、全体の目次

• 本気で作りたい人向け、WordPressプラグインの作成方法（このページ）
• WordPressプラグインの仕組みとクラスを利用したより実践的な解説
• WordPressのプラグインでデータベースを作成・削除・アップデートする方法
• WordPressプラグイン用の設定を追加する方法
• WordPressプラグインを公式プラグインディレクトリへ追加する方法

このページの目次

• まずプラグインの名前を考える
• WordPressのプラグインについて理解する
• プラグインの設計とファイル構成を考える
• 実際にプラグインを作成する
• プラグインの基本情報を追加する
• プラグインのライセンスを追加する

まずプラグインの名前を考える

「何を当たり前のことを」と思うかもしれませんが、これがとても重要です。プラグイン名、プラグインのフォルダ名、プラグインのPHPファイル名は、全て一意（ユニーク）である必要があります。
また、プラグイン固有のテンプレートタグも、WordPressのタグはもちろん、他のプラグインと被ると動作しません。

多数のプラグインが公開されているので、get_postsや、populer_postといったよくありそうな名前は避ける必要があります。
「わかり易い名前を付ける」という命名規則の基本と逆行するところがありますが仕方ありません。

「一意性を確保しつつ、わかり易い名前を」となると、どうしても名前が長くなるようで、公式サイトを少し探しただけで「NextGEN Facebook – Complete Meta Tags for FB, Google, Pinterest, Twitter, LinkedIn & More」という名前のプラグインを見つけました。
さすがにこれは長過ぎる気がしますが一意な名前をつけるのに苦労しているさまが伺い知れます。

そうなると有効なのが「接頭辞」を付けることです。しかし「wp_」や、「post_」といったありがちな接頭辞だと意味がありません。
簡単なのは自分のスクリーンネームやサイトの略称などを付けることです。私の場合なら「oxy_」としたり、「oxynotes_」等とすれば被る可能性をかなり減らすことができます。ただし、屋号なんかは避けたほうが良いようです。
他にも機能の頭文字を取るという方法もあります。私の作成したプラグインでは「step by step」から頭文字を取って「sbs_」という接頭辞を付けました。

ということでまずはオリジナルの接頭辞を考えてみてください。

WordPressのプラグインについて理解する

プラグインには大きく分けて2つのアプローチがあります。
1つはフックを使う方法。もう1つはテンプレートタグを追加する方法です。

WordPressにおけるフックとは何か

Codexいわく「WordPress はプラグインを WordPress 本体に “引っ張り込む (hook into)” ためのフックを提供しています。」とのこと。
具体的に何を使って引っ張り込むのかというと、アクションフックと、フィルターフックがあります。
（当初フックをfook（引っ掛ける）と解説していましたが、正しくはhookでした。修正してお詫びします。）

アクションフックとは何か

アクションフックとは名前の通り、何らかの動作をフラグにするフックです。例えばWordPress全体を読み込んだ時に実行されるアクションはwp_loaded。フッターを読み込んだ時に実行されるアクションはwp_footerといった具合です。

WordPressには沢山のアクションフックが用意されています。

詳しくは「Codexのアクションフック一覧ページ」をご覧ください。

フィルターフックとは何か

アクションフックは動作をフラグにしていましたが、フィルターフックはデータをフラグにします。例えばユーザーが投稿したデータをフィルターするにはcontent_save_pre。データベースから取得した投稿の抜粋をフィルターするにはget_the_excerptといった具合です。

フィルターフックも詳しくは「Codexのフィルターフック一覧ページ」をご覧ください。

テンプレートタグとは何か

テンプレートタグはWordPressで定義された関数です。
普段テンプレートファイルを編集する際にも使っています。投稿のコンテンツを表示するthe_content()だったり、タイトルを表示するthe_title()などです。

プラグインではWordPressで用意されたものではなく、新しいテンプレートタグを追加することで、新しい機能を追加します。

テンプレートタグも詳しくは「Codexのテンプレートタグ一覧ページ」をご覧ください。

プラグインの設計とファイル構成を考える

プラグインの最小構成はPHPファイルのみです。
現実的にはREADMEファイルや、翻訳ファイルなどで構成されるため、多くの場合プラグイン専用のディレクトリを作って管理します。

プラグインディレクトリの構成は自由に決められます。
今回は実際にプラグインを作った経験から、こうしておけばよかったというお勧めを紹介します。

まずプラグインディレクトリに沢山のPHPファイルがあるとメインファイルがわかりにくいので外部ファイルとして読み込むものは「lib」や「inc」といったディレクトリを作成してまとめます。

翻訳ファイルはlanguagesディレクトリにまとめる決まりがあるので作成するとして、他にも画像を使う場合は「imagesディレクトリ」、jQueryなどは「jsディレクトリ」といった具合にまとめるとわかりやすいと思います。

もちろんプラグインの機能によって様々ですが、とりあえずは以下のように作成しておくと、わかりやすいと思います。

プラグインディレクトリ
├ lib（メインファイルから分離したPHPファイル）
├ images（画像ファイル）
├ js（JavaScriptファイル）
├ style（CSS）
└ languages（翻訳ファイル）
 plugin.php（プラグインのメインファイル）
 readme.txt（READMEフィアル）

実際にプラグインを作成する

まずは簡単な「Hello World」を表示するプラグインを作り、段々と実践的なプラグインを作成します。
ただ、名前を考えるのも面倒なので解説で作成するプラグイン名は「Hello World」にします。

WordPressのデバッグを有効にする

これからプラグインを開発するにあたり、まずはデバックを有効にします。これを有効にすると非推奨になった関数をメッセージで表示したり、引数の型が間違っているなどエラーの詳細が表示されるようになります。

WordPressのルートディレクトリにある「wp-config.php」を開いて、以下のコードを追加します。

define('WP_DEBUG',true);

既にfalseがある場合は上書きしてください。

プラグインの基本情報を追加する

プラグインのメインファイルに「標準プラグイン情報」というメタ情報を記載します。

WordPressはプラグインディレクトリにあるファイルを走査して、「標準プラグイン情報」を探します。
ファイル名にかかわらず「標準プラグイン情報」が記述されているファイルをはじめに実行するので注意してください。

Codexの標準プラグイン情報に関する解説

具体的な書式は以下のようになっています。

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

それでは実際にプラグインを作成してみましょう。

まずWordPressのプラグインディレクトリに「hello-world」というディレクトリを作成してください。（スペースはハイフンで埋めます）
続いて「hello-worldディレクトリ」に「hello-world.php」というファイルを作成して標準プラグイン情報を記述します。

<?php
/*
Plugin Name: Hello World
Plugin URI: 
Description: Hello Worldを表示する
Version: 1.0.0
Author:oxy
Author URI: http://example.com
License: GPL2
*/
?>

最小構成はPlugin Nameだけで動作しますが、めんどくさがらずに全部入力しておきましょう。
Plugin URIはプラグインをWordPressの公式サイトにアップロードするときに入力するので空欄にしておいてください。

詳しくは後述しますが、LicenseはGPL2にしておいてください。

またプラグインで作成するファイルは全てUTF-8のBOMなしで保存してください。

プラグインのライセンスを追加する

Licenseに指定したGPL2はWordPressと同じライセンスです。簡単に解説すると「誰でもプラグインを自由に使用でき、再配布や改変をした場合でも同じ条件を継承する」というライセンスです。

2017/9/13 追記

WordPress公式のPlugin Handbookなる解説ページでライセンスについて解説されています。
ライセンスの文言も最新のものが掲載されています。詳しくはIncluding a Software Licenseページを参照してください。

ライセンスを有効にするには以下の記述が必須になります。
上で追加した「プラグインの基本情報」の後に続けて記述してください。

<?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
*/
?>

変更するのは「作成年」「ラグイン作者名」「プラグイン作者のメールアドレス」の3点のみです。
他の文言を1文字でも変更するとライセンスが無効になるので注意してください。

今回は以下のようにしました。

<?php
/*  Copyright 2015 Oxy (email : oxy@oxynotes.com)

    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プラグインの仕組みとクラスを利用したより実践的な解説」ではフックやテンプレートタグを使って動作させます。