関数リファレンス/wpdb Class

この項目「関数リファレンス/wpdb Class」は、翻訳チェック待ちの項目です。加筆、訂正などを通して、Codex ドキュメンテーションにご協力下さい。

データベースと話す: wpdb クラス

WordPressにはwpdbというクラスが定義されています。このクラスには、データベースとのやりとりに使用される一連の関数が含まれています。その主な目的は、WordPressデータベースとのインターフェイスを提供することですが、他の適切なデータベースと通信するために使用することもできます。クラスのコードはジャスティン・ヴィンセント氏が作成し、管理している ezSQL クラスに概ね基づいています。

$wpdb オブジェクトを使う

注意!: wpdb クラスのメソッドを直接呼び出すことはできません。代わりにグローバルの$wpdb オブジェクトを使用してください！

WordPressはグローバルオブジェクト変数 $wpdb を提供しています。これは/wp-includes/wp-db.phpに定義されているwpdbクラスのインスタンスです。 $wpdb はWordPressデータベースとやりとりするためにあらかじめインスタンス化されています。 WordPressのPHPコードで $wpdb にアクセスするには、globalキーワードを使用して$wpdbをグローバル変数として宣言するか、以下のようにしてスーパーグローバル $GLOBALSを使用します。

 // 1st Method - Declaring $wpdb as global and using it to execute an SQL query statement that returns a PHP object
 
 global $wpdb;
 $results = $wpdb->get_results( 'SELECT * FROM wp_options WHERE option_id = 1', OBJECT );
 
 // 2nd Method - Utilizing the $GLOBALS superglobal. Does not require global keyword ( but may not be best practice )
 
 $results = $GLOBALS['wpdb']->get_results( 'SELECT * FROM wp_options WHERE option_id = 1', OBJECT );

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

 $myrows = $wpdb->[[#SELECT_Generic_Results|get_results]]( "SELECT id, name FROM mytable" );

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

警告

このクラスの関数の中には、SQL文を入力として受け取るものがあります。 SQLインジェクション攻撃を防ぐために、SQLクエリーに組み込むすべての信頼できない値をエスケープする必要があります。使おうとしている機能がSQLをエスケープしているか、あるいはすでにエスケープされているかどうかを、ドキュメントで確認してください。

WordPressでのSQLエスケープの詳細については、下記のSQL インジェクション攻撃からクエリを保護するを参照してください。

変数の 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( "SELECT COUNT(*) FROM $wpdb->users" );
echo "<p>User count is {$user_count}</p>";
?>

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

<?php
// meta_key の値を、合計したいカスタムフィールドのメタキーにする
$meta_key = 'miles';
$allmiles = $wpdb->get_var( $wpdb->prepare( 
	"
		SELECT sum(meta_value) 
		FROM $wpdb->postmeta 
		WHERE meta_key = %s
	", 
	$meta_key
) );
echo "<p>合計マイルは {$allmiles}</p>";
?>

行の SELECT

クエリから行全体を取り出すには、get_row を使います。この関数を使うと行がオブジェクト、連想配列、またはインデックス配列として返されます。クエリが2行以上にマッチする場合は、後から使えるようにすべての行がキャッシュされますが、実際に返されるのは指定された行のみです。マッチする行がなければ NULL を返します。そのため、返された値を何かの引数として使う場合は注意してください(以下の例を見てください)。

使い方

<?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" をプリント

ID が10の行が links テーブルに無ければ null が返されます。そのため次の例は false になります:

if ($mylink != null) {
  // リンクについて何かする
  return true;
} else {
  // リンクが見つからなかった
  return false;
}

列の SELECT

列を SELECT するには、get_col を使います。この関数は一次元配列を出力します。クエリが複数の列を返した場合、指定された列だけが返ってきますが、後から使えるようにクエリの結果はすべてキャッシュされます。マッチする結果がなければ NULL を返します。そのため、返された値を何かの引数として使う場合は注意してください(以下の例を見てください)。

使い方

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

パラメータ

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

用例

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

wpdb クラスの 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 "List of {$meta_key3_value}(s), sorted by {$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
	} 
}
?>

次の例は、あるカスタムフィールドを持つ投稿をすべて表示します。そのときもう一つのカスタムフィールドの値で並べ替えます。

<?php
// カスタムフィールド Color を持つ投稿を、カスタムフィールド Display_Order の値でソートして表示する。
// どの投稿タイプも除外しない。
// 前提として、各投稿はカスタムフィールド Color と Display_Order をそれぞれちょうど1つ持つ。
$meta_key1 = 'Color';
$meta_key2 = 'Display_Order';

