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

投稿日:2019年3月7日 最終更新日:2020年4月17日

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

wpdbクラスの概要

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

インスタンスの扱い方

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

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

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

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

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

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

SQLのエスケープ

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

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

任意のSQLを実行する関数

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

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

引数

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

戻り値

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

サンプル

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

データ抽出(select)

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

引数

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

戻り値

第2引数で指定した型の要素を持つ配列が返却され、この配列の1つ1つの要素が行と対応しています。

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

サンプル

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

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

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

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

データ登録(insert)

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

引数

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

戻り値

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

サンプル

データ変更(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()メソッドを利用します。

引数

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

戻り値

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

サンプル

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

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

任意のDDLを実行

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

テーブルの作成・変更

テーブルの作成・変更をしたい場合は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()関数を利用するサンプルです。
サンプル中に記述はされていませんが、設定中のテーブル名接頭辞を取得してから、登録テーブル名にも利用するといった手順を踏む方が安全です。

2 件のコメント

chocozukushi より:

質問です!

INSERT、UPDATE、REPLACE、DELETEはそれぞれ$wpdb->insert、$wpdb->update、$wpdb->replace、$wpdb->deleteがあると思いますが、

それらで書くのと、$wpdb->prepareを使って書くのとではセキュリティ的にどちらがよいのでしょうか?

one-engineer より:

https://wpdocs.osdn.jp/%E3%83%87%E3%83%BC%E3%82%BF%E6%A4%9C%E8%A8%BC#Database
をみると、どちらも同様にエスケープされるようなので、どちらがよりセキュリティが強固になるか?という観点では変わらないと思います。

コメントはこちらから

メールアドレスは公開されませんのでご安心ください。また、* が付いている欄は必須項目となります。


内容に問題なければ、下記の「コメントを送信する」ボタンを押してください。