ワードプレスでwpdbクラスを使ったDB操作方法

ワードプレスにおいて、DBデータの取得・登録といった基本操作方法をまとめます。
wpdbクラスはワードプレスで用意されているクラスであり、ここにDB操作に必要な関数が定義されています。
codexをみても関数の種類が多く、"自分がどの関数を使えばよいかパッと見で判断できない"ということが多いため、早見表を作りました。

wpdbクラスの概要

詳細な内容は、codexのwpdbに関するページにて確認できます。

インスタンスの扱い方

接続したいDBによって、インスタンスの扱い方は以下となります。

ワードプレスで利用しているデータベースと接続したい場合

グローバル変数「$wpdb」にて、インスタンスを管理しています。
これは、ワードプレス側で管理しているため、開発者はインスタンス生成する必要がなく、単純に$wpdbにて関数呼び出しを行うことでDB操作が可能です。
以下、サンプルです。

上記のように、グローバル変数$wpdbを利用するためには、各テンプレートファイルにて『global $wpdb;』を宣言することで利用可能となります。

ワードプレスで利用していないデータベースと接続したい場合

必要なデータベース接続情報を設定の上で、インスタンスを新しく生成する必要があります。

基本的に、他システムのDBを直接参照するようなマネはしない方がよろしいので、今回はサンプルコードを割愛します。(というか調べてません。)

SQLのエスケープ[prepare()]

SQLインジェクション対策のために、wpdbクラスではprepare()メソッドが用意されています。
escape()メソッドやescape_by_ref()メソッドも用意されていますが、ver5.0.3時点では非推奨です。
特別な理由がなければprepare()メソッドを用いましょう。

引数

  • 第1引数:実行対象のSQL文
  • 第2引数以降:SQLのプレースフォルダに代入する値。オプション指定のため存在しない場合は未指定でOK。

戻り値

エスケープされたSQL文。

サンプル

以下のサンプルでは、foo=の部分に$name変数の値を、status=の部分に$status変数の値をそれぞれ代入した上で、SQL文を無害化しています。

より詳しく知りたい場合は、codexのデータ検証に関するページを参照してください。

任意のSQLを実行する関数[query()]

任意のSQLを実行するためには、query()メソッドを利用します。

引数として、prepare()メソッドの返り値を渡してあげます。

引数

  • 第1引数:実行対象のSQL文

戻り値

  • SQLの実行に成功した場合:True
  • SQLの実行に失敗した場合:False

サンプル

wpdbクラスを用いたデータ操作

複数行×複数列のデータ抽出(select)[get_result()]

一般的なselect文を発行して結果を得たい場合はget_results()メソッドを利用します。

引数

  • 第1引数:実行対象のselect文
  • 第2引数:戻り値の型としてOBJECT、OBJECT_K、ARRAY_A、ARRAY_Nのどれかを指定

戻り値

第2引数で指定した型のデータが返却されます。詳細はサンプル部分をご確認ください。

  • OBJECT:行レコードをオブジェクト化したもののインデックス配列
  • OBJECT_K:行レコードをオブジェクト化したものの連想配列(キーは第1カラムの値)
  • ARRAY_A:行レコードを連想配列化したもののインデックス配列
  • ARRAY_N:行レコードをインデックス配列化したもののインデックス配列

サンプル

第2引数で「OBJECT」を指定した場合。

第2引数で「OBJECT_K」を指定した場合。

第2引数で「ARRAY_A」を指定した場合。

第2引数で「ARRAY_N」を指定した場合。

単一列のデータ抽出(select)[get_col()]

引数

  • 第1引数:実行対象のselect文
  • 第2引数:取得対象の列番号(1列目を指定する時は0を指定)

第2引数は、複数列取得される場合に、何列目を取得対象とするか?を指定できます。

戻り値

取得した列の配列

サンプル

単一行のデータ抽出(select)[get_row()]

引数

  • 第1引数:実行対象のselect文
  • 第2引数:戻り値の型としてOBJECT、ARRAY_A、ARRAY_Nのどれかを指定
  • 第3引数:取得対象の行番号

戻り値

