• サイトデザイン工事中です。ご意見をお寄せください。
  • 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。（詳細）

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

関数リファレンス/wpdb Class

提供：WordPress Codex 日本語版
移動： 案内, 検索

目次

データベースへの接続

WordPress にはデータベース操作用のクラス関数が用意されています。このクラスは wpdb と呼ばれており、大まかな部分では ジャスティン・ヴィンセント氏が作成し、管理している ezSQL クラスに基づいています。

使い方の注意

wpdb クラスのメソッドは、直接呼び出すべきではありません。WordPress にはデータベースと対話するために設定されたクラスをインスタンス化した $wpdb というグローバル変数があります。常に、このグローバル変数 $wpdb を使うようにしましょう ($wpdb をカスタム関数の中で使う前に、グローバル宣言を忘れないようにしましょう)。

$wpdb オブジェクトは WordPress データベースにあるすべてのテーブルからデータを読み出すために利用できます。これには、WordPress が標準で作成する以外のテーブルも含まれます。例えば、"mytable" というカスタムテーブルから情報を SELECT するには、以下のようにします。 

$myrows = $wpdb->get_results( "SELECT id, name FROM mytable" );

$wpdb オブジェクトは好きな数のテーブルを操作できますが、接続できるのは1つのデータベースだけです (WordPress 用のデータベース)。もし他のデータベースに接続したいという珍しいケースの場合は、適切な接続情報を使って wpdb クラスから独自のオブジェクトをインスタンス化する必要があります。複数のデータベースを使った非常に複雑な構成の場合は、hyperdb の利用を検討してみてください。

データベースへ任意のクエリを送信

query 関数を使えば、WordPress データベースであらゆる SQL クエリを実行できます。ただし、SELECT クエリにはより明確な関数 (下記参照) を使うのが一番良いでしょう。

<?php $wpdb->query('query'); ?>

query 
(文字列) 実行したい SQL クエリ。

この関数は影響する行または選択された行の数に対応する整数を返します。もし MySQL エラーが発生した場合は、FALSE を返します (注: 0 または FALSE が返される可能性があるため、正しい比較演算子を使うように心がけてください。例えば、等価演算子 == や 厳密な等価演算子 ===)。

注: このクラスの SQL クエリを実行するすべての関数と同様、入力値は SQL エスケープする必要があります (例: wpdb->escape($user_entered_data_string))。詳しくは以下の "[#Protect_Queries_Against_SQL_Injection_Attacks SQL インジェクション攻撃からクエリを保護する]" セクションを読んでください。

例

ID が13の投稿から 'gargle' メタキーおよび値を削除する。 

$wpdb->query("
	DELETE FROM $wpdb->postmeta WHERE post_id = '13'
	AND meta_key = 'gargle'");

WordPress の delete_post_meta() 内で実行されます。

ID が15の固定ページの親ページを、ID が7のページに指定する。 

$wpdb->query("
	UPDATE $wpdb->posts SET post_parent = 7
	WHERE ID = 15 AND post_status = 'static'");

変数の SELECT

get_var 関数はデータベースから変数を一つ返します。変数は一つしか返ってきませんが、クエリの結果はすべてキャッシュされ、あとから使うことができます。結果にマッチするものがない場合、NULL が返されます。

<?php $wpdb->get_var('query',column_offset,row_offset); ?>

query 
(文字列) 実行したい SQL クエリ。パラメータを null にすると、前回のクエリ結果のキャッシュ中から指定した変数を返す。
column_offset 
(整数) 必要としている列のオフセット (一つ目は 0)。初期値は 0。
row_offset 
(整数) 必要としている行のオフセット (一つ目は 0)。初期値は 0。

例

ユーザーの数を取得し表示する。 

<?php
$user_count = $wpdb->get_var($wpdb->prepare("SELECT COUNT(*) FROM $wpdb->users;"));
echo '<p>現ユーザー数は、' . $user_count . '人です。</p>';
?>

カスタムフィールドの数値合計を返し、表示する。 

<?php
$meta_key = 'kilometers'; //実在するメタキーに変更する
$kms=$wpdb->get_var($wpdb->prepare("SELECT sum(meta_value) FROM $wpdb->postmeta WHERE meta_key = %s", $meta_key));
echo '<p>合計距離は'. $kms . 'kmです。</p>';
?>

行の SELECT

クエリから行全体を取り出すには、get_row を使います。この関数を使うと行がオブジェクト、連想配列、またはインデックス配列として返されます。クエリが一つ以上の行にマッチする場合は、あとから使えるようにすべての行がキャッシュされますが、実際に返されるのは指定された行のみです。

<?php $wpdb->get_row('query', output_type, row_offset); ?>

query 
(文字列) 実行したいクエリ。
output_type 
以下の定数のいずれか。初期値は OBJECT。
  • OBJECT - 結果をオブジェクトとして出力。
  • ARRAY_A - 結果を連想配列として出力。
  • ARRAY_N - 結果をインデックス配列として出力。
row_offset 
(整数) 必要としている行のオフセット (一つ目は 0)。初期値は 0。

例

リンク ID 10に関する情報をすべて取得する。 

$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10");

$mylink オブジェクトの属性は、SQL クエリ結果のカラム名になります (この例の場合、$wpdb->links テーブル内のすべてのカラム)。 

echo $mylink->link_id; // "10" をプリント

一方、 

$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_A);

を使うと、結果は以下の連想配列になります。 

echo $mylink['link_id']; // "10" をプリント

また、 

$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_N);

