Creating Tables with Plugins

出典: WordPress Codex 日本語版

ページ名検討中： このページ名「Creating Tables with Plugins」について改名が提案されています。ご意見をお寄せください。

目次


もしWordPressプラグインの作成をしているなら、WordPressデータベースになんらかの情報を保存しておきたいと思うことでしょう。保存できる情報は主に二つあります:

  • 設定情報 -- プラグインを有効化したときにユーザが最初に入力した値のこと。大幅に変更されることはあまりありません(例えば、タグ関連プラグインの場合、ユーザが選ぶのはタグ・クラウドのフォーマットぐらいです)。設定情報は通常を使ってWordPressのopstionsメカニズムによって保存されます。
  • データ -- ユーザがプラグインを使い続けることで増えていく情報。通常は投稿、カテゴリー、ファイルアップロードなどのWordPressコンポーネントに関連するもの(例えば、タグ関連プラグインでは、タグ名および、タグと投稿の関連を示すデータ)です。データは通常、別のMySQLテーブルに保存されるので、新たに作る必要があります。

この記事はプラグインがデータを保存するためにMySQLテーブルを自動的に作成する方法について述べています。ここに書かれている方法の他には、プラグインをインストールするとき、ユーザにインストールスクリプトを実行してもらうものがあります。もう一つの方法では、ユーザ自ら phpMyAdmin/enのようなものを使って、SQLクエリを実行してもらうという手もあります。しかし、どちらもあまり満足の行くものとはならないでしょう。ユーザはインストールスクリプトの実行やクエリの発行をよく忘れます(もしかしたらphpMyAdminを使えない環境かもしれません)。

というわけで、以下のステップに従い、プラグインにテーブルを自動生成させることをオススメします:

  1. テーブルを生成するPHP関数を書く。
  2. プラグインが有効化されたときにWordPressがその関数を呼び出すようにする。
  3. プラグインの新しいバージョンを作成して、別のテーブル構造が必要になったらアップグレード用関数を作成する。

データベーステーブルの作成

プラグインにデータベーステーブルを自動生成させるための第一歩は、WordPressのMySQLデータベースにテーブルを生成するPHP関数を作ることです。この記事の意図を明確にするために、jal_install関数を呼び出すことだとしましょう。

データベーステーブルの接頭辞

WordPressサイトのオーナーはwp-config.phpファイル内にデータベーステーブル接頭辞を定義できます。デフォルトだと、接頭辞は"wp_"となっていますが、そこに入る値を考えて、データベーステーブル名を定義しましょう。この値は$wpdb->prefix変数に格納されています。(もし2.0よりも古いバージョンのWordPressを使用している場合、グローバル変数$table_prefixを使う必要があります。これは2.1から削除されました。)

(prefix)liveshoutboxという名前のテーブルを作成したければ、テーブル作成関数を以下のように始めましょう: 