$postids = $wpdb->get_col( $wpdb->prepare( 
	"
	SELECT      key1.post_id
	FROM        $wpdb->postmeta key1
	INNER JOIN  $wpdb->postmeta key2
	            ON key2.post_id = key1.post_id
	            AND key2.meta_key = %s
	WHERE       key1.meta_key = %s
	ORDER BY    key2.meta_value+(0) ASC
	",
        $meta_key2,
	$meta_key1
) ); 

if ( $postids ) 
{
	echo "List of {$meta_key1} posts, sorted by {$meta_key2}";
	foreach ( $postids as $id ) 
	{
		$post = get_post( intval( $id ) );
		setup_postdata( $post );
		?>
		<p>
			<a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>">
				<?php the_title(); ?>
			</a>
		</p>
		<?php
	}
}
?>

一般的な結果を返す SELECT

get_results を使うと、データベースから一般的な複数行の結果を取得できます。この関数はクエリの結果全体を配列として返します。この配列の各要素はクエリ結果の各行と対応します。配列の型は、get_row と同じくオブジェクト、連想配列、またはインデックス配列のいずれかを指定できます。 1行も見つからないか、データベースエラーが発生した場合は、戻り値が空の配列になります。もし $query が空文字列であるか、無効な $output_type を指定すると、NULL が返されます。

使い方

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

パラメータ

query: (文字列) 実行したい SQL クエリ。
output_type: 以下の4つの定数のいずれか。初期値は OBJECT。詳細および例については、行の SELECT セクションを参照。

OBJECT - 結果をインデックス配列として出力。要素は行オブジェクト。
OBJECT_K - 結果を連想配列として出力。第1カラムの値をキー(重複は無視される)、行オブジェクトを値とする。
ARRAY_A - 結果をインデックス配列として出力。要素は1行を表す連想配列で、そのキーはカラム名。
ARRAY_N - 結果をインデックス配列として出力。要素は1行を表すインデックス配列。

この関数は内部で $wpdb->query() を使うので、クラス変数は適切にセットされます。'SELECT' クエリの結果(行カウント)は $wpdb->num_rows へ入ります。

用例

ID が5のユーザーのすべての下書きの 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 が5のユーザーの下書き情報をすべて取得。

<?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="Permalink: <?php the_title(); ?>">
				<?php the_title(); ?>
			</a>
		</h2>
		<?php
	}	
}
else
{
	?>
	<h2>Not Found</h2>
	<?php
}
?>

行の INSERT

テーブルへ行を挿入します。

使い方

<?php $wpdb->insert( $table, $data, $format ); ?>

パラメータ

table: (文字列) データを挿入するテーブル名。
data: (配列) 挿入するデータ。キーをカラム名、値を挿入する値とする。$data のカラム名と $data の値は両方とも "raw" であること(どちらも SQL エスケープしてはいけない)。
format: (配列|文字列) (オプション) $data の値それぞれに適用する書式の配列。文字列の場合、それが $data のすべての値に適用される。省略すると、$data のすべての値が文字列として扱われるが、wpdb::$field_typesによる指定があればそちらが優先される。

使用可能な書式の値(詳しくは後のプレースホルダーを参照):

%s - 文字列
%d - 整数 (すべて数字)
%f - 浮動小数点数

挿入した後、カラム AUTO_INCREMENT へ生成された ID は次の方法でアクセスできます:

$wpdb->insert_id

この関数は、行を挿入できなければ false を返します。挿入できたときは影響を受けた行数を返します(いつでも1です)。

注意: data パラメータの カラム名=>値 ペアにおける値はスカラーに限ります。値として配列(またはオブジェクト)を渡すと警告が発生します。この警告は例えば次のようなものです: "mysql_real_escape_string() expects parameter 1 to be string, array given on line 880 in file /var/www/html/wp-includes/wp-db.php"

用例

列を2つ(1つ目は文字列、2つ目は数値)持つ行を挿入します。

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

行の REPLACE

指定した行がテーブルにあれば置き換えます。なければ新しい行としてテーブルへ挿入します。

訳注: テーブルにプライマリーキーか、UNIQUE インデックスを用意しておかなければ REPLACE は利用できません。指定した行がすでに存在するかどうかを、キーまたは UNIQUE インデックスで調べるためです。

使い方

<?php $wpdb->replace( $table, $data, $format ); ?>

パラメータ

table: (文字列) 置き換えたいデータがあるテーブルの名前。
data: (配列) 置き換え後のデータ(列の名前 => 値 のペア)。$data の列の名前と値はどちらも "raw" にすること(どちらも SQL エスケープしてはいけない)。
format: (配列|文字列) (オプション) $data 内の値それぞれに適用する書式の配列。文字列の場合、それを書式として $data 内のすべての値へ適用する。省略すると $data 内のすべての値を文字列として扱うが、wpdb::$field_types に指定があればそちらを優先する。