を使うと、結果はインデックス配列になります。 

echo $mylink[1]; // "10" をプリント

列の SELECT

列を SELECT するには、get_col を使います。この関数は. 多次元配列を出力します。クエリによって複数の列が返された場合、列は一つしか返ってきませんが、クエリの結果はすべてキャッシュされ、あとから使うことができます。

<?php $wpdb->get_col('query',column_offset); ?>

query 
(文字列) 実行したい SQL クエリ。パラメータを null にすると、前回のクエリ結果のキャッシュ中から指定した行を返す。
column_offset 
(整数) 必要としている列のオフセット (一つ目は 0)。初期値は 0。

例

車に関するブログがあるとします。ブログの投稿はそれぞれ、ある車 (例: 1969年製のフォードマスタング) について書かれており、その車のモデル・製造年・メーカーという3つのカスタムフィールドが設定されています。以下の例では、メーカー名 (フォード) によってフィルターされた投稿のタイトルを、モデルと製造年でソートして出力する場合のコードを紹介しています。

wpdb Class の get_col を使って、条件に合うすべての投稿の ID の配列を正しい順に並べて取得します。それから foreach を使って投稿 ID の配列を反復し、各投稿のタイトルを表示します。この例は Andomar が作成しました。 

<?php 
$meta_key1 = 'モデル';
$meta_key2 = '製造年';
$meta_key3 = 'メーカー';
$meta_key3_value = 'フォード';

