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

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

プラグインでデータベーステーブルを作る

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

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

  • 設定情報 -- プラグインを有効化したときにユーザが最初に入力した値のこと。大幅に変更されることはあまりありません(例えば、タグ関連プラグインの場合、ユーザが選ぶのはタグ・クラウドのフォーマットぐらいです)。
    設定情報は通常、WordPress の options メカニズムを使って保存されます。
  • データ -- ユーザがプラグインを使い続けることで増えていく情報。通常は投稿、カテゴリー、ファイルアップロードなどの WordPress コンポーネントに関連するもの(例えば、統計情報に関するプラグインの場合、ページ閲覧数やリファラーなどの投稿に関連する統計情報)です。
    データは通常、別の MySQL テーブルに保存されるので、新たに作る必要があります。しかし、まったく新しいテーブルに飛びつく前に、プラグインのデータを WordPress の投稿メタ(カスタムフィールド)へ保存してうまくいくか検討してみてください。投稿メタは望ましい方法ですので、可能であり実用的なら利用してください。

この記事は、プラグインがデータを保存するために 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"; 
}

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

次のステップでは、実際にテーブルを作成します。直接 SQL クエリを実行するより、wp-admin/includes/upgrade.php にある dbDelta 関数を使いましょう(このファイルはデフォルトだと読み込まれないので、インクルードする必要があります)。dbDelta 関数は現在のテーブル構造を走査し、作成予定のテーブル構造と比較します。そして、必要に応じてテーブルを追加・変更してくれるので、更新にはとても便利な関数です(dbDelta の使用例については wp-admin/includes/schema.php 参照)。注意dbDelta 関数はやや融通がききません。こんな風にです:

  • 1 行につき、ひとつのフィールドを定義してください。〔訳注:ひとつの行に複数のフィールド定義を書くことはできません。さもなくば ALTER TABLE が正しく実行されず、プラグインのバージョンアップに失敗します。〕
  • PRIMARY KEY というキーワードと、主キーの定義の間には、二つのスペースが必要です。
  • INDEX という同義語ではなく、KEY というキーワードを使う必要があります。さらに最低ひとつの KEY を含めなければなりません。
  • フィールド名のまわりにアポストロフィ(')やバッククォート(`)を使ってはいけません。
  • フィールドタイプはすべて小文字であること。
  • SQL キーワード、例えば CREATE TABLE や UPDATE は、大文字であること。
  • 長さパラメータを受け付けるすべてのフィールドに長さを指定すること。例えば int(11) のように。

この注意事項に従って、関数に以下のような行を追加すれば、テーブルを自動生成・更新します。$sql 変数に、自分が作りたいテーブル構造を代入してください。

global $wpdb;

$charset_collate = $wpdb->get_charset_collate();

$sql = "CREATE TABLE $table_name (
  id mediumint(9) NOT NULL AUTO_INCREMENT,
  time datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
  name tinytext NOT NULL,
  text text NOT NULL,
  url varchar(55) DEFAULT '' NOT NULL,
  UNIQUE KEY id (id)
) $charset_collate;";

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

参考:上のコードで、テーブルのデフォルト文字セットと照合順序を指定しています。もし、これを省くと、一部の文字がテーブルへ格納されるときに ? の並びへ変換されてしまう可能性があります。この例では $wpdb->get_charset_collate() 関数を使って文字セットと照合順序を取得します。この関数は WordPress 3.5 で導入されたので、以前のバージョンをサポートする必要がある場合は、文字セットと照合順序を表す文字列を自分で作る必要があります(この関数のソースコードを複製してもよいでしょう)。

初期データを登録する

最後に、作成したテーブルになんらかのデータを登録するとしましょう。下記の例がそのやり方です:

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

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

$wpdb->insert(
  $table_name,
  array(
    'time' => current_time( 'mysql' ),
    'name' => $welcome_name,
    'text' => $welcome_text,
  ) 
);

参考WPDB の使い方について詳しくは wpdb クラスを参照してください。 今回は $wpdb->insert を使っているので、データは自動的にエスケープされます。もし $wpdb->query のような別のメソッドを使う必要がある場合は、セキュリティ問題を避けるため、クエリをデータベースへ渡す前に変数を $wpdb->prepare 関数に通すべきです。この例の関数は $welcome_name$welcome_text を定義しており、値に SQL 特殊文字が含まれないことが分かっていますが、それでもです。

バージョンオプション

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

add_option( "jal_db_version", "1.0" );

完成した関数

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

<?php

global $jal_db_version;
$jal_db_version = '1.0';

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

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

  $charset_collate = $wpdb->get_charset_collate();

  $sql = "CREATE TABLE $table_name (
    id mediumint(9) NOT NULL AUTO_INCREMENT,
    time datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
    name tinytext NOT NULL,
    text text NOT NULL,
    url varchar(55) DEFAULT '' NOT NULL,
    UNIQUE KEY id (id)
  ) $charset_collate;";

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

  add_option( 'jal_db_version', $jal_db_version );
}

function jal_install_data() {
  global $wpdb;

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

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

  $wpdb->insert(
    $table_name,
    array(
      'time' => current_time( 'mysql' ),
      'name' => $welcome_name,
      'text' => $welcome_text,
    )
  );
}

関数を呼び出す

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

register_activation_hook( __FILE__, 'jal_install' );
register_activation_hook( __FILE__, 'jal_install_data' );

詳しくは register_activation_hook() を見てください。

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

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

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

<?php

global $wpdb;
$installed_ver = get_option( "jal_db_version" );

if ( $installed_ver != $jal_db_version ) {

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

  $sql = "CREATE TABLE $table_name (
    id mediumint(9) NOT NULL AUTO_INCREMENT,
    time datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
    name tinytext NOT NULL,
    text text NOT NULL,
    url varchar(100) DEFAULT '' 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 も変更する必要があります。もちろん、初期化用の関数も、新しいテーブル構造を扱えるように変更しなければならないでしょう。

WordPress バージョン 3.1 から、register_activation_hook() で登録された初期化用の関数は、プラグインの更新時に呼び出されなくなりました。従って、プラグインをアップグレードした後に上記のコードを実行するには、プラグインのデータベースバージョンを別のフックでチェックする必要があります。そしてデータベースバージョンが古ければ関数を呼び出します。次のようなやり方です:

function myplugin_update_db_check() {
  global $jal_db_version;
  if ( get_site_option( 'jal_db_version' ) != $jal_db_version ) {
    jal_install();
  }
}
add_action( 'plugins_loaded', 'myplugin_update_db_check' );

関連項目

プラグイン開発についてもっと詳しい情報は、様々な情報をカバーした プラグイン・リソース を見てください。wp-hackers メーリングリスト にある記事も助けになるでしょう: WordPress Hackers Mailing List: Answer to Plugin Requires Additional Tables。これもどうぞ: Post meta vs separate database tables

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