使える書式の値は:

%s - 文字列
%d - 整数(全部が数字)
%f - 浮動小数点数。(詳しくはプレースホルダーを参照。)

もし $data 配列パラメータの要素数が MySql データベーステーブルに定義された列の数より多ければ、挿入は失敗して、この関数は false を返します。しかし $wpdb->last_error に失敗を説明するメッセージは入りません。挿入したいデータがデータベースへぴったり入るように自分で気をつけてください。MySQL がデータを切り捨ててくれると想定しないでください。

置き換えた後、AUTO_INCREMENT 列へ入れられた ID は次の方法でアクセスできます:

$wpdb->insert_id

この関数は影響を受けた行のカウントを返します。これは削除された行と挿入された行の合計数です。カウントが1なら単一行の REPLACE が行われた結果、1行が挿入され、どの行も削除されていません。カウントが1より大きければ、1行以上が削除され、かつ新しい行が挿入されています。なお、複数の古い行を1行で置き換える場合があります。それはテーブルが複数のユニークインデックスを持ち、新しい行が別々のユニークインデックスにより異なる行に対応づけられる場合です。

この関数は、既存の行を置き換えることができず、かつ新しい行を挿入することもできない場合、false を返します。

用例

ある行を置き換えます。第1の値が行の id で、2番目は文字列、3番目は数字です:

$wpdb->replace( 
	'table', 
	array( 
		'indexed_id' => 1,
		'column1' => 'value1', 
		'column2' => 123 
	), 
	array( 
		'%d',
		'%s', 
		'%d' 
	) 
);

行の UPDATE

テーブル内の行を更新します。エラーが生じると false を、成功すると影響を受けた行の数を返します。

使い方

<?php $wpdb->update( $table, $data, $where, $format = null, $where_format = null ); ?>

パラメータ

table: (文字列) 更新対象のテーブル名。
data: (配列) 更新するデータ(列名 => 値 ペア形式)。$data の列名と値は "raw" でなければならない(どちらも SQL エスケープしてはいけない)。例えば GET や POST のデータを使う場合、スラッシュがデータベースへ挿入されないように stripslashes() を使う必要があるかもしれません。
where: (配列) WHERE 句として使う名前付き配列(列名 => 値 ペア形式)。2つ以上の句は AND で結合される。$where の列名と値は "raw" でなければならない。
format: (配列|文字列) (オプション) $data の値それぞれに適用する書式の配列。文字列を指定すると、$data の値すべてに書式として適用される。
where_format: (配列|文字列) (オプション) $where の値それぞれに適用する書式の配列。文字列を指定すると、$where の値すべてに書式として適用される。

書式に指定できる値: ( 後の注記も見てください。)

%s - 文字列
%d - 整数(全部が数字)
%f - 浮動小数点数。
省略すると $where の値はすべて文字列と見なされる。

戻り値

この関数は影響を受けた行の数、またはエラーが発生すると false を返します。$data がデータベース内の既存データに一致した場合は 0 を返すことに注意してください。そのためエラー判定は false === $result が良いでしょう。

用例

ID が1である行を更新します。第1列の値は文字列、第2列の値は数値とします:

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

注意: %d はコンマ入りの値を扱えません。数字だけではない数値を扱うには、文字列(%s)を使ってください。

行の DELETE

delete 関数は WordPress 3.4.0 で追加されました。テーブルから行を削除するのに使います。使い方は update と insert にとてもよく似ています。削除された行の数を返しますが、エラーが発生すると false を返します。

使い方

<?php $wpdb->delete( $table, $where, $where_format = null ); ?>

パラメータ

$table

（文字列）（必須）テーブル名

初期値：なし

$where

（array）（必須） WHERE 句に使う連想配列（列の名前->値）。複数の句を指定すると AND で結合される。$where の列の名前と値は両方とも 'raw' でなければならない。

初期値：なし

$where_format

（文字列/配列）（オプション） $where の要素それぞれに適用する書式の配列。文字列を指定すると、それを書式として$where のすべての要素へ適用する。書式は '%d', '%f', '%s' (整数, 浮動小数点数, 文字列; 詳しくはプレースホルダーを参照)。省略すると $where の値はすべて文字列として扱われる(wpdb::$field_types に指定がある場合はそちらが優先)。

初期値： null

用例

// デフォルトの使い方。
$wpdb->delete( 'table', array( 'ID' => 1 ) );

