【PHP8.x】querySingleメソッドの使い方

Copy
1<?php
2
3/**
4 * SQLite3::querySingle メソッドのサンプルコード
5 *
6 * このスクリプトは、SQLite3 データベースに接続し、テーブルを作成・データを挿入後、
7 * querySingle メソッドを使用して単一の値や単一行全体を取得する方法を示します。
8 * システムエンジニアを目指す初心者の方にも分かりやすいように、コメントを最小限に抑え、
9 * 直接実行可能な形式で記述されています。
10 */
11
12// データベースファイル名
13$dbFileName = 'my_sample_database.db';
14
15// 1. SQLite3 データベースに接続
16// データベースファイルが存在しない場合は新規作成されます。
17try {
18    $db = new SQLite3($dbFileName);
19} catch (Exception $e) {
20    die("データベース接続エラー: " . $e->getMessage());
21}
22
23echo "データベース '{$dbFileName}' に接続しました。" . PHP_EOL . PHP_EOL;
24
25// 2. テーブルを作成する (もし存在しない場合)
26// `IF NOT EXISTS` を使用することで、スクリプトを複数回実行してもエラーになりません。
27$db->exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)');
28echo "テーブル 'users' が存在しない場合は作成しました。" . PHP_EOL;
29
30// 3. データを挿入する (初回実行時のみ、またはデータがない場合)
31// `INSERT OR IGNORE` を使用することで、同じ ID のデータが重複して挿入されるのを防ぎます。
32$db->exec('INSERT OR IGNORE INTO users (id, name, age) VALUES (1, "Alice", 30)');
33$db->exec('INSERT OR IGNORE INTO users (id, name, age) VALUES (2, "Bob", 25)');
34$db->exec('INSERT OR IGNORE INTO users (id, name, age) VALUES (3, "Charlie", 35)');
35echo "サンプルデータを挿入しました (既存の場合はスキップ)。" . PHP_EOL . PHP_EOL;
36
37echo "--- SQLite3::querySingle の使用例 ---" . PHP_EOL . PHP_EOL;
38
39// 4. querySingle を使用して単一の値を返却する (第2引数 $entireRow はデフォルトで false)
40// 結果の最初の行の最初のカラムの値が返されます。
41$countQuery = 'SELECT COUNT(*) FROM users';
42$userCount = $db->querySingle($countQuery);
43echo "総ユーザー数: " . $userCount . PHP_EOL;
44
45$nameQuery = 'SELECT name FROM users WHERE id = 1';
46$userName = $db->querySingle($nameQuery);
47echo "ID 1 のユーザー名: " . ($userName ?? '見つかりませんでした') . PHP_EOL; // NULL の場合は文字列で表示
48
49$nonExistentNameQuery = 'SELECT name FROM users WHERE id = 99';
50$nonExistentUserName = $db->querySingle($nonExistentNameQuery);
51echo "ID 99 のユーザー名: " . ($nonExistentUserName ?? '見つかりませんでした') . PHP_EOL;
52
53echo PHP_EOL;
54
55// 5. querySingle の第2引数 $entireRow を true にして単一行全体を連想配列で取得
56// 結果の最初の行全体が連想配列として返されます。
57$entireRowQuery = 'SELECT name, age FROM users WHERE id = 2';
58$userInfo = $db->querySingle($entireRowQuery, true);
59
60if ($userInfo !== null) {
61    echo "ID 2 のユーザー情報 (連想配列):" . PHP_EOL;
62    echo "  名前: " . $userInfo['name'] . PHP_EOL;
63    echo "  年齢: " . $userInfo['age'] . PHP_EOL;
64} else {
65    echo "ID 2 のユーザー情報が見つかりませんでした。" . PHP_EOL;
66}
67
68// 存在しない ID の場合 ($entireRow が true でも NULL が返される)
69$nonExistentUserInfo = $db->querySingle('SELECT name, age FROM users WHERE id = 100', true);
70if ($nonExistentUserInfo === null) {
71    echo "ID 100 のユーザー情報 (entireRow=true) は見つかりませんでした (NULLが返ります)。" . PHP_EOL;
72}
73
74echo PHP_EOL;
75
76// 6. データベース接続を閉じる
77$db->close();
78echo "データベース接続を閉じました。" . PHP_EOL;
79
80// 注意: このスクリプトは `my_sample_database.db` というファイルを生成します。
81// 必要に応じて手動で削除してください。
82
83?>