function jal_install () {
   global $wpdb;

   $table_name = $wpdb->prefix . "liveshoutbox";

テーブルは作成済み?

テーブル作成の次のステップは、テーブルがすでに作られていないかをチェックすることです。次のif節ではテーブルを発見するためにSHOW TABLESSQLクエリが実行され、実行結果を作成予定のテーブル名と比較しています: 

    if($wpdb->get_var("SHOW TABLES LIKE '$table_name'") != $table_name) {

テーブルの作成または更新

次のステップでは、実際にテーブルを作成します。直接SQLクエリを実行するより、wp-admin/upgrade-functions.php(このファイルはデフォルトだと読み込まれないので、インクルードする必要があります)にあるdbDelta関数を使いましょう〔訳注：バージョン2.5以降ではwp-admin/include/upgrade.phpで定義されています〕。dbDelta関数は現在のテーブル構造を走査し、作成予定のテーブルと比較、必要に応じてテーブルを追加・修正します。更新にはとても便利な関数です(dbDeltaの使用例についてはwp-admin/upgrade-schema.phpを確認のこと〔訳注：このファイルはバージョン2.7に含まれません〕)。しかしながら、dbDelta関数はやや融通がききません。こんな風にです:

  • PRIMARY KEYと主キーの定義の間には二つのスペースが必要です。〔訳注：原文 "You have to have two spaces between the words PRIMARY KEY and the definition of your primary key."〕
  • INDEXという言葉ではなく、KEYという言葉を使う必要があります。

この忠告に従えって、関数に以下のような行を追加すれば、テーブルを自動生成・更新します。$sql変数にテーブル構造を代入してください。 

$sql = "CREATE TABLE " . $table_name . " (
	  id mediumint(9) NOT NULL AUTO_INCREMENT,
	  time bigint(11) DEFAULT '0' NOT NULL,
	  name tinytext NOT NULL,
	  text text NOT NULL,
	  url VARCHAR(55) NOT NULL,
	  UNIQUE KEY id (id)
	);";

require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
dbDelta($sql);

初期データを加える

最後に、作成したテーブルになんらかのデータを加えましょう。以下がそのやり方です: 

  $welcome_name = "Wordpressさん";
  $welcome_text = "おめでとうございます、インストールに成功しました！";

  $insert = "INSERT INTO " . $table_name .
            " (time, name, text) " .
            "VALUES ('" . time() . "','" . $wpdb->escape($welcome_name) . "','" . $wpdb->escape($welcome_text) . "')";

  $results = $wpdb->query( $insert );

注意点: この関数の$welcome_nameと$welcome_textは自ら定義したもので、SQL特殊文字が含まれていないことはわかっています。しかし、それでもデータベースに渡す前に変数に対して$wpdb->escape()関数を実行することは、セキュリティ問題と思いがけないバグを避けるために有効です。

バージョンオプション

データベース構造のバージョン番号を記録するオプションレコードを付け足すのもいいアイデアです。テーブルを更新するとき、この情報を使うことができます: 

add_option("jal_db_version", "1.0");

完成した関数

これで関数は完成しました。まとめて見てみましょう。バージョン番号がグローバル変数に格納されていることに注意してください。 


$jal_db_version = "1.0";

function jal_install () {
   global $wpdb;
   global $jal_db_version;

   $table_name = $wpdb->prefix . "liveshoutbox";
   if($wpdb->get_var("show tables like '$table_name'") != $table_name) {
      
      $sql = "CREATE TABLE " . $table_name . " (
	  id mediumint(9) NOT NULL AUTO_INCREMENT,
	  time bigint(11) DEFAULT '0' NOT NULL,
	  name tinytext NOT NULL,
	  text text NOT NULL,
	  url VARCHAR(55) NOT NULL,
	  UNIQUE KEY id (id)
	);";

      require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
      dbDelta($sql);

      $welcome_name = "Wordpressさん";
      $welcome_text = "おめでとうございます、インストールに成功しました！";

      $insert = "INSERT INTO " . $table_name .
            " (time, name, text) " .
            "VALUES ('" . time() . "','" . $wpdb->escape($welcome_name) . "','" . $wpdb->escape($welcome_text) . "')";

      $results = $wpdb->query( $insert );
 
      add_option("jal_db_version", $jal_db_version);

   }
}

関数を呼び出す

これで初期化関数を定義できたので、管理画面でプラグインが有効化されたときにWordPressがこの関数を呼び出せるようにしましょう。そのためには、activate_アクションフックを使います。もしもあなたのプラグインファイルがwp-content/plugins/plugindir/pluginfile.phpならば、プラグインのメインファイルに以下の一文を付け加えてください: 

register_activation_hook(__FILE__,'jal_install');

詳しくは関数リファレンス/register_deactivation_hook/enを見てください。

アップグレード用関数を追加する

プラグインの寿命が尽きて、アップグレード版ではデータベース構造を変更する必要が出てくるかもしれません。そのためには、アップグレード用のコードをプラグインファイルに含め、それに新しいバージョンがインストールされたことを関知させ、データベース構造を更新させてなくてはいけません。一番簡単な方法は先ほど作ったjal_install関数にコードを追加することです。

この関数が呼び出しを受けることをしっかり把握しておく必要があります。したがってアップグレード時はプラグインのユーザに対して、プラグインの無効化、新しいプラグインファイルのアップロード、そしてプラグインの再有効化という手順を踏むよう教える必要があります。

さて、上記の関数はあなたのプラグイン・バージョン1.0用のテーブルを作成するために使われたといましょう。いまやバージョン1.1にアップグレードし、URLフィールドは大きくなっています(55文字から100文字へ)。jal_install関数の最後に以下の行を加えて、バージョンチェックをし、必要ならばアップグレードしましょう: 


   $installed_ver = get_option( "jal_db_version" );

   if( $installed_ver != $jal_db_version ) {

      $sql = "CREATE TABLE " . $table_name . " (
	  id mediumint(9) NOT NULL AUTO_INCREMENT,
	  time bigint(11) DEFAULT '0' NOT NULL,
	  name tinytext NOT NULL,
	  text text NOT NULL,
	  url VARCHAR(100) NOT NULL,
	  UNIQUE KEY id (id)
	);";

      require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
      dbDelta($sql);

      update_option( "jal_db_version", $jal_db_version );
  }

ファイルの最初にあるグローバル変数$jal_db_versionも変更する必要があります。もちろん、新しいテーブル構造を作るために上で作られた初期化部分にも変更を加える必要があります。

関連情報

プラグイン開発に関してのより詳しい情報は、プラグイン開発情報の理解を助けるプラグイン・リソースを見てください。wp-hackers メーリングリスト/enにある記事も助けになるでしょう:WordPress Hackers Mailing List: Answer to Plugin Requires Additional Tables

最新英語版： WordPress Codex » Creating Tables with Plugins （最新版との差分）

"http://wpdocs.sourceforge.jp/Creating_Tables_with_Plugins" より作成
他の言語