// where 句の書式を指定。
$wpdb->delete( 'table', array( 'ID' => 1 ), array( '%d' ) );

任意のクエリの実行

query 関数を使うと WordPress データベースに対して任意の SQL クエリを実行できます。特定用途や複雑な SQL クエリが必要なときに最適です。情報を選び出すようなもっと基本的なクエリの場合は、ここまでに説明した他の wpdb 関数を見てください。

一般的な構文

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

パラメータ

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

この関数は SELECT, INSERT, DELETE, UPDATE などの影響を受けた、または選択された行の数を示す整数値を返します。SQL の CREATE, ALTER, TRUNCATE および DROP の場合(これらは特定の行ではなくテーブル全体へ影響します)、この関数は成功すると TRUE を返します。もし MySQL エラーが発生した場合は FALSE を返します。

参考: 行のクエリは 0 と FALSE のどちらも返す場合があるので、戻り値を調べるときに注意してください。厳密な等価演算子(===)を使って、エラー(false === $result)と、影響を受けた行の有無(0 === $result)を確かめましょう。

用例

ID が 13 の投稿から投稿メタ 'gargle' のキーと値を削除します。(ここで 'prepare' メソッドを使うのは、不正な操作や不正な文字を処理しないためです):

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

WordPress が delete_post_meta() の内部で実行するコード:

ID が 7 の固定ページへ親として ID が 15 の固定ページを設定する。

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

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

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

簡単にいうと、SQL インジェクション攻撃からクエリを保護するためには、実行する前にクエリデータをすべて SQL エスケープする必要があります。 WordPress では prepare メソッドがこの機能を提供します。sprintf() 風と vsprintf() 風の両方の書き方を利用できます。

注意: WordPress 3.5以降、wpdb::prepare() は 引数を2個以上 必要とします。[詳しくはこちら。]

使い方

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

パラメータ

query: (文字列) 実行したい SQL クエリ。%s および %d がプレースホルダーになる。
value_parameter: (整数|文字列|配列) プレースホルダーへ代入する値。sprintf() 風の書き方でたくさんの値を渡すことができます。別の方法として、PHP の関数 vsprintf() 風に値を並べた配列を第2引数にすることもできます。

注意: ユーザーが入力したものを直接このパラメータにしてはいけません。もしそうすると、複数のプレースホルダーを含む任意のクエリに対して配列操作を行ってしまいます。値は SQL エスケープしてはいけません。

プレースホルダー

prepare の query パラメータは sprintf() 風のプレースホルダーを使えます。書式は %s (文字列), %d (整数) and %f (浮動小数点数) がサポートされています。(%s と %d はこの関数がコアへ追加されたバージョン 2.3 から、ただし %f はバージョン 3.3 以降で使えます。) これらを除く % 文字列はエスケープしなければパースエラーを起こす可能性があります。SQL 文字定数の中で % を使う場合、LIKE のワイルドカードも含めて、 %% のように二重の % を書いてエスケープしなければなりません。%d, %f, %s はどれもクォートで囲まずにクエリ文字列へ書きます。注意: %d プレースホルダーは整数だけを受け付けるので、桁区切りのコンマを使った数値を %d で渡してはいけません。コンマ付きの値が必要なら代わりに %f を使ってください。

用例

ID が10の投稿へ、投稿メタを追加します。投稿メタは、キー => 値のペア "Harriet's Adages" => "WordPress' database interface is like Sunday Morning: Easy." です。

$metakey	= "Harriet's Adages";
$metavalue	= "WordPress' database interface is like Sunday Morning: Easy.";

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

同様の処理が WordPress の add_meta() /en で行われています。

同じクエリを vsprintf() 風の構文で書くと次のようになります。

$metakey = "Harriet's Adages";
$metavalue = "WordPress' database interface is like Sunday Morning: Easy.";

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

この例では値を配列にまとめています。この方法は、実行するときまで引数の個数がわからない場合に有用です。

文字列をクォートで囲む必要がない点に注目しましょう。SQL クエリに変数を直接入れて渡すのではなく、プレースホルダーとして文字列には %s、整数には %d、浮動小数点数には %f を使ってください。渡す値の個数に制限はなく、1つずつ prepare() メソッドの新しいパラメーターにします。

SQL エラーの表示・非表示

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

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

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

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

参考: マルチサイトの WordPress の場合、データベースを表示するには定数 DIEONDBERROR を次のように定義しなければなりません:

<?php define( 'DIEONDBERROR', true ); ?>

列情報の取得

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 - すべてのカラムの情報を取得し、配列として出力する。初期値。
0または正の整数 - 指定した列の情報を取得する (0 が最初)。

