• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

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

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

提供: WordPress Codex 日本語版
移動先: 案内検索
(Multi-Site Variables)
(使い方が「変数のSELECT」と同じコードになっていたため、修正)
 
(4人の利用者による、間の46版が非表示)
1行目: 1行目:
== Talking to the Database: The ''wpdb'' Class ==
+
{{CheckTrans}}
  
WordPress defines a class called ''wpdb'', which contains a set of functions used to interact with a database. Its primary purpose is to provide an interface with the WordPress database, but can be used to communicate with any other appropriate database. The class source code is loosely based on the [http://justinvincent.com/ezsql ezSQL] class; written and maintained by [http://www.jvmultimedia.com Justin Vincent]
+
== データベースと話す: ''wpdb'' クラス ==
  
(旧版の訳)
+
WordPressには''wpdb''というクラスが定義されています。
WordPress にはデータベース操作用のクラス関数が用意されています。このクラスは <code>wpdb</code> と呼ばれており、大まかな部分では [http://www.jvmultimedia.com ジャスティン・ヴィンセント]氏が作成し、管理している [http://www.woyano.com/jv/ezsql ezSQL] クラスに基づいています。
+
このクラスには、データベースとのやりとりに使用される一連の関数が含まれています。
 +
その主な目的は、WordPressデータベースとのインターフェイスを提供することですが、他の適切なデータベースと通信するために使用することもできます。
 +
クラスのコードは [http://www.jvmultimedia.com ジャスティン・ヴィンセント氏] が作成し、管理している [http://justinvincent.com/ezsql ezSQL] クラスに概ね基づいています。
  
  
=== Using the ''$wpdb'' Object ===
+
=== ''$wpdb'' オブジェクトを使う ===
  
'''Warning: Methods in the <code>wpdb()</code> class should not be called directly. Use the global <code>$wpdb</code> object instead!'''  
+
'''注意!: <code>wpdb</code> クラスのメソッドを直接呼び出すことはできません。代わりにグローバルの<code>$wpdb</code> オブジェクトを使用してください!'''  
  
(旧訳ここから)<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 グローバル宣言]を忘れないようにしましょう)。(旧訳ここまで)
+
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]を使用します。
  
