【PHP8.x】PDO::FETCH_KEY_PAIR定数の使い方

FETCH_KEY_PAIR定数の使い方について、初心者にもわかりやすく解説します。

作成日: 2025年09月11日更新日: 2026年01月12日

基本的な使い方

FETCH_KEY_PAIR定数は、PHPのPDO拡張機能において、データベースから結果を取得する際のフェッチモードの一つを表す定数です。この定数は、主にPDOStatement::fetch()メソッドやPDO::query()メソッドの引数として使用され、取得される結果セットのデータの形式を指定します。

このフェッチモードを使用すると、データベースから返される各行が、キーと値のペアを持つ連想配列としてフォーマットされます。具体的には、結果セットの最初のカラムの値が連想配列のキーとなり、2番目のカラムの値がそのキーに対応する値として設定されます。例えば、IDと名前の2つのカラムを持つテーブルからデータを取得する場合、IDが配列のキー、名前がそのキーに対応する値として格納された連想配列が得られます。

この定数は、特定のキーとその値の対応関係を効率的に取得したい場合に非常に便利です。例えば、設定情報のキーと値のリストや、マスタデータのIDと名称の対応リストなどを取得する際に役立ちます。もし結果セットが3カラム以上であっても、このモードでは最初の2つのカラムのみが使用され、残りのカラムは無視されます。また、キーとなる最初のカラムに重複する値が存在する場合、後から取得された値が前の値を上書きする形で連想配列に格納されますので、この点には注意が必要です。

構文(syntax)


1<?php
2
3// PDOStatement オブジェクトが `$stmt` に格納されていると仮定します。
4// この例では、インメモリSQLiteデータベースを使用して具体的な `$stmt` を作成します。
5// SQLクエリで最初のカラムがキー、次のカラムが値になるように選択します。
6
7try {
8    // データベースに接続 (例: インメモリSQLite)
9    $pdo = new PDO('sqlite::memory:');
10    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
11
12    // テスト用のテーブルを作成しデータを挿入
13    $pdo->exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
14    $pdo->exec('INSERT INTO users (id, name) VALUES (1, "Alice"), (2, "Bob"), (3, "Charlie")');
15
16    // SQLクエリを準備 (idをキー、nameを値として取得)
17    $stmt = $pdo->prepare('SELECT id, name FROM users');
18    $stmt->execute();
19
20    // PDO::FETCH_KEY_PAIR 定数を使用して、結果をキーと値のペアの連想配列として取得します。
21    // 結果の最初のカラムが配列のキー、2番目のカラムが配列の値になります。
22    $keyValuePairResult = $stmt->fetchAll(PDO::FETCH_KEY_PAIR);
23
24    /*
25    $keyValuePairResult の内容は以下のようになります：
26    [
27        1 => 'Alice',
28        2 => 'Bob',
29        3 => 'Charlie',
30    ]
31    */
32
33    // 取得した結果の利用例
34    // echo $keyValuePairResult[1]; // 'Alice' を出力
35
36} catch (PDOException $e) {
37    // エラーハンドリング (ここでは簡略化)
38    // echo "エラー: " . $e->getMessage();
39}
40
41?>

引数(parameters)

引数なし

引数はありません

戻り値(return)

戻り値なし

戻り値はありません

サンプルコード

PHP PDO FETCH_KEY_PAIR でキーと値のペアを取得する


