PHP マニュアル: SQL文を準備し、変数をバインドし、実行する

説明

オブジェクト指向型

public mysqli_resultbool mysqli::execute_query(string $query, arraynull $params = null)

手続き型

mysqli_resultbool mysqli_execute_query(mysqli $mysql, string $query, arraynull $params = null)

SQL文を準備し、変数をバインドし、実行します。 mysqli::execute_query メソッドは mysqli::prepare, mysqli_stmt::bind_param, mysqli_stmt::execute, mysqli_stmt::get_result のショートカットです。

SQL文のテンプレートは、ゼロ個以上のクエスチョンマーク (?) を使ったパラメータマーカを含めることができます。パラメータマーカは、プレースホルダとも呼ばれています。 params を使って配列で指定しなければいけません。

プリペアドステートメントは内部的に作成され、その処理は関数の外部に公開されません。よって、mysqli_stmt オブジェクトを使うとアクセスできる、ステートメントのプロパティにはアクセスできません。この制限により、状態の情報は mysqli オブジェクトにコピーされ、たとえば mysqli_affected_rows や mysqli_error のようなメソッドを通じてアクセスできます。

注意:
サーバーの max_allowed_packet より長いステートメントを mysqli_execute_query に渡した場合、返ってくるエラーコードはオペレーティングシステムによって異なります。それぞれ、次のように振る舞います:

Linux 上では、エラーコード 1153 を返します。エラーメッセージは got a packet bigger than max_allowed_packet bytes です。

Windows では、エラーコード 2006 を返します。エラーメッセージは server has gone away です。

パラメータ

link

手続き型のみ: mysqli_connect あるいは mysqli_init が返す mysqliオブジェクト。

query

クエリ表す文字列。単一の SQL 文で構成されている必要があります。

SQL文には、適切な位置にゼロ個以上のパラメータマーカを含めることができます。パラメータマーカは、クエスチョンマーク(?)で表します。

注意:
マーカーは SQL文中の特定の場所でのみ有効です。 INSERT文の (行のカラムの値を指定する) VALUES() のリストや、 WHERE 句でカラムのデータと比較する値などが適切な位置の例です。しかし、識別子 (テーブルやカラムの名前) には使用できません。

params

オプションのリストを配列で指定します。これは、実行される SQL文中でバインドされるパラメータと同じ要素数を持ちます。個々の値は、文字列として扱われます。

戻り値

失敗時に false を返します。 SELECT, SHOW, DESCRIBE や EXPLAIN のような、結果セットを生成するクエリが成功した時には mysqli_result オブジェクトを返します。それ以外のクエリの場合は、true を返します。

例

例1 mysqli::execute_query の例

オブジェクト指向型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli('localhost', 'my_user', 'my_password', 'world');

$query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
$result = $mysqli->execute_query($query, ['DEU']);
foreach ($result as $row) {
    printf("%s (%s)\n", $row["Name"], $row["District"]);
}

手続き型

<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = 'SELECT Name, District FROM City WHERE CountryCode=? ORDER BY Name LIMIT 5';
$result = mysqli_execute_query($link, $query, ['DEU']);
foreach ($result as $row) {
    printf("%s (%s)\n", $row["Name"], $row["District"]);
}

上の例の出力は、たとえば以下のようになります。

Aachen (Nordrhein-Westfalen)
Augsburg (Baijeri)
Bergisch Gladbach (Nordrhein-Westfalen)
Berlin (Berliini)
Bielefeld (Nordrhein-Westfalen)

参考

mysqli_prepare
mysqli_stmt_execute
mysqli_stmt_bind_param
mysqli_stmt_get_result