WordPress provides a global object variable, <code>$wpdb</code>, which is an instantiation of the ''wpdb'' class defined in [https://core.trac.wordpress.org/browser/trunk/src/wp-includes/wp-db.php /wp-includes/wp-db.php]. By default, <code>$wpdb</code> is instantiated to talk to the WordPress database. To access <code>$wpdb</code> in your WordPress PHP code, declare <code>$wpdb</code> as a global variable using the <code>[http://www.php.net/manual/en/language.variables.scope.php#language.variables.scope.global global keyword]</code>, or use the [http://www.php.net/manual/en/language.variables.superglobals.php superglobal <code>$GLOBALS</code>] in the following manner:
+
<pre>
 
+
<code>
+
 
  // 1st Method - Declaring $wpdb as global and using it to execute an SQL query statement that returns a PHP object
 
  // 1st Method - Declaring $wpdb as global and using it to execute an SQL query statement that returns a PHP object
 
   
 
   
24行目: 27行目:
 
   
 
   
 
  $results = $GLOBALS['wpdb']->get_results( 'SELECT * FROM wp_options WHERE option_id = 1', OBJECT );
 
  $results = $GLOBALS['wpdb']->get_results( 'SELECT * FROM wp_options WHERE option_id = 1', OBJECT );
</code>
+
</pre>
  
 
<code>$wpdb</code> オブジェクトは WordPress データベースにあるすべてのテーブルからデータを読み出すために利用できます。これには、WordPress が標準で作成する以外のテーブルも含まれます。例えば、"mytable" というカスタムテーブルから情報を SELECT するには、以下のようにします。
 
<code>$wpdb</code> オブジェクトは WordPress データベースにあるすべてのテーブルからデータを読み出すために利用できます。これには、WordPress が標準で作成する以外のテーブルも含まれます。例えば、"mytable" というカスタムテーブルから情報を SELECT するには、以下のようにします。
  
<code>
+
<pre>
 
  $myrows = $wpdb->[[#SELECT_Generic_Results|get_results]]( "SELECT id, name FROM mytable" );
 
  $myrows = $wpdb->[[#SELECT_Generic_Results|get_results]]( "SELECT id, name FROM mytable" );
</code>
+
</pre>
 
<code>$wpdb</code> オブジェクトは好きな数のテーブルを操作できますが、接続できるのは1つのデータベースだけです (WordPress 用のデータベース)。もし他のデータベースに接続したいという珍しいケースの場合は、適切な接続情報を使って <code>wpdb</code> クラスから独自のオブジェクトをインスタンス化する必要があります。複数のデータベースを使った非常に複雑な構成の場合は、[http://wordpress.org/extend/plugins/hyperdb/ hyperdb] の利用を検討してみてください。
 
<code>$wpdb</code> オブジェクトは好きな数のテーブルを操作できますが、接続できるのは1つのデータベースだけです (WordPress 用のデータベース)。もし他のデータベースに接続したいという珍しいケースの場合は、適切な接続情報を使って <code>wpdb</code> クラスから独自のオブジェクトをインスタンス化する必要があります。複数のデータベースを使った非常に複雑な構成の場合は、[http://wordpress.org/extend/plugins/hyperdb/ hyperdb] の利用を検討してみてください。
  
=== A Warning ===
+
=== 警告<span id="A_Warning"></span> ===
  
'''Some of the functions in this class take an SQL statement as input. You must SQL escape all untrusted values you incorporate into the SQL query to prevent SQL injection attacks. Check the documentation to see if the function you plan to use escapes SQL for you or expects it to be pre-escaped.'''
+
'''このクラスの関数の中には、SQL文を入力として受け取るものがあります。 SQLインジェクション攻撃を防ぐために、SQLクエリーに組み込むすべての信頼できない値をエスケープする必要があります。使おうとしている機能がSQLをエスケープしているか、あるいはすでにエスケープされているかどうかを、ドキュメントで確認してください。'''
  
For more on SQL escaping in WordPress, see the section entitled [[#Protect_Queries_Against_SQL_Injection_Attacks|Protect Queries Against SQL Injection Attacks]] below.
+
WordPressでのSQLエスケープの詳細については、下記の[[#Protect_Queries_Against_SQL_Injection_Attacks|SQL インジェクション攻撃からクエリを保護する]]を参照してください。
  
<!--章ごと削除
+
== 変数の SELECT<span id="SELECT_a_Variable"></span> ==
  
== データベースへ任意のクエリを送信 ==
+
<code>get_var</code> 関数はデータベースから変数を一つ返します。変数は一つしか返ってきませんが、クエリの結果はすべてキャッシュされ、あとから使うことができます。結果にマッチするものがない場合、<tt>NULL</tt> が返されます。
  
<code>query</code> 関数を使えば、WordPress データベースで'''あらゆる''' SQL クエリを実行できます。ただし、SELECT クエリにはより明確な関数 (下記参照) を使うのが一番良いでしょう。
+
=== 使い方 ===
  
<code><?php $wpdb->query('query'); ?></code>
+
<?php $wpdb->get_var( $query, $column_offset, $row_offset ); ?>
  
; query : (文字列) 実行したい SQL クエリ。
+
===パラメータ===
 
+
この関数は影響する行または選択された行の数に対応する整数を返します。もし MySQL エラーが発生した場合は、<code>FALSE</code> を返します ('''注''': 0 または FALSE が返される可能性があるため、正しい比較演算子を使うように心がけてください。例えば、等価演算子 <code>==</code> や 厳密な等価演算子 <code>===</code>)。
+
 
+
注: このクラスの SQL クエリを実行するすべての関数と同様、入力値は SQL エスケープする必要があります (例: <code>wpdb->escape($user_entered_data_string)</code>)。詳しくは以下の "[#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 ==
+
 
+
<code>get_var</code> 関数はデータベースから変数を一つ返します。変数は一つしか返ってきませんが、クエリの結果はすべてキャッシュされ、あとから使うことができます。結果にマッチするものがない場合、<tt>NULL</tt> が返されます。
+
 
+
<code><?php $wpdb->get_var( 'query', column_offset, row_offset ); ?></code>
+
  
 
; query : (文字列) 実行したい SQL クエリ。パラメータを <code>null</code> にすると、前回のクエリ結果のキャッシュ中から指定した変数を返す。
 
; query : (文字列) 実行したい SQL クエリ。パラメータを <code>null</code> にすると、前回のクエリ結果のキャッシュ中から指定した変数を返す。
81行目: 56行目:
 
; row_offset : (整数) 必要としている行のオフセット (一つ目は '''0''')。初期値は '''0'''。
 
; row_offset : (整数) 必要としている行のオフセット (一つ目は '''0''')。初期値は '''0'''。
  
=== 例 ===
+
'''訳注:''' クエリはふつう複数の列(カラム)を持つ複数の行を返すので、どの行のどの列の値を変数として返すかを指定します。
  
ユーザーの数を取得し表示する。
+
=== 用例 ===
 +
 
 +
ユーザーの数を取得し、表示する。
 
<pre>
 
<pre>
 
<?php
 
<?php
91行目: 68行目:
 
</pre>
 
</pre>
  
[[カスタムフィールドの使い方|カスタムフィールドの数値]]合計を返し、表示する。
+
[[カスタムフィールドの使い方|カスタムフィールドの数値]]の合計を取得し、表示する。
 
+
<!--以前の用例
+
<pre>
+
<?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>';
+
?>
+
</pre>
+
-->
+
 
+
 
<pre>
 
<pre>
 
<?php
 
<?php
// set the meta_key to the appropriate custom field meta key
+
// meta_key の値を、合計したいカスタムフィールドのメタキーにする
$meta_key = 'miles';  //実在するメタキーに変更する
+
$meta_key = 'miles';
 
$allmiles = $wpdb->get_var( $wpdb->prepare(  
 
$allmiles = $wpdb->get_var( $wpdb->prepare(  
 
"
 
"
119行目: 85行目:
 
</pre>
 
</pre>
  
<div ="SELECT_a_Row">
+
== 行の SELECT<span id="SELECT_a_Row"></span> ==
== 行の SELECT ==
+
</div>
+
  
クエリから行全体を取り出すには、<code>get_row</code> を使います。この関数を使うと行がオブジェクト、連想配列、またはインデックス配列として返されます。クエリが一つ以上の行にマッチする場合は、あとから使えるようにすべての行がキャッシュされますが、実際に返されるのは指定された行のみです。
+
クエリから行全体を取り出すには、<code>get_row</code> を使います。この関数を使うと行がオブジェクト、連想配列、またはインデックス配列として返されます。クエリが2行以上にマッチする場合は、後から使えるようにすべての行がキャッシュされますが、実際に返されるのは指定された行のみです。マッチする行がなければ <code>NULL</code> を返します。そのため、返された値を何かの引数として使う場合は注意してください(以下の例を見てください)。
 +
 
 +
=== 使い方 ===
 +
 
 +
<?php $wpdb->get_row( $query, $output_type, $row_offset ); ?>
 +
 
 +
===パラメータ===
  
<code><?php $wpdb->get_var( 'query', column_offset, row_offset ); ?></code>
 
 
; query : (文字列) 実行したいクエリ。
 
; query : (文字列) 実行したいクエリ。
 
; output_type : 以下の定数のいずれか。初期値は OBJECT。
 
; output_type : 以下の定数のいずれか。初期値は OBJECT。
133行目: 102行目:
 
; row_offset : (整数) 必要としている行のオフセット (一つ目は '''0''')。初期値は '''0'''。
 
; row_offset : (整数) 必要としている行のオフセット (一つ目は '''0''')。初期値は '''0'''。
  
=== ===
+
=== 用例 ===
  
リンク ID 10に関する情報をすべて取得する。
+
ID が10のリンクに関する情報をすべて取得する。
  
 
<pre>
 
<pre>
141行目: 110行目:
 
</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" をプリント
161行目: 130行目:
 
  echo $mylink[1]; // "10" をプリント
 
  echo $mylink[1]; // "10" をプリント
  
If there is no record with ID 10 in the links table, <code>null</code> will be returned. The following would then be false:
+
ID が10の行が links テーブルに無ければ <code>null</code> が返されます。そのため次の例は false になります:
  
 
<pre>
 
<pre>
 
if ($mylink != null) {
 
if ($mylink != null) {
   // do something with the link
+
   // リンクについて何かする
 
   return true;
 
   return true;
 
} else {
 
} else {
   // no link found
+
   // リンクが見つからなかった
 
   return false;
 
   return false;
 
}
 
}
 
</pre>
 
</pre>
  
== 列の SELECT ==
+
== 列の SELECT<span id="SELECT_a_Column"></span> ==
  
列を SELECT するには、<code>get_col</code> を使います。この関数は. 多次元配列を出力します。クエリによって複数の列が返された場合、列は一つしか返ってきませんが、クエリの結果はすべてキャッシュされ、あとから使うことができます。 Returns <tt>NULL</tt> if no result is found, consider this when using the returned value in arguments, see example below.
+
列を SELECT するには、<code>get_col</code> を使います。この関数は一次元配列を出力します。クエリが複数の列を返した場合、指定された列だけが返ってきますが、後から使えるようにクエリの結果はすべてキャッシュされます。マッチする結果がなければ <code>NULL</code> を返します。そのため、返された値を何かの引数として使う場合は注意してください(以下の例を見てください)。
  
<code><?php $wpdb->get_col('query',column_offset); ?></code>
+
=== 使い方 ===
; query : (文字列) 実行したい SQL クエリ。パラメータを <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>
 
<pre>
 
<?php  
 
<?php  
233行目: 207行目:
 
</pre>
 
</pre>
  
This example lists all posts that contain a particular custom field, but sorted by the value of a second custom field.
+
次の例は、あるカスタムフィールドを持つ投稿をすべて表示します。そのときもう一つのカスタムフィールドの値で並べ替えます。
  
 
<pre>
 
<pre>
 
<?php
 
<?php
// List all posts with custom field Color, sorted by the value of custom field Display_Order
+
// カスタムフィールド Color を持つ投稿を、カスタムフィールド Display_Order の値でソートして表示する。
// does not exclude any 'post_type'
+
// どの投稿タイプも除外しない。
// assumes each post has just one custom field for Color, and one for Display_Order
+
// 前提として、各投稿はカスタムフィールド Color Display_Order をそれぞれちょうど1つ持つ。
$meta_key1 = 'カラー';
+
$meta_key1 = 'Color';
 
$meta_key2 = 'Display_Order';
 
$meta_key2 = 'Display_Order';
  
277行目: 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> と同じくオブジェクト、連想配列、またはインデックス配列のいずれかを指定できます。
If no matching rows are found, or if there is a database error, the return value will be an empty array. If your <tt>$query</tt> string is empty, or you pass an invalid <tt>$output_type</tt>, <tt>NULL</tt> will be returned.
+
1行も見つからないか、データベースエラーが発生した場合は、戻り値が空の配列になります。もし <tt>$query</tt> が空文字列であるか、無効な <tt>$output_type</tt> を指定すると、<tt>NULL</tt> が返されます。
  
<code><?php $wpdb->get_results( 'query', output_type ); ?> </code>
+
=== 使い方 ===
 +
 
 +
<?php $wpdb->get_results( $query, $output_type ); ?>
 +
 
 +
===パラメータ===
  
 
; query : (文字列) 実行したい SQL クエリ。
 
; query : (文字列) 実行したい SQL クエリ。
 
; output_type : 以下の4つの定数のいずれか。初期値は OBJECT。詳細および例については、[[#SELECT_a_Row|行の SELECT]] セクションを参照。
 
; output_type : 以下の4つの定数のいずれか。初期値は OBJECT。詳細および例については、[[#SELECT_a_Row|行の SELECT]] セクションを参照。
  
:* OBJECT -  result will be output as a numerically indexed array of row objects.
+
:* OBJECT -  結果をインデックス配列として出力。要素は行オブジェクト。
:* OBJECT_K - result will be output as an associative array of row objects, using first column's values as keys (duplicates will be discarded).
+
:* OBJECT_K - 結果を連想配列として出力。第1カラムの値をキー(重複は無視される)、行オブジェクトを値とする。
:* ARRAY_A - 結果を will be output as a numerically indexed array of associative arrays, using column names as keys.
+
:* ARRAY_A - 結果をインデックス配列として出力。要素は1行を表す連想配列で、そのキーはカラム名。
:* ARRAY_N - 結果をインデックス配列として出力。
+
:* ARRAY_N - 結果をインデックス配列として出力。要素は1行を表すインデックス配列。
  
Since this function uses the <tt>$wpdb->query()</tt> function all the class variables are properly set.
+
この関数は内部で <tt>$wpdb->query()</tt> を使うので、クラス変数は適切にセットされます。<tt>'SELECT'</tt> クエリの結果(行カウント)は <tt>$wpdb->num_rows</tt> へ入ります。
The results count for a 'SELECT' query will be stored in <tt>$wpdb->num_rows</tt>.
+
 
 +
=== 用例 ===
  
=== 例 ===
+
ID が5のユーザーのすべての下書きの ID とタイトルを取得して、タイトルを echo。
ID が5のユーザーのすべての下書きの ID とタイトルを取得して、タイトルを echo。
+
  
 
<pre>
 
<pre>
315行目: 294行目:
 
</pre>
 
</pre>
  
ID が5のユーザーの下書き情報をすべて取得。
+
ID が5のユーザーの下書き情報をすべて取得。
 
<pre>
 
<pre>
 
<?php
 
<?php
350行目: 329行目:
 
</pre>
 
</pre>
  
== 行の INSERT ==
+
== 行の INSERT<span id="INSERT_row"></span> ==
  
テーブルに行を挿入。
+
テーブルへ行を挿入します。
 +
 
 +
=== 使い方 ===
  
 
  <?php $wpdb->insert( $table, $data, $format ); ?>  
 
  <?php $wpdb->insert( $table, $data, $format ); ?>  
  
; table : (string) データを挿入するテーブル名。
+
===パラメータ===
; data : (array) Data to insert (in column => value pairs). Both <tt>$data</tt> columns and <tt>$data</tt> values should be "raw" (neither should be SQL escaped).
+
; format : (array|string) (optional) An array of formats to be mapped to each of the values in <tt>$data</tt>. If string, that format will be used for all of the values in <tt>$data</tt>. If omitted, all values in <tt>$data</tt> will be treated as strings unless otherwise specified in <tt>wpdb::$field_types</tt>.
+
  
Possible format values: <tt>%s</tt> as string; <tt>%d</tt> as integer (whole number); and <tt>%f</tt> as float. (See [[#Placeholders | below]] for more information.)
+
; 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>による指定があればそちらが優先される。
  
After insert, the ID generated for the <tt>AUTO_INCREMENT</tt> column can be accessed with:
+
: 使用可能な書式の値(詳しくは後の [[#Placeholders | プレースホルダー]] を参照):
 +
:* <tt>%s</tt> - 文字列
 +
:* <tt>%d</tt> - 整数 (すべて数字)
 +
:* <tt>%f</tt> - 浮動小数点数
 +
 
 +
挿入した後、カラム <tt>AUTO_INCREMENT</tt> へ生成された ID は次の方法でアクセスできます:
 
  <pre>$wpdb->insert_id</pre>
 
  <pre>$wpdb->insert_id</pre>
  
This function returns <tt>false</tt> if the row could not be inserted. Otherwise, it returns the number of affected rows (which will always be 1).
+
この関数は、行を挿入できなければ <tt>false</tt> を返します。挿入できたときは影響を受けた行数を返します(いつでも1です)
  
'''Please note''': The value portion of the data parameter's column=>value pairs must be scalar.  If you pass an array (or object) as a value to be inserted you will generate a warning similar to "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".
+
'''注意''': <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>
387行目: 372行目:
 
);
 
);
 
</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 インデックスで調べるためです。'''
 +
 
 +
=== 使い方 ===
 +
 
 +
<?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>
 +
$wpdb->replace(
 +
'table',
 +
array(
 +
'indexed_id' => 1,
 +
'column1' => 'value1',
 +
'column2' => 123
 +
),
 +
array(
 +
'%d',
 +
'%s',
 +
'%d'
 +
)
 +
);
 +
</pre>
 +
 
 +
== 行の UPDATE<span id="UPDATE_rows"></span> ==
 +
 
 +
テーブル内の行を更新します。エラーが生じると <tt>false</tt> を、成功すると影響を受けた行の数を返します。
 +
 
 +
=== 使い方 ===
 +
 
 +
<?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、一つ目の列の値が文字列、2つ目の列の値が数値、という行を更新する。
+
ID が1である行を更新します。第1列の値は文字列、第2列の値は数値とします:
  
 
<pre>
 
<pre>
419行目: 472行目:
 
</pre>
 
</pre>
  
<strong>Attention:</strong> <code>%d</code> can't deal with comma values - if you're <em>not</em> using full numbers, use string/<tt>%s</tt>.
+
<strong>注意:</strong> <code>%d</code> はコンマ入りの値を扱えません。数字だけではない数値を扱うには、文字列(<code>%s</code>)を使ってください。
  
== 列の DELETE ==
+
== 行の DELETE<span id="DELETE_Rows"></span> ==
  
The <tt>delete</tt> function was added in WordPress [[Version_3.4|3.4.0]], and can be used to delete rows from a table. The usage is very similar to <tt>[[#UPDATE_Rows|update]]</tt> and <tt>[[#INSERT_Rows|insert]]</tt>. It returns the number of rows updated, or <tt>false</tt> on error.
+
<tt>delete</tt> 関数は WordPress [[Version_3.4|3.4.0]] で追加されました。テーブルから行を削除するのに使います。使い方は <tt>[[#UPDATE_rows | update]]</tt> <tt>[[#INSERT_row | insert]]</tt> にとてもよく似ています。削除された行の数を返しますが、エラーが発生すると <tt>false</tt> を返します。
  
 
===使い方===
 
===使い方===
431行目: 484行目:
 
===パラメータ===
 
===パラメータ===
  
{{Parameter|$table|string|テーブル名}}
+
{{Parameter|$table|文字列|テーブル名}}
{{Parameter|$where|array|A named array of <tt>WHERE</tt> clauses (in column -> value pairs). Multiple clauses will be joined with <tt>AND</tt>s. Both <tt>$where</tt> columns and <tt>$where</tt> values should be 'raw'.}}
+
{{Parameter|$where|array|<tt>WHERE</tt> 句に使う連想配列(列の名前->値)。複数の句を指定すると <tt>AND</tt> で結合される。<tt>$where</tt> の列の名前と値は両方とも 'raw' でなければならない。}}
{{Parameter|$where_format|string/array|An array of formats to be mapped to each of the values in <tt>$where</tt>. If a string, that format will be used for all of the items in <tt>$where</tt>. A format is one of <tt>'%d'</tt>, <tt>'%f'</tt>, <tt>'%s'</tt> (integer, float, string; see [[#Placeholders | below]] for more information). If omitted, all values in <tt>$where</tt> will be treated as strings unless otherwise specified in <tt>wpdb::$field_types</tt>.|optional|<tt>null</tt>}}
+
{{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>
 
<pre>
// デフォルトの使用例
+
// デフォルトの使い方。
 
$wpdb->delete( 'table', array( 'ID' => 1 ) );
 
$wpdb->delete( 'table', array( 'ID' => 1 ) );
  
// Using where formatting.
+
// where 句の書式を指定。
 
$wpdb->delete( 'table', array( 'ID' => 1 ), array( '%d' ) );
 
$wpdb->delete( 'table', array( 'ID' => 1 ), array( '%d' ) );
 
</pre>
 
</pre>
  
== Running General Queries ==
+
== 任意のクエリの実行<span id="Running_General_Queries"></span> ==
  
The <code>query</code> function allows you to execute any SQL query on the WordPress database. It is best used when there is a need for specific, custom, or otherwise complex SQL queries. For more basic queries, such as selecting information from a table, see the other <code>wpdb</code> functions above.
+
<code>query</code> 関数を使うと WordPress データベースに対して任意の SQL クエリを実行できます。特定用途や複雑な SQL クエリが必要なときに最適です。情報を選び出すようなもっと基本的なクエリの場合は、ここまでに説明した他の <code>wpdb</code> 関数を見てください。
  
 
=== 一般的な構文 ===
 
=== 一般的な構文 ===
  
  <?php $wpdb->query('query'); ?>  
+
  <?php $wpdb->query( $query ); ?>  
  
; query : (string) 実行したいSQLクエリ。
+
===パラメータ===
  
This function returns an integer value indicating the number of rows affected/selected for SELECT, INSERT, DELETE, UPDATE, etc. For CREATE, ALTER, TRUNCATE and DROP SQL statements, (which affect whole tables instead of specific rows) this function returns <code>TRUE</code> on success. If a MySQL error is encountered, the function will return <code>FALSE</code>. Note that since both 0 and <code>FALSE</code> may be returned for row queries, you should be careful when checking the return value. Use the identity operator (<tt>===</tt>) to check for errors (e.g., <tt>false === $result</tt>), and whether any rows were affected (e.g., <tt>0 === $result</tt>).
+
; 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>)を確かめましょう。
  
 
=== 用例 ===
 
=== 用例 ===
Delete the 'gargle' meta key and value from Post 13. (We'll add the 'prepare' method to make sure we're not dealing with an illegal operation or any illegal characters):
+
 
 +
ID が 13 の投稿から投稿メタ 'gargle' のキーと値を削除します。(ここで 'prepare' メソッドを使うのは、不正な操作や不正な文字を処理しないためです):
 +
 
 
<pre>
 
<pre>
 
$wpdb->query(  
 
$wpdb->query(  
 
$wpdb->prepare(  
 
$wpdb->prepare(  
 
"
 
"
                DELETE FROM $wpdb->postmeta
+
DELETE FROM $wpdb->postmeta
WHERE post_id = %d
+
WHERE post_id = %d
AND meta_key = %s
+
AND meta_key = %s
 
",
 
",
        13, 'gargle'  
+
13, 'gargle'  
        )
+
)
 
);
 
);
 
 
</pre>
 
</pre>
''Performed in WordPress by <code>[[Function Reference/delete post meta|delete_post_meta()]]</code>.''
 
  
 +
''WordPress が <code>[[関数リファレンス/delete post meta|delete_post_meta()]]</code> の内部で実行するコード:''
 +
 +
 +
ID が 7 の[[固定ページ]]へ親として ID が 15 の[[固定ページ]]を設定する。
  
Set the parent of [[Pages|Page]] 15 to Page 7.
 
 
<pre>
 
<pre>
 
$wpdb->query(
 
$wpdb->query(
486行目: 546行目:
 
</pre>
 
</pre>
  
 +
== SQL インジェクション攻撃からクエリを保護する<span id="Protect_Queries_Against_SQL_Injection_Attacks"></span> ==
  
<div id=Protect_Queries_Against_SQL_Injection_Attacks">
+
WordPress における SQL エスケープのより詳しい説明は [[データ検証#Database|データベースのデータ検証]] ページを見てください。これはコア貢献者やプラグイン作者が '''必ず読むべき''' ページです。
  
== SQL インジェクション攻撃からクエリを保護する ==
+
簡単にいうと、SQL インジェクション攻撃からクエリを保護するためには、実行する前にクエリデータをすべて SQL エスケープする必要があります。
</div>
+
WordPress では <code>prepare</code> メソッドがこの機能を提供します。[http://php.net/sprintf sprintf()] 風と [http://php.net/vsprintf vsprintf()] 風の両方の書き方を利用できます。
  
WordPress での SQL エスケープについてのより詳しい概要は、[[データ検証#.E3.83.87.E3.83.BC.E3.82.BF.E3.83.99.E3.83.BC.E3.82.B9|データベースのデータ検証]]ページをご覧ください。これはコア貢献者やプラグイン作者が '''必ず読むべき''' ページです。
+
'''注意''': 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/ 詳しくはこちら。]]
  
簡単にいうと、SQL インジェクション攻撃からクエリを保護するためには、実行する前にクエリデータはすべて SQL エスケープする必要があります。
+
=== 使い方 ===
The <code>prepare</code> method performs this functionality for WordPress, which supports both a [http://php.net/sprintf sprintf()]-like and [http://php.net/vsprintf vsprintf()]-like syntax.
+
  
'''Please note''': As of [[Version 3.5|3.5]], <tt>wpdb::prepare()</tt> enforces a '''minimum of 2 arguments'''. [[http://make.wordpress.org/core/2012/12/12/php-warning-missing-argument-2-for-wpdb-prepare/ more info]]
+
<?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 : (整数|文字列|array) プレースホルダーに代入する値。Many values may be passed by simply passing more arguments in a [http://php.net/sprintf sprintf()]-like fashion. Alternatively the second argument can be an array containing the values as in PHP's [http://php.net/vsprintf vsprintf()] function. Care must be taken not to allow direct user input to this parameter, which would enable array manipulation of any query with multiple placeholders. Values cannot be SQL-escaped.
+
; value_parameter : (整数|文字列|配列) プレースホルダーへ代入する値。[http://php.net/sprintf sprintf()] 風の書き方でたくさんの値を渡すことができます。別の方法として、PHP の関数 [http://php.net/vsprintf vsprintf()] 風に値を並べた配列を第2引数にすることもできます。
 +
'''注意''': ユーザーが入力したものを直接このパラメータにしてはいけません。もしそうすると、複数のプレースホルダーを含む任意のクエリに対して配列操作を行ってしまいます。値は SQL エスケープしてはいけません。
  
===プレースホルダー===
+
=== プレースホルダー<span id="Placeholders"></span> ===
The <tt>query</tt> parameter for <tt>prepare</tt> accepts [http://php.net/sprintf sprintf()]-like placeholders. The <tt>%s</tt> (string), <tt>%d</tt> (integer) and <tt>%f</tt> (float) formats are supported. (The <tt>%s</tt> and <tt>%d</tt> placeholders have been available since the function was added to core in [[Version 2.3]], <tt>%f</tt> has only been available since [[Version 3.3]].) Any other <code>%</code> characters may cause parsing errors unless they are escaped. All <code>%</code> characters inside SQL string literals, including LIKE wildcards, must be double-% escaped as <code>%%</code>. All of <tt>%d</tt>, <tt>%f</tt>, and <tt>%s</tt> are to be left unquoted in the query string. Note that the <tt>%d</tt> placeholder only accepts integers, so '''you can't pass numbers that have comma values via <tt>%d</tt>'''. If you need comma values, use <tt>%f</tt> as float instead.
+
<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> です。
Add Meta key => value pair "Harriet's Adages" => "WordPress' database interface is like Sunday Morning: Easy." to Post 10.
+
 
<pre>
 
<pre>
 
$metakey = "Harriet's Adages";
 
$metakey = "Harriet's Adages";
525行目: 588行目:
 
) );
 
) );
 
</pre>
 
</pre>
''Performed in WordPress by <code>[[関数リファレンス/add_meta|add_meta()]]</code>.''
+
''同様の処理が WordPress <code>[[関数リファレンス/add_meta|add_meta()]]</code> /[[:en:Function Reference/add meta|en]] で行われています。''
  
The same query using [http://php.net/vsprintf vsprintf()]-like syntax.
+
同じクエリを [http://php.net/vsprintf vsprintf()] 風の構文で書くと次のようになります。
 
<pre>
 
<pre>
 
$metakey = "Harriet's Adages";
 
$metakey = "Harriet's Adages";
545行目: 608行目:
 
) );
 
) );
 
</pre>
 
</pre>
 +
''この例では値を配列にまとめています。この方法は、実行するときまで引数の個数がわからない場合に有用です。''
  
''Note that in this example we pack the values together in an array. This can be useful when we don't know the number of arguments we need to pass until runtime.''
+
文字列をクォートで囲む必要がない点に注目しましょう。SQL クエリに変数を直接入れて渡すのではなく、プレースホルダーとして文字列には <code>%s</code>、整数には <code>%d</code>、浮動小数点数には <tt>%f</tt> を使ってください。渡す値の個数に制限はなく、1つずつ <code>prepare()</code> メソッドの新しいパラメーターにします。
  
文字列をクオートで囲む必要がない点に注目しましょう。SQL クエリに変数を直接渡すのではなく、文字列には <code>%s</code> プレースホルダーを、整数には <code>%d</code> プレースホルダーを使っています。, and a <tt>%f</tt> as a placeholder for floats. 渡す値の数に制限はありません。それぞれ、<code>prepare()</code> メソッドで新しいパラメーターにします。
+
== SQL エラーの表示・非表示<span id="Showing_and_Hiding_SQL_Errors"></span> ==
  
 +
<code>show_errors</code> と <code>hide_errors</code> を使い、エラーの出力を有効化・無効化できます。
  
<div id="Showing_and_Hiding_SQL_Errors">
+
<?php $wpdb->show_errors(); ?>
 +
<?php $wpdb->hide_errors(); ?>
  
== SQL エラーの表示・非表示 ==
+
最後に実行されたクエリにエラーがある場合、<code>print_error</code> でそのエラーを表示できます。
</div>
+
  
<code>show_errors</code> と <code>hide_errors</code> を使い、エラーの出力を有効化・無効化できます。
+
<?php $wpdb->print_error(); ?>
  
<code><?php $wpdb->show_errors(); ?>
+
<strong>参考:</strong> マルチサイトの WordPress の場合、データベースを表示するには定数 <tt>DIEONDBERROR</tt> を次のように定義しなければなりません:<br />
<?php $wpdb->hide_errors(); ?></code>
+
<?php define( 'DIEONDBERROR', true ); ?>
  
最後に実行されたクエリにエラーがある場合、<code>print_error</code> でそのエラーを表示できます。
+
== 列情報の取得<span id="Getting_Column_Information"></span> ==
  
<code><?php $wpdb->print_error(); ?></code>
+
<code>get_col_info</code> を使えば、最後に実行したクエリ結果の列に関する情報を取得できます。これは、関数が属性が分からない OBJECT を返してきた際に便利です。この関数は指定した列から取得したい情報を出力します。列が指定されていない場合は、クエリ結果に含まれるすべての列の情報を含む配列を出力します。
  
<strong>Note:</strong> If you are running WordPress Multisite, you must define the DIEONDBERROR constant for database errors to display like so:
+
=== 使い方 ===
<br />%%% <?php define( 'DIEONDBERROR', true ); ?> %%%
+
  
 +
<?php $wpdb->get_col_info( $type, $offset ); ?>
  
<div id="Getting_Column_Information">
+
=== パラメータ ===
== 列情報の取得 ==
+
</div>
+
<code>get_col_info</code> を使えば、最後に実行したクエリ結果の列に関する情報を取得できます。これは、関数が属性が分からない OBJECT を返してきた際に便利です。この関数は指定した列から取得したい情報を出力します。列が指定されていない場合は、クエリ結果に含まれるすべての列の情報を含む配列を出力します。
+
  
<code><?php $wpdb->get_col_info('type', offset); ?></code>
+
; type : (文字列) 取得したい情報。以下の値から選べる ([https://github.com/ezSQL/ezSQL/blob/master/ez_sql_help.htm ezSQL のドキュメンテーション]から転載)。初期値は '''name'''。
; type : (文字列) 取得したい情報。以下の値から選べる ([jvmultimedia.com/docs/ezsql/ez_sql_help.htm ezSQL のドキュメンテーション]から転載)。初期値は '''name'''。
+
 
:*name - カラム名 (初期値)。
 
:*name - カラム名 (初期値)。
 
:*table - 列が含まれるテーブル名。
 
:*table - 列が含まれるテーブル名。
589行目: 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 : 最後に実行されたクエリ。
; $last_error : The most recent error text generated by MySQL.
+
; $last_error : MySQL で生成された最新のエラー文字列。
; $queries : You may save all of the queries run on the database and their stop times by setting the <tt>SAVEQUERIES</tt> constant to <tt>TRUE</tt> (this constant defaults to <tt>FALSE</tt>). If <tt>SAVEQUERIES</tt> is <tt>TRUE</tt>, your queries will be stored in this variable as an array.
+
; $queries : 定数 <tt>SAVEQUERIES</tt> <tt>TRUE</tt> にすると(デフォルトは <tt>FALSE</tt>)、データベースで実行したクエリと終了時刻を保存できます。<tt>SAVEQUERIES</tt> <tt>TRUE</tt> のとき、クエリが配列としてこの変数へ保存されます。
<!-- 旧版の訳
+
; $queries : SAVEQUERIES 定数を TRUE に設定することで (定数の初期値は FALSE)、データベースで実行するクエリおよに停止時間を保存できる。SAVEQUERIES が TRUE の場合、クエリはこの変数に配列として保存される。-->
+
 
+
 
; $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 : The assigned WordPress table prefix for the site.
+
; $prefix : このサイトの WordPress テーブルに与えられたプリフィックス。
  
 
=== マルチサイト変数 ===
 
=== マルチサイト変数 ===
619行目: 678行目:
 
マルチサイトを使用する場合、以下にアクセスする場合があります:
 
マルチサイトを使用する場合、以下にアクセスする場合があります:
  
; $blogid :  現在のサイト(ブログ)のID。
+
; $blogid :  現在のサイト(ブログ)の ID。
; $siteid :  現在のネットワーク(正式には"サイト")のID。WordPress currently only supports one network per multi-site install, but that could change in future.
+
; $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://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.
 
* 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]] (投稿・固定ページ) テーブル。
 +
; $postmeta : [[データベース概要#Table:_wp_postmeta|postmeta]] (メタコンテンツ、[[カスタムフィールドの使い方|カスタムフィールド]]) テーブル。
 +
 
; $comments : [[データベース概要#Table:_wp_comments|comments]] (コメント) テーブル。
 
; $comments : [[データベース概要#Table:_wp_comments|comments]] (コメント) テーブル。
; $commentmeta : The table contains additional comment information.
+
; $commentmeta : 追加のコメント情報を含むテーブル。
; $links : [[データベース概要#Table:_wp_links|links]] (リンク情報) テーブル。
+
 
; $options : [[データベース概要#Table:_wp_options|options]] (設定情報) テーブル。
+
; $termmeta : タームのメタ情報を含むテーブル。
; $postmeta : [[データベース概要#Table:_wp_postmeta|postmeta]] (= メタコンテンツ、[[カスタムフィールドの使い方|カスタムフィールド]]) テーブル。
+
; $usermeta : [[データベース概要#Table:_wp_usermeta|usermeta]] (ユーザーメタ情報) テーブル。ニックネーム、説明、パーミッションなどユーザーに関する追加情報を含む。
+
; $comments : The [[Database Description#Table:_wp_comments|Comments]] table.
+
; $commentmeta : The table contains additional comment information.
+
 
; $terms : [[データベース概要#Table:_wp_terms|terms]] (キーワード情報) テーブル。カテゴリーの説明、リンクカテゴリー、タグなどの情報を含む。
 
; $terms : [[データベース概要#Table:_wp_terms|terms]] (キーワード情報) テーブル。カテゴリーの説明、リンクカテゴリー、タグなどの情報を含む。
 
 
; $term_taxonomy : [[データベース概要#Table:_wp_term_taxonomy|term_taxonomy]] テーブル。キーワード (terms) のクラスであるタクソノミーの情報を含む。タクソノミーとは、投稿カテゴリー、リンクカテゴリー、タグ、その他のカスタムタクソノミーを指す。
 
; $term_taxonomy : [[データベース概要#Table:_wp_term_taxonomy|term_taxonomy]] テーブル。キーワード (terms) のクラスであるタクソノミーの情報を含む。タクソノミーとは、投稿カテゴリー、リンクカテゴリー、タグ、その他のカスタムタクソノミーを指す。
 
; $term_relationships : [[データベース概要#Table:_wp_term_relationships|term_relationships]] テーブル。キーワード (terms) と、そのキーワードを使っているオブジェクトの関係性を示す情報を含む。投稿カテゴリーがどの投稿に適用されているか、など。
 
; $term_relationships : [[データベース概要#Table:_wp_term_relationships|term_relationships]] テーブル。キーワード (terms) と、そのキーワードを使っているオブジェクトの関係性を示す情報を含む。投稿カテゴリーがどの投稿に適用されているか、など。
  
; $users : The table of [[Database Description#Table:_wp_users|Users]].
+
; $users : [[データベース概要#Table:_wp_users|Users]] (ユーザー) のテーブル。
; $usermeta : The [[Database Description#Table:_wp_usermeta|usermeta]] table contains additional user information, such as nicknames, descriptions and permissions.
+
; $usermeta : [[データベース概要#Table:_wp_usermeta|usermeta]] (ユーザーメタ情報) テーブル。ニックネーム、説明、パーミッションなどユーザーに関する追加情報を含む。
; $links : The table of [[Database Description#Table:_wp_links|Links]].
+
; $options : The [[Database Description#Table:_wp_options|Options]] table.
+
  
=== マルチサイトのテーブル ===
+
; $links : [[データベース概要#Table:_wp_links|links]] (リンク) のテーブル。
These tables are used only in multisite installations.
+
; $options : [[データベース概要#Table:_wp_options|options]] (設定情報) テーブル。
  
; $blogs : The [[Database Description#Table:_wp_blogs|Blogs]] table contains a list of the separate blogs (sites) that have been set up within the network(s).
+
=== マルチサイトのテーブル<span id="Multisite_Tables"></span> ===
 +
以下のテーブルはマルチサイトインストールでのみ使用されます。
  
; $signups : The [[Database Description#Table:_wp_signups|Signups]] table.
+
; $blogs : [[Database Description#Table:_wp_blogs|Blogs]] テーブル。これはネットワーク内に作成されたブログ(サイト)のリストです。
  
; $site : The [[Database Description#Table:_wp_site|Site]] table contains a list of the networks (previously known as "sites" in WPMU) that are set up in the installation (usually there is only one site listed in this table).
+
; $signups : [[Database Description#Table:_wp_signups|Signups]] テーブル。
  
; $sitemeta : The [[Database Description#Table:_wp_sitemeta|Network Options (Site Meta)]] table contains any options that are applicable to the entire multisite installation.
+
; $site : [[Database Description#Table:_wp_site|Site]] テーブル。これは WordPress インストールの中に作られたネットワーク (以前の WPMU では "sites" と呼ばれていました) のリストです。(このテーブルに普通はサイトが一つだけリストされます。)
  
; $sitecategories : The [[Database Description#Table:_wp_sitecategories|Site Categories]] table.
+
; $sitemeta : [[Database Description#Table:_wp_sitemeta|Network Options (Site Meta)]] テーブル。これはマルチサイトインストールの全体へ適用されるオプションを含みます。
  
; $registration_log : The [[Database Description#Table:_wp_registration_log|Registration Log]] table.
+
; $sitecategories : [[Database Description#Table:_wp_sitecategories|Site Categories]] テーブル。
  
; $blog_versions : The [[Database Description#Table:_wp_blog_versions|Blog Versions]] table.
+
: '''訳注:''' 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}}にあります。
 
<tt>wpdb()</tt> は {{Trac|wp-includes/wp-db.php}}にあります。
  
== 関連 ==
+
== 外部資料 ==
* Member関数: [[Class_Reference/wpdb/esc_like | wpdb::esc_like()]] - Escape LIKE statements before use in SQL.
+
* [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}}
 
{{Query Tags}}
676行目: 740行目:
 
{{Class Footer}}
 
{{Class Footer}}
  
{{NeedTrans|一部}}
+
{{原文|Function_Reference/wpdb_Class|151627}} <!-- 21:55, 14 May 2015 Jdgrimes 版 -->
 
+
{{原文|Function_Reference/wpdb_Class|151627}} <!-- 21:55, 14 May 2015‎ Jdgrimes 版 -->
+
  
{{DEFAULTSORT:wpdb_Class}}
+
{{DEFAULTSORT:Wpdb_Class}}
 
[[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最新版との差分