PHPのSQLite3::querySingleメソッドは、SQLiteデータベースに対してSQLクエリを実行し、その結果から単一の値や単一行全体を効率的に取得するために使用されます。

最初の引数string $queryには、データベースで実行したいSQLクエリ文字列を指定します。このクエリは通常、単一のセルまたは単一行の結果を想定します。

二つ目の引数bool $entireRowはオプションで、デフォルトはfalseです。falseの場合、クエリ結果の最初の行の最初のカラムの値のみが返されます。例えば、COUNT(*)の結果や特定の名前だけを取得する際に適しています。trueを指定すると、クエリ結果の最初の行全体が、カラム名をキーとする連想配列として返されます。これにより、複数のカラムから成る単一行のデータを一度に取得できます。

戻り値はmixed型です。クエリが成功し、結果が存在する場合は、$entireRowがfalseならその値の型に応じたスカラー値（整数、文字列など）、$entireRowがtrueなら連想配列が返されます。クエリが結果を返さない場合やエラーが発生した場合は、NULLが返されます。このメソッドは、取得する情報が単一のデータや単一行に限定される場合に非常に役立ち、シンプルなデータ取得処理に適しています。

Copy
1<?php
2
3/**
4 * PHP 8 の SQLite3::querySingle メソッドの利用例を示します。
5 * SQLite データベースの作成、テーブル作成、データ挿入、
6 * そして querySingle を使ったデータの取得方法を初心者向けに解説します。
7 */
8function runQuerySingleExample(): void
9{
10    // データベースファイルのパスを定義
11    // このファイルはスクリプト実行時に作成され、終了時に削除されます。
12    $dbFile = 'my_database.db';
13
14    // 既存のデータベースファイルがあれば削除し、常にクリーンな状態から始める
15    if (file_exists($dbFile)) {
16        unlink($dbFile);
17    }
18
19    $sqlite = null; // SQLite3 オブジェクトの初期化
20
21    try {
22        // 1. SQLite3 データベースに接続（ファイルが存在しない場合は新規作成）
23        // データベースファイルが存在しない場合は自動的に作成されます。
24        // ファイルへの書き込み権限がスクリプトにあることを確認してください。
25        $sqlite = new SQLite3($dbFile);
26        echo "データベースファイル '{$dbFile}' に接続しました。" . PHP_EOL;
27
28        // 2. テーブルを作成する
29        // `id`は自動増分するプライマリキー、`name`は文字列、`age`は整数型です。
30        // `IF NOT EXISTS` を使用することで、テーブルが既に存在する場合は作成されません。
31        $sqlite->exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, age INTEGER)');
32        echo "テーブル 'users' を作成しました。" . PHP_EOL;
33
34        // 3. データを挿入する
35        // いくつかのサンプルユーザーデータをテーブルに追加します。
36        $sqlite->exec("INSERT INTO users (name, age) VALUES ('Alice', 30)");
37        $sqlite->exec("INSERT INTO users (name, age) VALUES ('Bob', 25)");
38        $sqlite->exec("INSERT INTO users (name, age) VALUES ('Charlie', 35)");
39        echo "3件のユーザーデータを挿入しました。" . PHP_EOL;
40
41        echo PHP_EOL . "--- SQLite3::querySingle の使用例 ---" . PHP_EOL;
42
43        // 4. querySingle を使用して、単一の値（最初の行の最初のカラム）を取得する
44        // 第2引数 `$entireRow` を省略（または `false` を指定）した場合の動作です。
45        // 結果セットの最初の行の最初のカラムの値が返されます。
46        $userName = $sqlite->querySingle("SELECT name FROM users WHERE id = 1");
47        echo "ID 1 のユーザー名: " . ($userName ?: '見つかりません') . PHP_EOL;
48
49        // 5. querySingle で集計関数の結果を取得する
50        // COUNT(*) のような集計関数の結果も単一の値として取得できます。
51        $totalUsers = $sqlite->querySingle("SELECT COUNT(*) FROM users");
52        echo "登録されているユーザー総数: " . ($totalUsers ?: 0) . PHP_EOL;
53
54        // 6. querySingle を使用して、行全体を連想配列として取得する
55        // 第2引数 `$entireRow` を `true` に設定します。
56        // 結果が見つかった場合、カラム名をキーとする連想配列が返されます。
57        // 結果が見つからない場合は `null` を返します。
58        $bobDetails = $sqlite->querySingle("SELECT id, name, age FROM users WHERE name = 'Bob'", true);
59        if ($bobDetails) {
60            echo "Bob の詳細情報 (連想配列):" . PHP_EOL;
61            echo "  ID: " . $bobDetails['id'] . PHP_EOL;
62            echo "  名前: " . $bobDetails['name'] . PHP_EOL;
63            echo "  年齢: " . $bobDetails['age'] . PHP_EOL;
64        } else {
65            echo "Bob の情報は見つかりませんでした。" . PHP_EOL;
66        }
67
68        // 7. 存在しないデータを検索した場合の動作
69        // クエリ結果が存在しない場合、querySingle は `null` を返します。
70        $nonExistentUserAge = $sqlite->querySingle("SELECT age FROM users WHERE name = 'David'");
71        if ($nonExistentUserAge === null) {
72            echo "David の年齢はデータベースに見つかりませんでした (querySingle は null を返しました)。" . PHP_EOL;
73        }
74
75    } catch (Exception $e) {
76        // データベース接続や操作中にエラーが発生した場合のハンドリング
77        // 初心者向けに簡略化していますが、実際のシステムではより詳細なログ記録などが必要です。
78        echo "エラーが発生しました: " . $e->getMessage() . PHP_EOL;
79    } finally {
80        // 8. データベース接続を閉じる
81        // データベースオブジェクトが存在し、SQLite3のインスタンスである場合に閉じます。
82        if ($sqlite instanceof SQLite3) {
83            $sqlite->close();
84            echo "データベース接続を閉じました。" . PHP_EOL;
85        }
86        // 9. 使用したデータベースファイルを削除してクリーンアップ
87        // サンプルコードのため、実行後にファイルを削除します。
88        if (file_exists($dbFile)) {
89            unlink($dbFile);
90            echo "データベースファイル '{$dbFile}' を削除しました。" . PHP_EOL;
91        }
92    }
93}
94
95// 関数を実行してサンプルコードの動作を確認
96runQuerySingleExample();