キャッシュの消去

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

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

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

クラス変数

$show_errors: エラーの表示が有効化されているかどうか。デフォルトは TRUE 。
$num_queries: 実行されたクエリの数。
$last_query: 最後に実行されたクエリ。
$last_error: MySQL で生成された最新のエラー文字列。
$queries: 定数 SAVEQUERIES を TRUE にすると(デフォルトは FALSE)、データベースで実行したクエリと終了時刻を保存できます。SAVEQUERIES が TRUE のとき、クエリが配列としてこの変数へ保存されます。
$last_result: 最後に実行されたクエリの結果。
$col_info: 最後に実行されたクエリの列情報。列情報の取得セクションを参照。
$insert_id: 最後に実行された INSERT クエリで、AUTO_INCREMENT によって生成された ID。
$num_rows: 最後に実行されたクエリで返された行の数。
$prefix: このサイトの WordPress テーブルに与えられたプリフィックス。

マルチサイト変数

マルチサイトを使用する場合、以下にアクセスする場合があります:

$blogid: 現在のサイト(ブログ)の ID。
$siteid: 現在のネットワーク(正式には "サイト")の ID。現在の WordPress は一つのマルチサイト型インストールに一つのネットワークだけをサポートします。将来は変わるかもしれませんが。

詳しくは以下をご覧ください:

WordPress: difference between site_id and blog_id?
http://stackoverflow.com/a/4189358/1924128 - Another good answer to the same question.

テーブル

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

$posts: posts (投稿・固定ページ) テーブル。
$postmeta: postmeta (メタコンテンツ、カスタムフィールド) テーブル。

$comments: comments (コメント) テーブル。
$commentmeta: 追加のコメント情報を含むテーブル。

$termmeta: タームのメタ情報を含むテーブル。
$terms: terms (キーワード情報) テーブル。カテゴリーの説明、リンクカテゴリー、タグなどの情報を含む。
$term_taxonomy: term_taxonomy テーブル。キーワード (terms) のクラスであるタクソノミーの情報を含む。タクソノミーとは、投稿カテゴリー、リンクカテゴリー、タグ、その他のカスタムタクソノミーを指す。
$term_relationships: term_relationships テーブル。キーワード (terms) と、そのキーワードを使っているオブジェクトの関係性を示す情報を含む。投稿カテゴリーがどの投稿に適用されているか、など。

$users: Users (ユーザー) のテーブル。
$usermeta: usermeta (ユーザーメタ情報) テーブル。ニックネーム、説明、パーミッションなどユーザーに関する追加情報を含む。

$links: links (リンク) のテーブル。
$options: options (設定情報) テーブル。

マルチサイトのテーブル

以下のテーブルはマルチサイトインストールでのみ使用されます。

$blogs: Blogs テーブル。これはネットワーク内に作成されたブログ(サイト)のリストです。

$signups: Signups テーブル。

$site: Site テーブル。これは WordPress インストールの中に作られたネットワーク (以前の WPMU では "sites" と呼ばれていました) のリストです。(このテーブルに普通はサイトが一つだけリストされます。)

$sitemeta: Network Options (Site Meta) テーブル。これはマルチサイトインストールの全体へ適用されるオプションを含みます。

$sitecategories: Site Categories テーブル。

訳注: Site Categories テーブルはデフォルトでは存在しません。詳しくは Ticket #12589 (Disable/Enable Global Terms) を見てください。

$registration_log: Registration Log テーブル。

$blog_versions: Blog Versions テーブル。

ソースファイル

wpdb() は wp-includes/wp-db.phpにあります。

外部資料

警告メッセージを改善することの効果 - WordPress のwpdb::prepareメソッドにおける実践

関数リファレンス/wpdb Class

目次

データベースと話す: wpdb クラス

$wpdb オブジェクトを使う

警告

変数の SELECT

使い方

パラメータ

用例

行の SELECT

使い方

パラメータ

用例

列の SELECT

使い方

パラメータ

用例

一般的な結果を返す SELECT

使い方

パラメータ

用例

行の INSERT

使い方

パラメータ

用例

行の REPLACE

使い方

パラメータ

用例

行の UPDATE

使い方

パラメータ

戻り値

用例

行の DELETE

使い方

パラメータ

用例

任意のクエリの実行

一般的な構文

パラメータ

用例

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

使い方

パラメータ

プレースホルダー

用例

SQL エラーの表示・非表示

列情報の取得

使い方

パラメータ

キャッシュの消去

クラス変数

マルチサイト変数

テーブル

マルチサイトのテーブル

ソースファイル

外部資料

関連項目

記事

コード・ドキュメンテーション

案内メニュー

検索