1<?php
2
3/**
4 * PDO::FETCH_KEY_PAIR を使用してデータベースからキーと値のペアを取得するサンプル
5 * この関数は、インメモリのSQLiteデータベースに接続し、
6 * サンプルデータを作成・挿入し、その後 PDO::FETCH_KEY_PAIR を用いてデータを取得します。
7 *
8 * PDO::FETCH_KEY_PAIR は、結果セットの最初のカラムをキー、2番目のカラムを値とする
9 * 連想配列として行を取得する際に使用します。
10 *
11 * @return array キーと値のペアの配列、またはエラー時は空の配列
12 */
13function getKeyValuePairsFromDatabase(): array
14{
15    // エラーハンドリングのためのtry-catchブロック
16    try {
17        // 1. データベースへの接続
18        // SQLiteのインメモリデータベースに接続します。これはファイルとして保存されず、
19        // スクリプトの実行中にのみ存在するため、テストや簡単な例に適しています。
20        $pdo = new PDO('sqlite::memory:');
21
22        // エラーモードを例外に設定
23        // これにより、SQL実行時にエラーが発生した場合、PDOExceptionがスローされ、
24        // 問題をより簡単に捕捉・処理できるようになります。
25        $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
26
27        echo "データベースに接続しました。\n";
28
29        // 2. テーブルの作成
30        // 'configurations' というテーブルを作成します。
31        // 'config_key' がキー、'config_value' が値として使用されることを想定しています。
32        $pdo->exec("CREATE TABLE IF NOT EXISTS configurations (
33            id INTEGER PRIMARY KEY AUTOINCREMENT,
34            config_key TEXT NOT NULL UNIQUE,
35            config_value TEXT NOT NULL
36        )");
37        echo "テーブル 'configurations' を作成しました。\n";
38
39        // 3. サンプルデータの挿入
40        // キーと値のペアのサンプルデータをテーブルに挿入します。
41        // 'INSERT OR IGNORE' を使用することで、キーが重複した場合でもエラーにならず、
42        // 既に存在する行はスキップされます。
43        $pdo->exec("INSERT OR IGNORE INTO configurations (config_key, config_value) VALUES ('appName', 'MyWebApp')");
44        $pdo->exec("INSERT OR IGNORE INTO configurations (config_key, config_value) VALUES ('version', '1.0.0')");
45        $pdo->exec("INSERT OR IGNORE INTO configurations (config_key, config_value) VALUES ('timezone', 'Asia/Tokyo')");
46        echo "サンプルデータを挿入しました。\n";
47
48        // 4. PDO::FETCH_KEY_PAIR を使用してデータを取得
49        // SELECT文で、キーにしたいカラム (config_key) を最初に、
50        // 値にしたいカラム (config_value) を2番目に指定します。
51        $stmt = $pdo->query("SELECT config_key, config_value FROM configurations ORDER BY config_key");
52
53        // fetchAll() メソッドに PDO::FETCH_KEY_PAIR 定数を渡して実行します。
54        // 結果は ['config_key1' => 'config_value1', 'config_key2' => 'config_value2', ...]
55        // のような連想配列として取得されます。
56        $configPairs = $stmt->fetchAll(PDO::FETCH_KEY_PAIR);
57
58        echo "\n--- PDO::FETCH_KEY_PAIR で取得した結果 ---\n";
59        print_r($configPairs);
60        echo "--------------------------------------\n";
61
62        return $configPairs;
63
64    } catch (PDOException $e) {
65        // データベース関連のエラー（接続失敗、SQL実行エラーなど）を捕捉し、表示します。
66        echo "データベースエラーが発生しました: " . $e->getMessage() . "\n";
67        return []; // エラー時は空の配列を返す
68    }
69}
70
71// 関数を実行して結果を表示
72getKeyValuePairsFromDatabase();

PHPのPDO::FETCH_KEY_PAIRは、データベースからデータを取得する際に結果の形式を指定するための定数です。これはPHPのPDO拡張機能に属しており、PDOStatement::fetchAll()メソッドの引数として渡すことで、取得結果を特定の形式に整形します。この定数自体に引数はなく、直接の戻り値もありませんが、fetchAll()メソッドに適用された場合、そのメソッドは整形された結果の配列を返します。

PDO::FETCH_KEY_PAIRを使用すると、データベースからの結果セットにおいて、最初のカラムが連想配列のキーとなり、2番目のカラムがそのキーに対応する値として抽出されます。これにより、['キー1' => '値1', 'キー2' => '値2', ...]のようなキーと値のペアからなる連想配列を効率的に取得できます。

提供されたサンプルコードでは、まずSQLiteのインメモリデータベースに接続し、configurationsというテーブルを作成して設定情報のようなキーと値のペアとなるサンプルデータを挿入しています。その後、SELECT config_key, config_value FROM configurationsというSQLクエリを実行し、その結果をPDO::FETCH_KEY_PAIRを用いて取得しています。これにより、例えば'appName' => 'MyWebApp'のように、設定のキーと値が直接対応する連想配列としてデータを受け取ることができ、プログラム内で特定のキーに対応する値を簡単に参照できるため、設定情報の管理や簡易的なマッピング処理などに非常に役立ちます。

PDO::FETCH_KEY_PAIRは、SELECT文で指定した最初のカラムを連想配列のキー、2番目のカラムを値として取得します。このため、カラムの指定順序が非常に重要です。3番目以降のカラムは結果に反映されません。キーとなるカラムに重複する値が存在する場合、後から取得された値が前の値を上書きしますのでご注意ください。また、データベースへの接続や操作では、例外モード（PDO::ERRMODE_EXCEPTION）を設定し、try-catchブロックでエラーを適切に処理することが安全なコードの基本です。ユーザーからの入力など動的な値をSQLに含める際は、セキュリティのために必ずプリペアドステートメントを利用してください。