PHPのSQLite3::querySingleメソッドは、SQLiteデータベースから「単一の」データや行を効率的に取得するための機能です。このメソッドは、膨大なデータの中から必要な特定の情報だけを手早く取り出したい場合に非常に役立ちます。

第一引数 $query には実行したいSQL文を文字列で指定します。例えば、特定のユーザーの名前や商品の価格だけを知りたい場合などです。第二引数 $entireRow は省略可能で、デフォルトでは false が設定されています。この場合、クエリ結果の「最初の行の最初のカラム」の値だけが返されます。もし $entireRow を true に設定すると、結果の「最初の行全体」がカラム名をキーとする連想配列として返されるため、複数の関連するカラム（例：ID、名前、年齢など）を一括で取得できます。該当するデータが見つからない場合は null を返しますので、結果がnullでないかを必ず確認してください。COUNT(*)のような集計関数の結果も、このメソッドで単一の値として簡単に取得できます。

提供されたサンプルコードでは、まず一時的なSQLiteデータベースを作成し、usersテーブルにデータを挿入しています。その後、querySingleを使って、ID 1のユーザー名、登録ユーザーの総数、そして「Bob」という名前のユーザーの詳細情報を連想配列として取得する具体的な例が示されています。また、存在しないユーザーを検索した場合に null が返される挙動も確認でき、エラーハンドリングやデータベースのクリーンアップまでの一連の流れを学べます。このメソッドを理解することで、データベースからの特定情報の取得がスムーズに行えるようになります。