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

# pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ

### 説明

function pg_query_params(PgSql\Connection `$connection` = ?, string `$query`, array `$params`): PgSql\Result|false

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

pg_query_params() は pg_query() と似ていますが、追加の機能を有しています。それはパラメータ値が コマンド文字列と分離しているということです。

パラメータを使用する際は、`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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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() - クエリを実行する

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open