$postids=$wpdb->get_col($wpdb->prepare("
SELECT      key3.post_id
FROM        $wpdb->postmeta key3
INNER JOIN  $wpdb->postmeta key1 
            on key1.post_id = key3.post_id
            and key1.meta_key = %s 
INNER JOIN  $wpdb->postmeta key2
            on key2.post_id = key3.post_id
            and key2.meta_key = %s
WHERE       key3.meta_key = %s 
            and key3.meta_value = %s
ORDER BY    key1.meta_value, key2.meta_value",$meta_key1, $meta_key2, $meta_key3, $meta_key3_value)); 

if ($postids) {
  echo $meta_key3_value . '一覧 (' . $meta_key1 . '・' . $meta_key2 .'順)';
  foreach ($postids as $id) { 
    $post=get_post(intval($id));
    setup_postdata($post);?>
    <p><a href="<?php the_permalink() ?>" rel="bookmark" title="<?php the_title_attribute(); ?>へのパーマリンク"><?php the_title(); ?></a></p>
    <?php
  } 
}
?>

一般的な結果の SELECT

get_results を使うと、データベースから一般的な複数行の結果を取ってくることができます。この関数はクエリの結果全体を配列として返します。この配列の各要素はクエリ結果の各行と対応しており、get_row と同じくオブジェクト、連想配列、またはインデックス配列のいずれかを指定することができます。

<?php $wpdb->get_results('query', output_type); ?>

query 
(文字列) 実行したい SQL クエリ。パラメータを null にすると、前回のクエリ結果のキャッシュ中からデータを返す。
output_type 
以下の定数のいずれか。初期値は OBJECT。詳細および例については、行の SELECT セクションを参照。
  • OBJECT - 結果をオブジェクトとして出力。
  • ARRAY_A - 結果を連想配列として出力。
  • ARRAY_N - 結果をインデックス配列として出力。

例

ID が５のユーザーのすべての下書きの ID とタイトルを取得して、タイトルを echo。 

$fivesdrafts = $wpdb->get_results("SELECT ID, post_title FROM $wpdb->posts
	WHERE post_status = 'draft' AND post_author = 5");

foreach ($fivesdrafts as $fivesdraft) {
	echo $fivesdraft->post_title;
}

ID が５のユーザーの下書き情報をすべて取得。 

<?php
$fivesdrafts = $wpdb->get_results("SELECT * FROM $wpdb->posts
	WHERE post_status = 'draft' AND post_author = 5");
if ($fivesdrafts) :
	foreach ($fivesdrafts as $post) :
		setup_postdata($post);
?>
	<h2><a href="<?php the_permalink(); ?>" rel="bookmark"
		title="<?php the_title(); ?>へのパーマリンク"><?php the_title(); ?></a></h2>
<?php
	endforeach;
else :
?>
    <h2>見つかりません</h2>
<?php endif; ?>

行の INSERT

テーブルに行を挿入。

例

列に2つ (1つ目は文字列、2つ目は数値) 行を挿入。 

$wpdb->insert( 'table', array( 'column1' => 'value1', 'column2' => 123 ), array( '%s', '%d' ) )

使用できる値: - %s (文字列) - %d (十進記数法) - %f (浮動小数点数)


列の UPDATE

テーブル内の列を更新。

例

ID が1、一つ目の列の値が文字列、2つ目の列の値が数値、という行を更新する。 

$wpdb->update( 'table', array( 'column1' => 'value1', 'column2' => 'value2' ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )

SQL インジェクション攻撃からクエリを保護する

WordPress での SQL エスケープについてのより詳しい概要は、データベースのデータ検証ページをご覧ください。これはコア貢献者やプラグイン作者が 必ず読むべき ページです。

簡単にいうと、SQL インジェクション攻撃からクエリを保護するためには、実行する前にクエリデータはすべて SQL エスケープする必要があります。これを行う際には、sprintf() に似た構文を持つprepare メソッドを使うと便利です。

<?php $sql = $wpdb->prepare( 'query'[, value_parameter, value_parameter ... ] ); ?>

query 
(文字列) 実行したい SQL クエリ。%s および %d がプレースホルダーになる。
value_parameter 
(整数|文字列) プレースホルダーに代入する値。すでに SQL エスケープされている値は使えない。

例

ID 10の投稿に、"孔子の教え" => "故きを温めて新しきを知る､以て師と為るべし。" というメタキー => 値のペアを追加する。 

$metakey = "孔子の教え";
$metavalue = "故きを温めて新しきを知る､以て師と為るべし。";

$wpdb->query( $wpdb->prepare( "
	INSERT INTO $wpdb->postmeta
	( post_id, meta_key, meta_value )
	VALUES ( %d, %s, %s )", 
        10, $metakey, $metavalue ) );

add_meta() によって WordPress 内で実行される。

文字列をクオートで囲む必要がない点に注目しましょう。SQL クエリに変数を直接渡すのではなく、文字列には %s プレースホルダーを、整数には %d プレースホルダーを使っています。渡す値の数に制限はありません。それぞれ、prepare() メソッドで新しいパラメーターにします。

SQL エラーの表示・非表示

show_errors と hide_errors を使い、エラーの出力を有効化・無効化できます。

<?php $wpdb->show_errors(); ?> <?php $wpdb->hide_errors(); ?>

最後に実行されたクエリにエラーがある場合、print_error でそのエラーを表示できます。

<?php $wpdb->print_error(); ?>

列情報の取得

get_col_info を使えば、最後に実行したクエリ結果の列に関する情報を取得できます。これは、関数が属性が分からない OBJECT を返してきた際に便利です。この関数は指定した列から取得したい情報を出力します。列が指定されていない場合は、クエリ結果に含まれるすべての列の情報を含む配列を出力します。

<?php $wpdb->get_col_info('type', offset); ?>

type 
(文字列) 取得したい情報。以下の値から選べる (ezSQL のドキュメンテーションから転載)。初期値は name。
  • name - カラム名 (初期値)。
  • table - 列が含まれるテーブル名。
  • max_length - 列の最長値。
  • not_null - 列が NULL の値をとれない場合は1。
  • primary_key - 列がプライマリーキーの場合は1。
  • unique_key - 列がユニークキーの場合は1。
  • multiple_key - 列がユニークキーでない場合は1。
  • numeric - 列が numeric の場合は1。
  • blob - 列が BLOB の場合は1。
  • type - 列の type。
  • unsigned - 列が unsigned の場合は1。
  • zerofill - 列が zero-filled の場合は1。
offset 
(整数) 情報を取得するカラムを指定する (0 が最初のカラム)。初期値は -1。
  • -1 - すべてのカラムの情報を取得し、配列として出力する。初期値。
  • Non-negative integer - 指定した列の情報を取得する (0 が最初)。

キャッシュのクリア

SQL の結果のキャッシュは、flush でクリアできます。

<?php $wpdb->flush(); ?>

これにより、$wpdb->last_result、$wpdb->last_query、$wpdb->col_info がリセットされます。

クラス変数

$show_errors 
エラーの echo が有効化されているかどうか。デフォルトは TRUE 。
$num_queries 
実行されたクエリの数。
$last_query 
最後に実行されたクエリ。
$queries 
SAVEQUERIES 定数を TRUE に設定することで (定数の初期値は FALSE)、データベースで実行するクエリおよに停止時間を保存できる。SAVEQUERIES が TRUE の場合、クエリはこの変数に配列として保存される。
$last_result 
最後に実行されたクエリの結果。
$col_info 
最後に実行されたクエリの列情報。列情報の取得セクションを参照。
$insert_id 
最後に実行された INSERT クエリで、AUTO_INCREMENT によって生成された ID。
$num_rows 
最後に実行されたクエリで返された行の数。

テーブル

wpdb を使って簡単に WordPress データベーステーブルを参照できます。

$posts 
posts (投稿・固定ページ) テーブル。
$users 
The table of users (ユーザー) テーブル。
$comments 
The comments (コメント) テーブル。
$links 
The table of links (リンク情報) テーブル。
$options 
The options (設定情報) テーブル。
$postmeta 
The postmeta (= メタコンテンツ、カスタムフィールド) テーブル。
$usermeta 
The usermeta (ユーザーメタ情報) テーブル。ニックネーム、説明、パーミッションなどユーザーに関する追加情報を含む。
$terms 
terms (キーワード情報) テーブル。カテゴリーの説明、リンクカテゴリー、タグなどの情報を含む。
$term_taxonomy 
The term_taxonomy テーブル。キーワード (terms) のクラスであるタクソノミーの情報を含む。タクソノミーとは、投稿カテゴリー、リンクカテゴリー、タグ、その他のカスタムタクソノミーを指す。
$term_relationships 
The term_relationships テーブル。キーワード (terms) と、そのキーワードを使っているオブジェクトの関係性を示す情報を含む。投稿カテゴリーがどの投稿に適用されているか、など。

最新英語版： WordPress Codex » Function_Reference/wpdb_Class （最新版との差分）

「http://wpdocs.sourceforge.jp/%E9%96%A2%E6%95%B0%E3%83%AA%E3%83%95%E3%82%A1%E3%83%AC%E3%83%B3%E3%82%B9/wpdb_Class」より作成
個人用ツール
名前空間
変種
操作
このサイトについて
特集
サーバ別情報
リファレンス
ドキュメント整備
ツールボックス
他の言語