当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

「関数リファレンス/wpdb Class」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(テーブル)
(使い方が「変数のSELECT」と同じコードになっていたため、修正)
 
(4人の利用者による、間の55版が非表示)
1行目: 1行目:
== データベースへの接続 ==
+
{{CheckTrans}}
  
WordPress にはデータベース操作用のクラス関数が用意されています。このクラスは <code>wpdb</code> と呼ばれており、大まかな部分では [http://www.jvmultimedia.com ジャスティン・ヴィンセント]氏が作成し、管理している [http://www.woyano.com/jv/ezsql ezSQL] クラスに基づいています。
+
== データベースと話す: ''wpdb'' クラス ==
  
=== 使い方の注意 ===
+
WordPressには''wpdb''というクラスが定義されています。
 +
このクラスには、データベースとのやりとりに使用される一連の関数が含まれています。
 +
その主な目的は、WordPressデータベースとのインターフェイスを提供することですが、他の適切なデータベースと通信するために使用することもできます。
 +
クラスのコードは [http://www.jvmultimedia.com ジャスティン・ヴィンセント氏] が作成し、管理している [http://justinvincent.com/ezsql ezSQL] クラスに概ね基づいています。
  
<code>wpdb</code> クラスのメソッドは、直接呼び出すべきではありません。WordPress にはデータベースと対話するために設定されたクラスをインスタンス化した <code>$wpdb</code> というグローバル変数があります。常に、このグローバル変数 <code>$wpdb</code> を使うようにしましょう (<code>$wpdb</code> をカスタム関数の中で使う前に、[http://www.php.net/manual/ja/language.variables.scope.php#language.variables.scope.global グローバル宣言]を忘れないようにしましょう)。
 
  
<code>$wpdb</code> オブジェクトは WordPress データベースにあるすべてのテーブルからデータを読み出すために利用できます。これには、WordPress が標準で作成する以外のテーブルも含まれます。例えば、"mytable" というカスタムテーブルから情報を SELECT するには、以下のようにします。
+
=== ''$wpdb'' オブジェクトを使う ===
<code>
+
$myrows = $wpdb->[[#SELECT_Generic_Results|get_results]]( "SELECT id, name FROM mytable" );
+
</code>
+
  
<code>$wpdb</code> オブジェクトは好きな数のテーブルを操作できますが、接続できるのは1つのデータベースだけです (WordPress 用のデータベース)。もし他のデータベースに接続したいという珍しいケースの場合は、適切な接続情報を使って <code>wpdb</code> クラスから独自のオブジェクトをインスタンス化する必要があります。複数のデータベースを使った非常に複雑な構成の場合は、[http://wordpress.org/extend/plugins/hyperdb/ hyperdb] の利用を検討してみてください。
+
'''注意!: <code>wpdb</code> クラスのメソッドを直接呼び出すことはできません。代わりにグローバルの<code>$wpdb</code> オブジェクトを使用してください!'''
  
== データベースへ任意のクエリを送信 ==
+
WordPressはグローバルオブジェクト変数 <code>$wpdb</code> を提供しています。
 +
これは[https://core.trac.wordpress.org/browser/trunk/src/wp-includes/wp-db.php /wp-includes/wp-db.php]に定義されている''wpdb''クラスのインスタンスです。
 +
<code>$wpdb</code> はWordPressデータベースとやりとりするためにあらかじめインスタンス化されています。
 +
WordPressのPHPコードで <code>$wpdb</code> にアクセスするには、globalキーワードを使用して$wpdbを[http://jp2.php.net/manual/ja/language.variables.scope.php#language.variables.scope.global グローバル変数]として宣言するか、以下のようにして[http://jp2.php.net/manual/ja/language.variables.superglobals.php スーパーグローバル $GLOBALS]を使用します。
  
<code>query</code> 関数を使えば、WordPress データベースで'''あらゆる''' SQL クエリを実行できます。ただし、SELECT クエリにはより明確な関数 (下記参照) を使うのが一番良いでしょう。
+
<pre>
 +
// 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 );
 +
</pre>
  
<code><?php $wpdb->query('query'); ?></code>
+
<code>$wpdb</code> オブジェクトは WordPress データベースにあるすべてのテーブルからデータを読み出すために利用できます。これには、WordPress が標準で作成する以外のテーブルも含まれます。例えば、"mytable" というカスタムテーブルから情報を SELECT するには、以下のようにします。
  
; query : (文字列) 実行したい SQL クエリ。
+
<pre>
 +
$myrows = $wpdb->[[#SELECT_Generic_Results|get_results]]( "SELECT id, name FROM mytable" );
 +
</pre>
 +
<code>$wpdb</code> オブジェクトは好きな数のテーブルを操作できますが、接続できるのは1つのデータベースだけです (WordPress 用のデータベース)。もし他のデータベースに接続したいという珍しいケースの場合は、適切な接続情報を使って <code>wpdb</code> クラスから独自のオブジェクトをインスタンス化する必要があります。複数のデータベースを使った非常に複雑な構成の場合は、[http://wordpress.org/extend/plugins/hyperdb/ hyperdb] の利用を検討してみてください。
  
この関数は影響する行または選択された行の数に対応する整数を返します。もし MySQL エラーが発生した場合は、<code>FALSE</code> を返します ('''注''': 0 または FALSE が返される可能性があるため、正しい比較演算子を使うように心がけてください。例えば、等価演算子 <code>==</code> や 厳密な等価演算子 <code>===</code>)。
+
=== 警告<span id="A_Warning"></span> ===
  
注: このクラスの SQL クエリを実行するすべての関数と同様、入力値は SQL エスケープする必要があります (例: <code>wpdb->escape($user_entered_data_string)</code>)。詳しくは以下の "[#Protect_Queries_Against_SQL_Injection_Attacks SQL インジェクション攻撃からクエリを保護する]" セクションを読んでください。
+
'''このクラスの関数の中には、SQL文を入力として受け取るものがあります。 SQLインジェクション攻撃を防ぐために、SQLクエリーに組み込むすべての信頼できない値をエスケープする必要があります。使おうとしている機能がSQLをエスケープしているか、あるいはすでにエスケープされているかどうかを、ドキュメントで確認してください。'''
  
=== 例 ===
+
WordPressでのSQLエスケープの詳細については、下記の[[#Protect_Queries_Against_SQL_Injection_Attacks|SQL インジェクション攻撃からクエリを保護する]]を参照してください。
ID が13の投稿から 'gargle' メタキーおよび値を削除する。
+
<pre>
+
$wpdb->query("
+
DELETE FROM $wpdb->postmeta WHERE post_id = '13'
+
AND meta_key = 'gargle'");
+
</pre>
+
''WordPress の <code>[[関数リファレンス/delete post meta|delete_post_meta()]]</code> 内で実行されます。''
+
 
+
ID が15の[[Pages|固定ページ]]の親ページを、ID が7のページに指定する。
+
<pre>
+
$wpdb->query("
+
UPDATE $wpdb->posts SET post_parent = 7
+
WHERE ID = 15 AND post_status = 'static'");
+
</pre>
+
  
== 変数の SELECT ==
+
== 変数の SELECT<span id="SELECT_a_Variable"></span> ==
  
 
<code>get_var</code> 関数はデータベースから変数を一つ返します。変数は一つしか返ってきませんが、クエリの結果はすべてキャッシュされ、あとから使うことができます。結果にマッチするものがない場合、<tt>NULL</tt> が返されます。
 
<code>get_var</code> 関数はデータベースから変数を一つ返します。変数は一つしか返ってきませんが、クエリの結果はすべてキャッシュされ、あとから使うことができます。結果にマッチするものがない場合、<tt>NULL</tt> が返されます。
  
<code><?php $wpdb->get_var('query',column_offset,row_offset); ?></code>
+
=== 使い方 ===
 +
 
 +
<?php $wpdb->get_var( $query, $column_offset, $row_offset ); ?>
 +
 
 +
===パラメータ===
 +
 
 
; query : (文字列) 実行したい SQL クエリ。パラメータを <code>null</code> にすると、前回のクエリ結果のキャッシュ中から指定した変数を返す。
 
; query : (文字列) 実行したい SQL クエリ。パラメータを <code>null</code> にすると、前回のクエリ結果のキャッシュ中から指定した変数を返す。
 
; column_offset : (整数) 必要としている列のオフセット (一つ目は '''0''')。初期値は '''0'''。
 
; column_offset : (整数) 必要としている列のオフセット (一つ目は '''0''')。初期値は '''0'''。
 
; row_offset : (整数) 必要としている行のオフセット (一つ目は '''0''')。初期値は '''0'''。
 
; row_offset : (整数) 必要としている行のオフセット (一つ目は '''0''')。初期値は '''0'''。
  
=== ===
+
'''訳注:''' クエリはふつう複数の列(カラム)を持つ複数の行を返すので、どの行のどの列の値を変数として返すかを指定します。
ユーザーの数を取得し表示する。
+
 
 +
=== 用例 ===
 +
 
 +
ユーザーの数を取得し、表示する。
 
<pre>
 
<pre>
 
<?php
 
<?php
$user_count = $wpdb->get_var($wpdb->prepare("SELECT COUNT(*) FROM $wpdb->users;"));
+
$user_count = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->users" );
echo '<p>現ユーザー数は、' . $user_count . '人です。</p>';
+
echo "<p>User count is {$user_count}</p>";
 
?>
 
?>
 
</pre>
 
</pre>
  
[[カスタムフィールドの使い方|カスタムフィールドの数値]]合計を返し、表示する。
+
[[カスタムフィールドの使い方|カスタムフィールドの数値]]の合計を取得し、表示する。
 
+
 
<pre>
 
<pre>
 
<?php
 
<?php
$meta_key = 'kilometers'; //実在するメタキーに変更する
+
// meta_key の値を、合計したいカスタムフィールドのメタキーにする
$kms=$wpdb->get_var($wpdb->prepare("SELECT sum(meta_value) FROM $wpdb->postmeta WHERE meta_key = %s", $meta_key));
+
$meta_key = 'miles';
echo '<p>合計距離は'. $kms . 'kmです。</p>';
+
$allmiles = $wpdb->get_var( $wpdb->prepare(  
 +
"
 +
SELECT sum(meta_value)  
 +
FROM $wpdb->postmeta  
 +
WHERE meta_key = %s
 +
",  
 +
$meta_key
 +
) );
 +
echo "<p>合計マイルは {$allmiles}</p>";
 
?>  
 
?>  
 
</pre>
 
</pre>
  
<div ="SELECT_a_Row">
+
== 行の SELECT<span id="SELECT_a_Row"></span> ==
== 行の SELECT ==
+
 
</div>
+
クエリから行全体を取り出すには、<code>get_row</code> を使います。この関数を使うと行がオブジェクト、連想配列、またはインデックス配列として返されます。クエリが2行以上にマッチする場合は、後から使えるようにすべての行がキャッシュされますが、実際に返されるのは指定された行のみです。マッチする行がなければ <code>NULL</code> を返します。そのため、返された値を何かの引数として使う場合は注意してください(以下の例を見てください)。
 +
 
 +
=== 使い方 ===
 +
 
 +
<?php $wpdb->get_row( $query, $output_type, $row_offset ); ?>
  
クエリから行全体を取り出すには、<code>get_row</code> を使います。この関数を使うと行がオブジェクト、連想配列、またはインデックス配列として返されます。クエリが一つ以上の行にマッチする場合は、あとから使えるようにすべての行がキャッシュされますが、実際に返されるのは指定された行のみです。
+
===パラメータ===
  
<code><?php $wpdb->get_row('query', output_type, row_offset); ?></code>
 
 
; query : (文字列) 実行したいクエリ。
 
; query : (文字列) 実行したいクエリ。
 
; output_type : 以下の定数のいずれか。初期値は OBJECT。
 
; output_type : 以下の定数のいずれか。初期値は OBJECT。
84行目: 102行目:
 
; row_offset : (整数) 必要としている行のオフセット (一つ目は '''0''')。初期値は '''0'''。
 
; row_offset : (整数) 必要としている行のオフセット (一つ目は '''0''')。初期値は '''0'''。
  
=== ===
+
=== 用例 ===
リンク ID 10に関する情報をすべて取得する。
+
 
 +
ID が10のリンクに関する情報をすべて取得する。
 +
 
 
<pre>
 
<pre>
 
$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10");
 
$mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10");
 
</pre>
 
</pre>
<code>$mylink</code> オブジェクトの属性は、SQL クエリ結果のカラム名になります (この例の場合、<code>$wpdb->links</code> テーブル内のすべてのカラム)。
+
 
 +
<code>$mylink</code> オブジェクトのプロパティは SQL クエリ結果のカラム名になります (この例の場合、<code>$wpdb->links</code> テーブル内のすべてのカラム)。
 +
 
 
  echo $mylink->link_id; // "10" をプリント
 
  echo $mylink->link_id; // "10" をプリント
  
 
一方、
 
一方、
 +
 
  $mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_A);
 
  $mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_A);
 +
 
を使うと、結果は以下の連想配列になります。
 
を使うと、結果は以下の連想配列になります。
 +
 
  echo $mylink['link_id']; // "10" をプリント
 
  echo $mylink['link_id']; // "10" をプリント
  
 
また、
 
また、
 +
 
  $mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_N);
 
  $mylink = $wpdb->get_row("SELECT * FROM $wpdb->links WHERE link_id = 10", ARRAY_N);
 +
 
を使うと、結果はインデックス配列になります。
 
を使うと、結果はインデックス配列になります。
 +
 
  echo $mylink[1]; // "10" をプリント
 
  echo $mylink[1]; // "10" をプリント
  
== 列の SELECT ==
+
ID が10の行が links テーブルに無ければ <code>null</code> が返されます。そのため次の例は false になります:
  
列を SELECT するには、<code>get_col</code> を使います。この関数は. 多次元配列を出力します。クエリによって複数の列が返された場合、列は一つしか返ってきませんが、クエリの結果はすべてキャッシュされ、あとから使うことができます。
+
<pre>
 +
if ($mylink != null) {
 +
  // リンクについて何かする
 +
  return true;
 +
} else {
 +
  // リンクが見つからなかった
 +
  return false;
 +
}
 +
</pre>
  
<code><?php $wpdb->get_col('query',column_offset); ?></code>
+
== 列の SELECT<span id="SELECT_a_Column"></span> ==
; query : (文字列) 実行したい SQL クエリ。パラメータを <code>null</code> にすると、前回のクエリ結果のキャッシュ中から指定した行を返す。
+
 
 +
列を SELECT するには、<code>get_col</code> を使います。この関数は一次元配列を出力します。クエリが複数の列を返した場合、指定された列だけが返ってきますが、後から使えるようにクエリの結果はすべてキャッシュされます。マッチする結果がなければ <code>NULL</code> を返します。そのため、返された値を何かの引数として使う場合は注意してください(以下の例を見てください)。
 +
 
 +
=== 使い方 ===
 +
 
 +
<?php $wpdb->get_col( $query, $column_offset ); ?>
 +
 
 +
===パラメータ===
 +
 
 +
; query : (文字列) 実行したい SQL クエリ。<code>null</code> を指定すると前回のクエリ結果のキャッシュから指定した列を返す。
 
; column_offset : (整数) 必要としている列のオフセット (一つ目は '''0''')。初期値は '''0'''。
 
; column_offset : (整数) 必要としている列のオフセット (一つ目は '''0''')。初期値は '''0'''。
  
=== ===
+
=== 用例 ===
 +
 
 
車に関するブログがあるとします。ブログの投稿はそれぞれ、ある車 (例: 1969年製のフォードマスタング) について書かれており、その車のモデル・製造年・メーカーという3つの[[カスタムフィールドの使い方|カスタムフィールド]]が設定されています。以下の例では、メーカー名 (フォード) によってフィルターされた投稿のタイトルを、モデルと製造年でソートして出力する場合のコードを紹介しています。
 
車に関するブログがあるとします。ブログの投稿はそれぞれ、ある車 (例: 1969年製のフォードマスタング) について書かれており、その車のモデル・製造年・メーカーという3つの[[カスタムフィールドの使い方|カスタムフィールド]]が設定されています。以下の例では、メーカー名 (フォード) によってフィルターされた投稿のタイトルを、モデルと製造年でソートして出力する場合のコードを紹介しています。
  
[[wpdb Class]] の '''get_col''' を使って、条件に合うすべての投稿の ID の配列を正しい順に並べて取得します。それから ''foreach'' を使って投稿 ID の配列を反復し、各投稿のタイトルを表示します。この例は [http://stackoverflow.com/questions/1690762/complicated-mysql-query/1690808#1690808 Andomar] が作成しました。
+
<tt>wpdb クラス</tt>の '''get_col''' を使って、条件に合うすべての投稿の ID の配列を正しい順に並べて取得します。それから ''foreach'' を使って投稿 ID の配列を反復し、各投稿のタイトルを表示します。この例は [http://stackoverflow.com/questions/1690762/complicated-mysql-query/1690808#1690808 Andomar] が作成しました。
  
 
<pre>
 
<pre>
 
<?php  
 
<?php  
$meta_key1 = 'モデル';
+
$meta_key1 = 'モデル';
$meta_key2 = '製造年';
+
$meta_key2 = '製造年';
$meta_key3 = 'メーカー';
+
$meta_key3 = 'メーカー';
$meta_key3_value = 'フォード';
+
$meta_key3_value = 'フォード';
  
$postids=$wpdb->get_col($wpdb->prepare("
+
$postids=$wpdb->get_col( $wpdb->prepare(  
SELECT      key3.post_id
+
"
FROM        $wpdb->postmeta key3
+
SELECT      key3.post_id
INNER JOIN  $wpdb->postmeta key1  
+
FROM        $wpdb->postmeta key3
            on key1.post_id = key3.post_id
+
INNER JOIN  $wpdb->postmeta key1  
            and key1.meta_key = %s  
+
            ON key1.post_id = key3.post_id
INNER JOIN  $wpdb->postmeta key2
+
            AND key1.meta_key = %s  
            on key2.post_id = key3.post_id
+
INNER JOIN  $wpdb->postmeta key2
            and key2.meta_key = %s
+
            ON key2.post_id = key3.post_id
WHERE      key3.meta_key = %s  
+
            AND key2.meta_key = %s
            and key3.meta_value = %s
+
WHERE      key3.meta_key = %s  
ORDER BY    key1.meta_value, key2.meta_value",$meta_key1, $meta_key2, $meta_key3, $meta_key3_value));  
+
            AND key3.meta_value = %s
 +
ORDER BY    key1.meta_value, key2.meta_value
 +
",
 +
$meta_key1,  
 +
$meta_key2,  
 +
$meta_key3,  
 +
$meta_key3_value
 +
) );  
  
if ($postids) {
+
if ( $postids )  
  echo $meta_key3_value . '一覧 (' . $meta_key1 . '' . $meta_key2 .'順)';
+
{
  foreach ($postids as $id) {  
+
echo "List of {$meta_key3_value}(s), sorted by {$meta_key1}, {$meta_key2}";
    $post=get_post(intval($id));
+
foreach ( $postids as $id )
    setup_postdata($post);?>
+
{
    <p><a href="<?php the_permalink() ?>" rel="bookmark" title="<?php the_title_attribute(); ?>へのパーマリンク"><?php the_title(); ?></a></p>
+
$post = get_post( intval( $id ) );
    <?php
+
setup_postdata( $post );
  }  
+
?>
 +
<p>
 +
<a href="<?php the_permalink() ?>" rel="bookmark" title="<?php the_title_attribute(); ?>へのパーマリンク">
 +
<?php the_title(); ?>
 +
</a>
 +
</p>
 +
<?php
 +
}
 +
}
 +
?>
 +
</pre>
 +
 
 +
次の例は、あるカスタムフィールドを持つ投稿をすべて表示します。そのときもう一つのカスタムフィールドの値で並べ替えます。
 +
 
 +
<pre>
 +
<?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
 +
}
 
}
 
}
 
?>
 
?>
148行目: 251行目:
  
 
<div id="SELECT_Generic_Results">
 
<div id="SELECT_Generic_Results">
== 一般的な結果の SELECT ==
+
 
 +
== 一般的な結果を返す SELECT<span id="SELECT_Generic_Results"></span> ==
 
</div>
 
</div>
  
<code>get_results</code> を使うと、データベースから一般的な複数行の結果を取ってくることができます。この関数はクエリの結果全体を配列として返します。この配列の各要素はクエリ結果の各行と対応しており、<code>get_row</code> と同じくオブジェクト、連想配列、またはインデックス配列のいずれかを指定することができます。
+
<code>get_results</code> を使うと、データベースから一般的な複数行の結果を取得できます。この関数はクエリの結果全体を配列として返します。この配列の各要素はクエリ結果の各行と対応します。配列の型は、<code>get_row</code> と同じくオブジェクト、連想配列、またはインデックス配列のいずれかを指定できます。
 +
1行も見つからないか、データベースエラーが発生した場合は、戻り値が空の配列になります。もし <tt>$query</tt> が空文字列であるか、無効な <tt>$output_type</tt> を指定すると、<tt>NULL</tt> が返されます。
  
<code><?php $wpdb->get_results('query', output_type); ?></code>
+
=== 使い方 ===
; query : (文字列) 実行したい SQL クエリ。パラメータを <code>null</code> にすると、前回のクエリ結果のキャッシュ中からデータを返す。
+
; output_type : 以下の定数のいずれか。初期値は OBJECT。詳細および例については、[[#SELECT_a_Row|行の SELECT]] セクションを参照。
+
:* OBJECT - 結果をオブジェクトとして出力。
+
:* ARRAY_A - 結果を連想配列として出力。
+
:* ARRAY_N - 結果をインデックス配列として出力。
+
  
=== ===
+
<?php $wpdb->get_results( $query, $output_type ); ?>
ID が5のユーザーのすべての下書きの ID とタイトルを取得して、タイトルを echo。
+
 
 +
===パラメータ===
 +
 
 +
; query : (文字列) 実行したい SQL クエリ。
 +
; output_type : 以下の4つの定数のいずれか。初期値は OBJECT。詳細および例については、[[#SELECT_a_Row|行の SELECT]] セクションを参照。
 +
 
 +
:* OBJECT -  結果をインデックス配列として出力。要素は行オブジェクト。
 +
:* OBJECT_K - 結果を連想配列として出力。第1カラムの値をキー(重複は無視される)、行オブジェクトを値とする。
 +
:* ARRAY_A - 結果をインデックス配列として出力。要素は1行を表す連想配列で、そのキーはカラム名。
 +
:* ARRAY_N - 結果をインデックス配列として出力。要素は1行を表すインデックス配列。
 +
 
 +
この関数は内部で <tt>$wpdb->query()</tt> を使うので、クラス変数は適切にセットされます。<tt>'SELECT'</tt> クエリの結果(行カウント)は <tt>$wpdb->num_rows</tt> へ入ります。
 +
 
 +
=== 用例 ===
 +
 
 +
ID が5のユーザーのすべての下書きの ID とタイトルを取得して、タイトルを echo。
  
 
<pre>
 
<pre>
$fivesdrafts = $wpdb->get_results("SELECT ID, post_title FROM $wpdb->posts
+
$fivesdrafts = $wpdb->get_results(  
WHERE post_status = 'draft' AND post_author = 5");
+
"
 +
SELECT ID, post_title  
 +
FROM $wpdb->posts
 +
WHERE post_status = 'draft'  
 +
AND post_author = 5
 +
"
 +
);
  
foreach ($fivesdrafts as $fivesdraft) {
+
foreach ( $fivesdrafts as $fivesdraft )  
 +
{
 
echo $fivesdraft->post_title;
 
echo $fivesdraft->post_title;
 
}
 
}
 
</pre>
 
</pre>
  
ID が5のユーザーの下書き情報をすべて取得。
+
ID が5のユーザーの下書き情報をすべて取得。
 
<pre>
 
<pre>
 
<?php
 
<?php
$fivesdrafts = $wpdb->get_results("SELECT * FROM $wpdb->posts
+
$fivesdrafts = $wpdb->get_results(  
WHERE post_status = 'draft' AND post_author = 5");
+
"
if ($fivesdrafts) :
+
SELECT *  
foreach ($fivesdrafts as $post) :
+
FROM $wpdb->posts
setup_postdata($post);
+
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
 +
}
 
?>
 
?>
<h2><a href="<?php the_permalink(); ?>" rel="bookmark"
 
title="<?php the_title(); ?>へのパーマリンク"><?php the_title(); ?></a></h2>
 
<?php
 
endforeach;
 
else :
 
?>
 
    <h2>見つかりません</h2>
 
<?php endif; ?>
 
 
</pre>
 
</pre>
  
== 行の INSERT ==
+
== 行の INSERT<span id="INSERT_row"></span> ==
 +
 
 +
テーブルへ行を挿入します。
 +
 
 +
=== 使い方 ===
 +
 
 +
<?php $wpdb->insert( $table, $data, $format ); ?>
 +
 
 +
===パラメータ===
 +
 
 +
; table : (文字列) データを挿入するテーブル名。
 +
; data : (配列) 挿入するデータ。キーをカラム名、値を挿入する値とする。<tt>$data</tt> のカラム名と <tt>$data</tt> の値は両方とも "raw" であること(どちらも SQL エスケープしてはいけない)。
 +
; format : (配列|文字列) (オプション) <tt>$data</tt> の値それぞれに適用する書式の配列。文字列の場合、それが <tt>$data</tt> のすべての値に適用される。省略すると、<tt>$data</tt> のすべての値が文字列として扱われるが、<tt>wpdb::$field_types</tt>による指定があればそちらが優先される。
 +
 
 +
: 使用可能な書式の値(詳しくは後の [[#Placeholders | プレースホルダー]] を参照):
 +
:* <tt>%s</tt> - 文字列
 +
:* <tt>%d</tt> - 整数 (すべて数字)
 +
:* <tt>%f</tt> - 浮動小数点数
 +
 
 +
挿入した後、カラム <tt>AUTO_INCREMENT</tt> へ生成された ID は次の方法でアクセスできます:
 +
<pre>$wpdb->insert_id</pre>
 +
 
 +
この関数は、行を挿入できなければ <tt>false</tt> を返します。挿入できたときは影響を受けた行数を返します(いつでも1です)。
  
テーブルに行を挿入。
+
'''注意''': <tt>data</tt> パラメータの <tt>カラム名=>値</tt> ペアにおける値はスカラーに限ります。値として配列(またはオブジェクト)を渡すと警告が発生します。この警告は例えば次のようなものです: <code>"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"</code>
  
=== ===
+
=== 用例 ===
  
列に2つ (1つ目は文字列、2つ目は数値) 行を挿入。
+
列を2つ(1つ目は文字列、2つ目は数値)持つ行を挿入します。
  
 
<pre>
 
<pre>
$wpdb->insert( 'table', array( 'column1' => 'value1', 'column2' => 123 ), array( '%s', '%d' ) )
+
$wpdb->insert(  
 +
'table',  
 +
array(  
 +
'column1' => 'value1',  
 +
'column2' => 123  
 +
),  
 +
array(  
 +
'%s',  
 +
'%d'  
 +
)  
 +
);
 
</pre>
 
</pre>
 
<strong>使用できる値</strong>:
 
- %s (文字列)
 
- %d (十進記数法)
 
- %f (浮動小数点数)
 
  
 
<!-- Please complete this list, it could be easier to use this function for newbies -->
 
<!-- Please complete this list, it could be easier to use this function for newbies -->
  
== 列の UPDATE ==
+
== 行の REPLACE<span id="REPLACE_row"></span> ==
  
テーブル内の列を更新。
+
指定した行がテーブルにあれば置き換えます。なければ新しい行としてテーブルへ挿入します。
  
=== 例 ===
+
'''訳注: テーブルにプライマリーキーか、UNIQUE インデックスを用意しておかなければ REPLACE は利用できません。指定した行がすでに存在するかどうかを、キーまたは UNIQUE インデックスで調べるためです。'''
  
ID が1、一つ目の列の値が文字列、2つ目の列の値が数値、という行を更新する。
+
=== 使い方 ===
 +
 
 +
<?php $wpdb->replace( $table, $data, $format ); ?>
 +
 
 +
===パラメータ===
 +
 
 +
; table : (文字列) 置き換えたいデータがあるテーブルの名前。
 +
; data : (配列) 置き換え後のデータ(<code>列の名前 => 値</code> のペア)。<tt>$data</tt> の列の名前と値はどちらも "raw" にすること(どちらも SQL エスケープしてはいけない)。
 +
; format : (配列|文字列) (オプション) <tt>$data</tt> 内の値それぞれに適用する書式の配列。文字列の場合、それを書式として <tt>$data</tt> 内のすべての値へ適用する。省略すると <tt>$data</tt> 内のすべての値を文字列として扱うが、<tt>wpdb::$field_types</tt> に指定があればそちらを優先する。
 +
 
 +
: 使える書式の値は:
 +
:* <tt>%s</tt> - 文字列
 +
:* <tt>%d</tt> - 整数(全部が数字)
 +
:* <tt>%f</tt> - 浮動小数点数。(詳しくは [[#Placeholders | プレースホルダー]] を参照。)
 +
 
 +
もし <tt>$data</tt> 配列パラメータの要素数が MySql データベーステーブルに定義された列の数より多ければ、挿入は失敗して、この関数は <tt>false</tt> を返します。しかし <code>$wpdb->last_error</code> に失敗を説明するメッセージは入りません。挿入したいデータがデータベースへぴったり入るように自分で気をつけてください。MySQL がデータを切り捨ててくれると想定しないでください。
 +
 
 +
置き換えた後、<tt>AUTO_INCREMENT</tt> 列へ入れられた ID は次の方法でアクセスできます:
 +
<pre>$wpdb->insert_id</pre>
 +
 
 +
この関数は影響を受けた行のカウントを返します。これは削除された行と挿入された行の合計数です。カウントが1なら単一行の REPLACE が行われた結果、1行が挿入され、どの行も削除されていません。カウントが1より大きければ、1行以上が削除され、かつ新しい行が挿入されています。
 +
なお、複数の古い行を1行で置き換える場合があります。それはテーブルが複数のユニークインデックスを持ち、新しい行が別々のユニークインデックスにより異なる行に対応づけられる場合です。
 +
 
 +
この関数は、既存の行を置き換えることができず、かつ新しい行を挿入することもできない場合、<tt>false</tt> を返します。
 +
 
 +
=== 用例 ===
 +
 
 +
ある行を置き換えます。第1の値が行の id で、2番目は文字列、3番目は数字です:
  
 
<pre>
 
<pre>
$wpdb->update( 'table', array( 'column1' => 'value1', 'column2' => 'value2' ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
+
$wpdb->replace(  
 +
'table',  
 +
array(  
 +
'indexed_id' => 1,
 +
'column1' => 'value1',  
 +
'column2' => 123
 +
),  
 +
array(  
 +
'%d',
 +
'%s',  
 +
'%d'  
 +
)  
 +
);
 
</pre>
 
</pre>
  
<div id=Protect_Queries_Against_SQL_Injection_Attacks">
+
== 行の UPDATE<span id="UPDATE_rows"></span> ==
== SQL インジェクション攻撃からクエリを保護する ==
+
</div>
+
  
WordPress での SQL エスケープについてのより詳しい概要は、[[データ検証#.E3.83.87.E3.83.BC.E3.82.BF.E3.83.99.E3.83.BC.E3.82.B9|データベースのデータ検証]]ページをご覧ください。これはコア貢献者やプラグイン作者が '''必ず読むべき''' ページです。
+
テーブル内の行を更新します。エラーが生じると <tt>false</tt> を、成功すると影響を受けた行の数を返します。
  
簡単にいうと、SQL インジェクション攻撃からクエリを保護するためには、実行する前にクエリデータはすべて SQL エスケープする必要があります。これを行う際には、[http://php.net/manual/ja/function.sprintf.php sprintf()] に似た構文を持つ<code>prepare</code> メソッドを使うと便利です。
+
=== 使い方 ===
 +
 
 +
<?php $wpdb->update( $table, $data, $where, $format = null, $where_format = null ); ?>
 +
 
 +
===パラメータ===
 +
 
 +
; table : (文字列) 更新対象のテーブル名。
 +
; data : (配列) 更新するデータ(<tt>列名 => 値</tt> ペア形式)。<tt>$data</tt> の列名と値は "raw" でなければならない(どちらも SQL エスケープしてはいけない)。例えば <tt>GET</tt> や <tt>POST</tt> のデータを使う場合、スラッシュがデータベースへ挿入されないように <tt>stripslashes()</tt> を使う必要があるかもしれません。
 +
; where : (配列) <tt>WHERE</tt> 句として使う名前付き配列(<tt>列名 => 値</tt> ペア形式)。2つ以上の句は <tt>AND</tt> で結合される。<tt>$where</tt> の列名と値は "raw" でなければならない。
 +
; format : (配列|文字列) (オプション) <tt>$data</tt> の値それぞれに適用する書式の配列。文字列を指定すると、<tt>$data</tt> の値すべてに書式として適用される。
 +
; where_format : (配列|文字列) (オプション) <tt>$where</tt> の値それぞれに適用する書式の配列。文字列を指定すると、<tt>$where</tt> の値すべてに書式として適用される。
 +
 
 +
: <strong>書式に指定できる値</strong>: ([[#Placeholders | 後の注記]] も見てください。)
 +
:* <tt>%s</tt> - 文字列
 +
:* <tt>%d</tt> - 整数(全部が数字)
 +
:* <tt>%f</tt> - 浮動小数点数。
 +
:* 省略すると <tt>$where</tt> の値はすべて文字列と見なされる。
 +
 
 +
===戻り値===
 +
 
 +
この関数は影響を受けた行の数、またはエラーが発生すると <tt>false</tt> を返します。<tt>$data</tt> がデータベース内の既存データに一致した場合は <tt>0</tt> を返すことに注意してください。そのためエラー判定は <code>false === $result</code> が良いでしょう。
 +
 
 +
=== 用例 ===
 +
 
 +
ID が1である行を更新します。第1列の値は文字列、第2列の値は数値とします:
 +
 
 +
<pre>
 +
$wpdb->update(
 +
'table',
 +
array(
 +
'column1' => 'value1', // string
 +
'column2' => 'value2' // integer (number)
 +
),
 +
array( 'ID' => 1 ),
 +
array(
 +
'%s', // value1
 +
'%d' // value2
 +
),
 +
array( '%d' )
 +
);
 +
</pre>
 +
 
 +
<strong>注意:</strong> <code>%d</code> はコンマ入りの値を扱えません。数字だけではない数値を扱うには、文字列(<code>%s</code>)を使ってください。
 +
 
 +
== 行の DELETE<span id="DELETE_Rows"></span> ==
 +
 
 +
<tt>delete</tt> 関数は WordPress [[Version_3.4|3.4.0]] で追加されました。テーブルから行を削除するのに使います。使い方は <tt>[[#UPDATE_rows | update]]</tt> と <tt>[[#INSERT_row | insert]]</tt> にとてもよく似ています。削除された行の数を返しますが、エラーが発生すると <tt>false</tt> を返します。
 +
 
 +
===使い方===
 +
 
 +
<?php $wpdb->delete( $table, $where, $where_format = null ); ?>
 +
 
 +
===パラメータ===
 +
 
 +
{{Parameter|$table|文字列|テーブル名}}
 +
{{Parameter|$where|array|<tt>WHERE</tt> 句に使う連想配列(列の名前->値)。複数の句を指定すると <tt>AND</tt> で結合される。<tt>$where</tt> の列の名前と値は両方とも 'raw' でなければならない。}}
 +
{{Parameter|$where_format|文字列/配列|<tt>$where</tt> の要素それぞれに適用する書式の配列。文字列を指定すると、それを書式として<tt>$where</tt> のすべての要素へ適用する。書式は <tt>'%d'</tt>, <tt>'%f'</tt>, <tt>'%s'</tt> (整数, 浮動小数点数, 文字列; 詳しくは [[#Placeholders | プレースホルダー]] を参照)。省略すると <tt>$where</tt> の値はすべて文字列として扱われる(<tt>wpdb::$field_types</tt> に指定がある場合はそちらが優先)。|オプション|<tt>null</tt>}}
 +
 
 +
===用例===
 +
<pre>
 +
// デフォルトの使い方。
 +
$wpdb->delete( 'table', array( 'ID' => 1 ) );
 +
 
 +
// where 句の書式を指定。
 +
$wpdb->delete( 'table', array( 'ID' => 1 ), array( '%d' ) );
 +
</pre>
 +
 
 +
== 任意のクエリの実行<span id="Running_General_Queries"></span> ==
 +
 
 +
<code>query</code> 関数を使うと WordPress データベースに対して任意の SQL クエリを実行できます。特定用途や複雑な SQL クエリが必要なときに最適です。情報を選び出すようなもっと基本的なクエリの場合は、ここまでに説明した他の <code>wpdb</code> 関数を見てください。
 +
 
 +
=== 一般的な構文 ===
 +
 
 +
<?php $wpdb->query( $query ); ?>
 +
 
 +
===パラメータ===
 +
 
 +
; query : (文字列) 実行したい SQL クエリ。
 +
 
 +
この関数は <tt>SELECT, INSERT, DELETE, UPDATE</tt> などの影響を受けた、または選択された行の数を示す整数値を返します。SQL の <tt>CREATE, ALTER, TRUNCATE</tt> および <tt>DROP</tt> の場合(これらは特定の行ではなくテーブル全体へ影響します)、この関数は成功すると <code>TRUE</code> を返します。もし MySQL エラーが発生した場合は <code>FALSE</code> を返します。
 +
 
 +
参考: 行のクエリは <code>0</code> と <code>FALSE</code> のどちらも返す場合があるので、戻り値を調べるときに注意してください。厳密な等価演算子(<code>===</code>)を使って、エラー(<code>false === $result</code>)と、影響を受けた行の有無(<code>0 === $result</code>)を確かめましょう。
 +
 
 +
=== 用例 ===
 +
 
 +
ID が 13 の投稿から投稿メタ 'gargle' のキーと値を削除します。(ここで 'prepare' メソッドを使うのは、不正な操作や不正な文字を処理しないためです):
 +
 
 +
<pre>
 +
$wpdb->query(
 +
$wpdb->prepare(
 +
"
 +
DELETE FROM $wpdb->postmeta
 +
WHERE post_id = %d
 +
AND meta_key = %s
 +
",
 +
13, 'gargle'
 +
)
 +
);
 +
</pre>
 +
 
 +
''WordPress が <code>[[関数リファレンス/delete post meta|delete_post_meta()]]</code> の内部で実行するコード:''
 +
 
 +
 
 +
ID が 7 の[[固定ページ]]へ親として ID が 15 の[[固定ページ]]を設定する。
 +
 
 +
<pre>
 +
$wpdb->query(
 +
"
 +
UPDATE $wpdb->posts
 +
SET post_parent = 7
 +
WHERE ID = 15
 +
AND post_status = 'static'
 +
"
 +
);
 +
</pre>
 +
 
 +
== SQL インジェクション攻撃からクエリを保護する<span id="Protect_Queries_Against_SQL_Injection_Attacks"></span> ==
 +
 
 +
WordPress における SQL エスケープのより詳しい説明は [[データ検証#Database|データベースのデータ検証]] ページを見てください。これはコア貢献者やプラグイン作者が '''必ず読むべき''' ページです。
 +
 
 +
簡単にいうと、SQL インジェクション攻撃からクエリを保護するためには、実行する前にクエリデータをすべて SQL エスケープする必要があります。
 +
WordPress では <code>prepare</code> メソッドがこの機能を提供します。[http://php.net/sprintf sprintf()] 風と [http://php.net/vsprintf vsprintf()] 風の両方の書き方を利用できます。
 +
 
 +
'''注意''': WordPress [[Version 3.5|3.5]]以降、<tt>wpdb::prepare()</tt> は '''引数を2個以上''' 必要とします。[[http://make.wordpress.org/core/2012/12/12/php-warning-missing-argument-2-for-wpdb-prepare/ 詳しくはこちら。]]
 +
 
 +
=== 使い方 ===
 +
 
 +
<?php $sql = $wpdb->prepare( $query, $value_parameter[, $value_parameter ... ] ); ?>
 +
 
 +
=== パラメータ ===
  
<code><?php $sql = $wpdb->prepare( 'query'[, value_parameter, value_parameter ... ] ); ?></code>
 
 
; query : (文字列) 実行したい SQL クエリ。<code>%s</code> および <code>%d</code> がプレースホルダーになる。
 
; query : (文字列) 実行したい SQL クエリ。<code>%s</code> および <code>%d</code> がプレースホルダーになる。
; value_parameter : (整数|文字列) プレースホルダーに代入する値。すでに SQL エスケープされている値は使えない。
+
; value_parameter : (整数|文字列|配列) プレースホルダーへ代入する値。[http://php.net/sprintf sprintf()] 風の書き方でたくさんの値を渡すことができます。別の方法として、PHP の関数 [http://php.net/vsprintf vsprintf()] 風に値を並べた配列を第2引数にすることもできます。
 +
'''注意''': ユーザーが入力したものを直接このパラメータにしてはいけません。もしそうすると、複数のプレースホルダーを含む任意のクエリに対して配列操作を行ってしまいます。値は SQL エスケープしてはいけません。
  
======
+
=== プレースホルダー<span id="Placeholders"></span> ===
ID 10の投稿に、"孔子の教え" => "故きを温めて新しきを知る、以て師と為るべし。" というメタキー => 値のペアを追加する。
+
<tt>prepare</tt> の <tt>query</tt> パラメータは [http://php.net/sprintf sprintf()] 風のプレースホルダーを使えます。書式は <tt>%s</tt> (文字列), <tt>%d</tt> (整数) and <tt>%f</tt> (浮動小数点数) がサポートされています。(<tt>%s</tt> と <tt>%d</tt> はこの関数がコアへ追加された [[Version 2.3|バージョン 2.3]] から、ただし <tt>%f</tt> は [[Version 3.3|バージョン 3.3]] 以降で使えます。)
 +
これらを除く <code>%</code> 文字列はエスケープしなければパースエラーを起こす可能性があります。SQL 文字定数の中で <code>%</code> を使う場合、LIKE のワイルドカードも含めて、
 +
<code>%%</code> のように二重の <code>%</code> を書いてエスケープしなければなりません。<tt>%d</tt>, <tt>%f</tt>, <tt>%s</tt> はどれもクォートで囲まずにクエリ文字列へ書きます。
 +
'''注意''': <tt>%d</tt> プレースホルダーは整数だけを受け付けるので、'''桁区切りのコンマを使った数値を <tt>%d</tt> で渡してはいけません'''。コンマ付きの値が必要なら代わりに <tt>%f</tt> を使ってください。
 +
 
 +
=== 用例 ===
 +
ID が10の投稿へ、投稿メタを追加します。投稿メタは、キー => 値のペア <code>"Harriet's Adages" => "WordPress' database interface is like Sunday Morning: Easy."</code> です。
 
<pre>
 
<pre>
$metakey = "孔子の教え";
+
$metakey = "Harriet's Adages";
$metavalue = "故きを温めて新しきを知る、以て師と為るべし。";
+
$metavalue = "WordPress' database interface is like Sunday Morning: Easy.";
  
$wpdb->query( $wpdb->prepare( "
+
$wpdb->query( $wpdb->prepare(  
INSERT INTO $wpdb->postmeta
+
"
( post_id, meta_key, meta_value )
+
INSERT INTO $wpdb->postmeta
VALUES ( %d, %s, %s )",  
+
( post_id, meta_key, meta_value )
         10, $metakey, $metavalue ) );
+
VALUES ( %d, %s, %s )
 +
",  
 +
         10,  
 +
$metakey,  
 +
$metavalue  
 +
) );
 
</pre>
 
</pre>
''<code>add_meta()</code> によって WordPress 内で実行される。''
+
''同様の処理が WordPress の <code>[[関数リファレンス/add_meta|add_meta()]]</code> /[[:en:Function Reference/add meta|en]] で行われています。''
  
文字列をクオートで囲む必要がない点に注目しましょう。SQL クエリに変数を直接渡すのではなく、文字列には <code>%s</code> プレースホルダーを、整数には <code>%d</code> プレースホルダーを使っています。渡す値の数に制限はありません。それぞれ、<code>prepare()</code> メソッドで新しいパラメーターにします。
+
同じクエリを [http://php.net/vsprintf vsprintf()] 風の構文で書くと次のようになります。
 +
<pre>
 +
$metakey = "Harriet's Adages";
 +
$metavalue = "WordPress' database interface is like Sunday Morning: Easy.";
  
<div id="Showing_and_Hiding_SQL_Errors">
+
$wpdb->query( $wpdb->prepare(
== SQL エラーの表示・非表示 ==
+
"
</div>
+
INSERT INTO $wpdb->postmeta
 +
( post_id, meta_key, meta_value )
 +
VALUES ( %d, %s, %s )
 +
",
 +
        array(
 +
10,
 +
$metakey,
 +
$metavalue
 +
)
 +
) );
 +
</pre>
 +
''この例では値を配列にまとめています。この方法は、実行するときまで引数の個数がわからない場合に有用です。''
 +
 
 +
文字列をクォートで囲む必要がない点に注目しましょう。SQL クエリに変数を直接入れて渡すのではなく、プレースホルダーとして文字列には <code>%s</code>、整数には <code>%d</code>、浮動小数点数には <tt>%f</tt> を使ってください。渡す値の個数に制限はなく、1つずつ <code>prepare()</code> メソッドの新しいパラメーターにします。
 +
 
 +
== SQL エラーの表示・非表示<span id="Showing_and_Hiding_SQL_Errors"></span> ==
  
 
<code>show_errors</code> と <code>hide_errors</code> を使い、エラーの出力を有効化・無効化できます。
 
<code>show_errors</code> と <code>hide_errors</code> を使い、エラーの出力を有効化・無効化できます。
  
<code><?php $wpdb->show_errors(); ?>
+
<?php $wpdb->show_errors(); ?>
<?php $wpdb->hide_errors(); ?></code>
+
<?php $wpdb->hide_errors(); ?>
  
 
最後に実行されたクエリにエラーがある場合、<code>print_error</code> でそのエラーを表示できます。
 
最後に実行されたクエリにエラーがある場合、<code>print_error</code> でそのエラーを表示できます。
  
<code><?php $wpdb->print_error(); ?></code>
+
<?php $wpdb->print_error(); ?>
 +
 
 +
<strong>参考:</strong> マルチサイトの WordPress の場合、データベースを表示するには定数 <tt>DIEONDBERROR</tt> を次のように定義しなければなりません:<br />
 +
<?php define( 'DIEONDBERROR', true ); ?>
 +
 
 +
== 列情報の取得<span id="Getting_Column_Information"></span> ==
  
<div id="Getting_Column_Information">
 
== 列情報の取得 ==
 
</div>
 
 
<code>get_col_info</code> を使えば、最後に実行したクエリ結果の列に関する情報を取得できます。これは、関数が属性が分からない OBJECT を返してきた際に便利です。この関数は指定した列から取得したい情報を出力します。列が指定されていない場合は、クエリ結果に含まれるすべての列の情報を含む配列を出力します。
 
<code>get_col_info</code> を使えば、最後に実行したクエリ結果の列に関する情報を取得できます。これは、関数が属性が分からない OBJECT を返してきた際に便利です。この関数は指定した列から取得したい情報を出力します。列が指定されていない場合は、クエリ結果に含まれるすべての列の情報を含む配列を出力します。
  
<code><?php $wpdb->get_col_info('type', offset); ?></code>
+
=== 使い方 ===
; type : (文字列) 取得したい情報。以下の値から選べる ([http://justinvincent.com/home/docs/ezsql/ez_sql_help.htm ezSQL のドキュメンテーション]から転載)。初期値は '''name'''。
+
 
 +
<?php $wpdb->get_col_info( $type, $offset ); ?>
 +
 
 +
=== パラメータ ===
 +
 
 +
; type : (文字列) 取得したい情報。以下の値から選べる ([https://github.com/ezSQL/ezSQL/blob/master/ez_sql_help.htm ezSQL のドキュメンテーション]から転載)。初期値は '''name'''。
 
:*name - カラム名 (初期値)。
 
:*name - カラム名 (初期値)。
 
:*table - 列が含まれるテーブル名。
 
:*table - 列が含まれるテーブル名。
283行目: 650行目:
 
:*zerofill - 列が zero-filled の場合は1。
 
:*zerofill - 列が zero-filled の場合は1。
 
; offset : (整数) 情報を取得するカラムを指定する ('''0''' が最初のカラム)。初期値は '''-1'''。
 
; offset : (整数) 情報を取得するカラムを指定する ('''0''' が最初のカラム)。初期値は '''-1'''。
:*-1 - すべてのカラムの情報を取得し、配列として出力する。初期値。
+
:* -1 - すべてのカラムの情報を取得し、配列として出力する。初期値。
:*Non-negative integer - 指定した列の情報を取得する ('''0''' が最初)。
+
:* 0または正の整数 - 指定した列の情報を取得する ('''0''' が最初)。
  
== キャッシュのクリア ==
+
== キャッシュの消去<span id="Clearing the Cache"></span> ==
  
 
SQL の結果のキャッシュは、<code>flush</code> でクリアできます。
 
SQL の結果のキャッシュは、<code>flush</code> でクリアできます。
  
<code><?php $wpdb->flush(); ?></code>
+
<?php $wpdb->flush(); ?>
  
 
これにより、<code>$wpdb->last_result</code>、<code>$wpdb->last_query</code>、<code>$wpdb->col_info</code> がリセットされます。
 
これにより、<code>$wpdb->last_result</code>、<code>$wpdb->last_query</code>、<code>$wpdb->col_info</code> がリセットされます。
  
== クラス変数 ==
+
== クラス変数<span id="Class Variables"></span> ==
; $show_errors : [[#Showing and Hiding SQL Errors|エラーの echo]] が有効化されているかどうか。デフォルトは TRUE 。
+
 
 +
; $show_errors : [[#Showing and Hiding SQL Errors|エラーの表示]] が有効化されているかどうか。デフォルトは TRUE 。
 
; $num_queries : 実行されたクエリの数。
 
; $num_queries : 実行されたクエリの数。
 
; $last_query : 最後に実行されたクエリ。
 
; $last_query : 最後に実行されたクエリ。
; $queries : SAVEQUERIES 定数を TRUE に設定することで (定数の初期値は FALSE)、データベースで実行するクエリおよに停止時間を保存できる。SAVEQUERIES が TRUE の場合、クエリはこの変数に配列として保存される。
+
; $last_error : MySQL で生成された最新のエラー文字列。
 +
; $queries : 定数 <tt>SAVEQUERIES</tt> を <tt>TRUE</tt> にすると(デフォルトは <tt>FALSE</tt>)、データベースで実行したクエリと終了時刻を保存できます。<tt>SAVEQUERIES</tt> <tt>TRUE</tt> のとき、クエリが配列としてこの変数へ保存されます。
 
; $last_result : 最後に実行されたクエリの結果。
 
; $last_result : 最後に実行されたクエリの結果。
 
; $col_info : 最後に実行されたクエリの列情報。[[#Getting_Column_Information|列情報の取得]]セクションを参照。
 
; $col_info : 最後に実行されたクエリの列情報。[[#Getting_Column_Information|列情報の取得]]セクションを参照。
 
; $insert_id : 最後に実行された INSERT クエリで、AUTO_INCREMENT によって生成された ID。
 
; $insert_id : 最後に実行された INSERT クエリで、AUTO_INCREMENT によって生成された ID。
 
; $num_rows : 最後に実行されたクエリで返された行の数。
 
; $num_rows : 最後に実行されたクエリで返された行の数。
 +
; $prefix : このサイトの WordPress テーブルに与えられたプリフィックス。
 +
 +
=== マルチサイト変数 ===
 +
 +
マルチサイトを使用する場合、以下にアクセスする場合があります:
 +
 +
; $blogid :  現在のサイト(ブログ)の ID。
 +
; $siteid :  現在のネットワーク(正式には "サイト")の ID。現在の WordPress は一つのマルチサイト型インストールに一つのネットワークだけをサポートします。将来は変わるかもしれませんが。
 +
 +
詳しくは以下をご覧ください:
 +
 +
* [http://wordpress.org/support/topic/wordpress-difference-between-site_id-and-blog_id?replies=11 WordPress: difference between site_id and blog_id?]
 +
* http://stackoverflow.com/a/4189358/1924128 - Another good answer to the same question.
 +
 +
== テーブル<span id="Tables"></span> ==
  
== テーブル ==
 
 
<!-- will likely not be useful when the database structure is fully described -->
 
<!-- will likely not be useful when the database structure is fully described -->
 
<code>wpdb</code> を使って簡単に WordPress データベーステーブルを参照できます。
 
<code>wpdb</code> を使って簡単に WordPress データベーステーブルを参照できます。
 
; $posts : [[データベース概要#Table:_wp_posts|posts]] (投稿・固定ページ) テーブル。
 
; $posts : [[データベース概要#Table:_wp_posts|posts]] (投稿・固定ページ) テーブル。
; $users : The table of [[データベース概要#Table:_wp_users|users]] (ユーザー) テーブル。
+
; $postmeta : [[データベース概要#Table:_wp_postmeta|postmeta]] (メタコンテンツ、[[カスタムフィールドの使い方|カスタムフィールド]]) テーブル。
; $comments : The [[データベース概要#Table:_wp_comments|comments]] (コメント) テーブル。
+
 
; $links : The table of [[データベース概要#Table:_wp_links|links]] (リンク情報) テーブル。
+
; $comments : [[データベース概要#Table:_wp_comments|comments]] (コメント) テーブル。
; $options : The [[データベース概要#Table:_wp_options|options]] (設定情報) テーブル。
+
; $commentmeta : 追加のコメント情報を含むテーブル。
; $postmeta : The [[データベース概要#Table:_wp_postmeta|postmeta]] (= メタコンテンツ、[[カスタムフィールドの使い方|カスタムフィールド]]) テーブル。
+
 
; $usermeta : The [[データベース概要#Table:_wp_usermeta|usermeta]] (ユーザーメタ情報) テーブル。ニックネーム、説明、パーミッションなどユーザーに関する追加情報を含む。
+
; $termmeta : タームのメタ情報を含むテーブル。
 
; $terms : [[データベース概要#Table:_wp_terms|terms]] (キーワード情報) テーブル。カテゴリーの説明、リンクカテゴリー、タグなどの情報を含む。
 
; $terms : [[データベース概要#Table:_wp_terms|terms]] (キーワード情報) テーブル。カテゴリーの説明、リンクカテゴリー、タグなどの情報を含む。
; $term_taxonomy : The [[データベース概要#Table:_wp_term_taxonomy|term_taxonomy]] テーブル。キーワード (terms) のクラスであるタクソノミーの情報を含む。タクソノミーとは、投稿カテゴリー、リンクカテゴリー、タグ、その他のカスタムタクソノミーを指す。
+
; $term_taxonomy : [[データベース概要#Table:_wp_term_taxonomy|term_taxonomy]] テーブル。キーワード (terms) のクラスであるタクソノミーの情報を含む。タクソノミーとは、投稿カテゴリー、リンクカテゴリー、タグ、その他のカスタムタクソノミーを指す。
; $term_relationships : The [[データベース概要#Table:_wp_term_relationships|term_relationships]] テーブル。キーワード (terms) と、そのキーワードを使っているオブジェクトの関係性を示す情報を含む。投稿カテゴリーがどの投稿に適用されているか、など。
+
; $term_relationships : [[データベース概要#Table:_wp_term_relationships|term_relationships]] テーブル。キーワード (terms) と、そのキーワードを使っているオブジェクトの関係性を示す情報を含む。投稿カテゴリーがどの投稿に適用されているか、など。
 +
 
 +
; $users : [[データベース概要#Table:_wp_users|Users]] (ユーザー) のテーブル。
 +
; $usermeta : [[データベース概要#Table:_wp_usermeta|usermeta]] (ユーザーメタ情報) テーブル。ニックネーム、説明、パーミッションなどユーザーに関する追加情報を含む。
 +
 
 +
; $links : [[データベース概要#Table:_wp_links|links]] (リンク) のテーブル。
 +
; $options : [[データベース概要#Table:_wp_options|options]] (設定情報) テーブル。
 +
 
 +
=== マルチサイトのテーブル<span id="Multisite_Tables"></span> ===
 +
以下のテーブルはマルチサイトインストールでのみ使用されます。
 +
 
 +
; $blogs : [[Database Description#Table:_wp_blogs|Blogs]] テーブル。これはネットワーク内に作成されたブログ(サイト)のリストです。
 +
 
 +
; $signups : [[Database Description#Table:_wp_signups|Signups]] テーブル。
 +
 
 +
; $site : [[Database Description#Table:_wp_site|Site]] テーブル。これは WordPress インストールの中に作られたネットワーク (以前の WPMU では "sites" と呼ばれていました) のリストです。(このテーブルに普通はサイトが一つだけリストされます。)
 +
 
 +
; $sitemeta : [[Database Description#Table:_wp_sitemeta|Network Options (Site Meta)]] テーブル。これはマルチサイトインストールの全体へ適用されるオプションを含みます。
 +
 
 +
; $sitecategories : [[Database Description#Table:_wp_sitecategories|Site Categories]] テーブル。
 +
 
 +
: '''訳注:''' Site Categories テーブルはデフォルトでは存在しません。詳しくは [https://core.trac.wordpress.org/ticket/12589 Ticket #12589 (Disable/Enable Global Terms)] を見てください。
 +
 
 +
; $registration_log : [[Database Description#Table:_wp_registration_log|Registration Log]] テーブル。
 +
 
 +
; $blog_versions : [[Database Description#Table:_wp_blog_versions|Blog Versions]] テーブル。
 +
 
 +
 
 +
== ソースファイル ==
 +
<tt>wpdb()</tt> は {{Trac|wp-includes/wp-db.php}}にあります。
 +
 
 +
== 外部資料 ==
 +
* [http://qiita.com/ounziw/items/f14e00f10fe5e6fe0150 警告メッセージを改善することの効果 - WordPress のwpdb::prepareメソッドにおける実践]
 +
 
 +
== 関連項目 ==
 +
* Member関数: [[クラスリファレンス/wpdb/esc_like | wpdb::esc_like()]] /[[:en:Class_Reference/wpdb/esc_like|en]] - SQL で使う前に LIKE 文をエスケープする。
 +
 
 +
{{Query Tags}}
 +
 
 +
{{Class Footer}}
  
{{原文|Function_Reference/wpdb_Class|80286}} <!-- 2006-08-21T01:03:22 MacManX 版 -->
+
{{原文|Function_Reference/wpdb_Class|151627}} <!-- 21:55, 14 May 2015 Jdgrimes 版 -->
  
{{DEFAULTSORT:wpdb_Class}}
+
{{DEFAULTSORT:Wpdb_Class}}
 +
[[Category:クラス]]
 
[[Category:上級トピック]]
 
[[Category:上級トピック]]
 
[[Category:デザインとレイアウト]]
 
[[Category:デザインとレイアウト]]

2018年5月27日 (日) 09:59時点における最新版

この項目「関数リファレンス/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 に指定があればそちらを優先する。
使える書式の値は:

もし $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 エスケープしてはいけない)。例えば GETPOST のデータを使う場合、スラッシュがデータベースへ挿入されないように 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 を返します。

参考: 行のクエリは 0FALSE のどちらも返す場合があるので、戻り値を調べるときに注意してください。厳密な等価演算子(===)を使って、エラー(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 エスケープしてはいけません。

プレースホルダー

preparequery パラメータは 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_errorshide_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 
定数 SAVEQUERIESTRUE にすると(デフォルトは FALSE)、データベースで実行したクエリと終了時刻を保存できます。SAVEQUERIESTRUE のとき、クエリが配列としてこの変数へ保存されます。
$last_result 
最後に実行されたクエリの結果。
$col_info 
最後に実行されたクエリの列情報。列情報の取得セクションを参照。
$insert_id 
最後に実行された INSERT クエリで、AUTO_INCREMENT によって生成された ID。
$num_rows 
最後に実行されたクエリで返された行の数。
$prefix 
このサイトの WordPress テーブルに与えられたプリフィックス。

マルチサイト変数

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

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

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

テーブル

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にあります。

外部資料

関連項目

記事

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

  • クラス: WP_Query - WP_Query クラスの詳細な全容
  • クラス: WP_Comment_Query - コメント関連のクエリのためのクラス
  • クラス: WP_User_Query - ユーザー関連のクエリのためのクラス
  • オブジェクト: $wpdb - $wpdb オブジェクトの使い方全容
  • 関数: set_query_var()
  • 関数: get_query_var()
  • 関数: query_posts() - 追加のカスタムクエリを作成
  • 関数: get_post() - 項目の ID を取得しデータベース内にあるその投稿のレコードを返す
  • 関数: get_posts() - 投稿の配列を返すことに特化した関数
  • 関数: get_pages() - ページの配列を返すことに特化した関数
  • 関数: have posts() - クエリが投稿を返すか否かを判断する条件関数
  • 関数: the_post() - クエリ後に自動的にループを設定する
  • 関数: rewind_posts() - 現状のループをリセットする
  • 関数: setup_postdata() - ループ内で個別の結果を得るためのクエリデータを設定する
  • 関数: wp_reset_postdata() - 直前のクエリを復元する (通常はループ内の別のループの後に用いられる)
  • 関数: wp_reset_query()
  • 関数: is_main_query() - 変更されるクエリがメインのクエリであることを確認する
  • アクションフック: pre_get_posts - WordPressクエリが実行される前に変更する
  • アクションフック: the_post - post クエリの後で post オブジェクトを変更する
  • フィルターフック: found_posts - WP_Query オブジェクトの found_posts 値を変更する


クラスリファレンス関数リファレンスの各インデックスも参照してください。

最新英語版: WordPress Codex » Function_Reference/wpdb_Class最新版との差分