取得した行情報。第2引数で指定した型のデータで返却される。

  • OBJECT:行レコードをオブジェクト化したもののインデックス配列
  • ARRAY_A:行レコードを連想配列化したもののインデックス配列
  • ARRAY_N:行レコードをインデックス配列化したもののインデックス配列

各型の扱い型については、get_result()のサンプル部分にまとめていますので、そちらをご参照ください。

サンプル

単一の値データ抽出(select)[get_var()]

引数

  • 第1引数:実行対象のselect文
  • 第2引数:取得対象の列番号(1列目を指定する時は0を指定)
  • 第3引数:取得対象の行番号(1行目を指定する時は0を指定)

第2引数と第3引数は、select句で複数列×複数行の取得を指定した際に、何列目の何行目の値をget_var()での取得値とするかを指定することができます。

戻り値

取得できた単一の値。

サンプル

データ登録(insert)[insert()]

insert文の実行を行いたい場合はinsert()メソッドを利用します。

引数

  • 第1引数:対象テーブル
  • 第2引数:挿入データ(キー:カラム名、値:設定値の連想配列で設定)
  • 第3引数:データフォーマット(第2引数と対応させる形で配列で指定)(%s:文字列、%d:整数、%f:浮動小数点数のいずれかを指定)

戻り値

  • 行を挿入できた場合:1(insertできた行数=常に1)
  • 行の挿入に失敗した場合:false

サンプル

データ変更(update)[update()]

登録済みデータの変更については、update()とreplace()の2パターンありますが、replace()は使いにくそうなので、update()を使うこととします。

引き数

  • 第1引数:対象テーブル
  • 第2引数:更新するデータ(キー:カラム名、値:設定値の連想配列で設定)
  • 第3引数:where句として使う名前付き配列(キー:カラム名、値:設定値の連想配列で設定)
  • 第4引数:データフォーマット(第2引数と対応させる形で配列で指定)(%s:文字列、%d:整数、%f:浮動小数点数のいずれかを指定)
  • 第5引数:データフォーマット(第3引数と対応させる形で配列で指定)(%s:文字列、%d:整数、%f:浮動小数点数のいずれかを指定)

戻り値

  • 更新に成功した場合:1(更新されたレコード数=1)
  • 指定データと既存データが同一だった場合:0(更新されない=更新されたレコード数が0)
  • 更新に失敗した場合:false

サンプル

データ削除(delete)[delete()]

delete文発行したい場合はdelete()メソッドを利用します。

引数

  • 第1引数:テーブル名
  • 第2引数:where句として使う名前付き配列(キー:カラム名、値:設定値の連想配列で設定)
  • 第3引数:データフォーマット(第2引数と対応させる形で配列で指定)(%s:文字列、%d:整数、%f:浮動小数点数のいずれかを指定)

戻り値

  • 行削除できた場合:1(削除された行数=1)
  • 削除対象行が存在しなかった場合:0(削除された行数=0)
  • エラーが発生した場合:false

サンプル

wpdbクラスを用いたデータ定義

プラグインを作成する際は、専用のテーブルを定義することがあります。
その際は、以下の2種類の関数を用いて実現できます。
また、テーブル定義用の関数を実装したら、プラグインのメインファイルにて以下のように呼び出しを行い、プラグインインストール時に適用されるようにします。

任意のDDLを実行[query()]

query()メソッドを利用します。
こちらのメソッドの利用方法については、すでに説明済みのためここでは省略します。

テーブルの作成・変更[dbDelta()]

テーブルの作成・変更をしたい場合はdbDelta()関数を利用することもできます。
この関数の引数としてcreate文を渡してやると、テーブルが存在しない場合は作成し、テーブルがすでに存在する場合は差分をalter tableで反映してくれます。
ただし、利用するに当たって以下の制約があるため、標準SQLの利用に慣れている人はquery()メソッドで一本化してもよさそうに思います。

dbDelta()関数利用時の制約

実行するcreate文を作成する際に、以下の制約があります。

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

引数

  • 第1引数:SQL

戻り値

なし。

サンプル

以下、dbDelta()関数を利用するサンプルです。
サンプル中に記述はされていませんが、設定中のテーブル名接頭辞を取得してから、登録テーブル名にも利用するといった手順を踏む方が安全です。