PHP マニュアル: SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ

説明

PgSql\Resultfalse pg_query_params(PgSql\Connection $connection = ?, string $query, array $params)

コマンドをサーバーに送信し、その結果を待ちます。パラメータを SQL コマンドとは別に渡すことが可能です。

pg_query_params は pg_query と似ていますが、追加の機能を有しています。それはパラメータ値がコマンド文字列と分離しているということです。 pg_query_params は PostgreSQL 7.4 以降の接続でのみサポートされます。それ以前のバージョンでは失敗します。

パラメータを使用する際は、query 文字列内で $1、$2 のように参照されます。 query の中で同じパラメータを何度も使えます。その場合は、それぞれに同じ値が渡されます。 params で実際の値を指定します。null を指定すると、SQL の NULL とみなされます。

pg_query に対する pg_query_params の最大の利点は、パラメータの値を query 文字列から分離できることです。そのため、退屈でエラーの元となりやすいクォート・エスケープなどをしなくてもよくなります。pg_query と異なり、pg_query_params ではひとつの SQL コマンドしか実行できません（クエリ文字列にセミコロンを含めることは可能です。しかしそれ以降にコマンドを続けることはできません）。

パラメータ

connection

PgSql\Connection クラスのインスタンス。 connection が指定されない場合は、デフォルトの接続を使います。デフォルトの接続とは、pg_connect または pg_pconnect によって確立された直近の接続です。

警告

PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

query

パラメータ化した SQL 文。ひとつの文のみである必要があります（複数の文をセミコロンで区切る形式は使用できません）。パラメータを使用する際は $1、$2 などの形式で参照されます。

ユーザーから受け取った値は常にパラメータとして渡すべきです。直接クエリ文字列に組み込んではいけません。そうしてしまうと、 SQL インジェクション攻撃を受けてしまう可能性があります。また、クォート文字を含むデータの処理でバグの原因になります。何らかの理由でパラメータが使えない場合は、値を適切にエスケープするようにしましょう。

params

プリペアドステートメント中の $1、$2 などのプレースホルダを置き換えるパラメータの配列。配列の要素数はプレースホルダの数と一致する必要があります。

bytea フィールド用の値は、パラメータとして指定できません。 pg_escape_bytea を使うか、ラージオブジェクト関数を使うようにしましょう。

戻り値

成功した場合に PgSql\Result クラスのインスタンスを返します。失敗した場合に false を返します

変更履歴

バージョン	説明
8.1.0	PgSql\Result クラスのインスタンスを返すようになりました。これより前のバージョンでは、リソースを返していました。
8.1.0	`connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。これより前のバージョンでは、リソースを期待していました。

例

例1 pg_query_params の使用法

<?php
// "mary"という名前のデータベースに接続
$dbconn = pg_connect("dbname=mary");

// Joe's Widgets という名前の店を探す。"Joe's Widgets" を
// エスケープする必要がないことに注意
$result = pg_query_params($dbconn, 'SELECT * FROM shops WHERE name = $1', array("Joe's Widgets"));

// pg_query を使用した場合と比較
$str = pg_escape_string("Joe's Widgets");
$result = pg_query($dbconn, "SELECT * FROM shops WHERE name = '{$str}'");

?>

参考

pg_query