【PHP8.x】SQLite3::createCollation()メソッドの使い方

Copy
1<?php
2
3/**
4 * SQLite3 データベースにカスタム照合順序を作成し、使用するサンプル。
5 *
6 * createCollation メソッドは、SQL の ORDER BY 句などで使用できる
7 * 独自の文字列比較ルール（照合順序）を定義するために使用されます。
8 */
9
10// データベースファイル名
11$dbFile = 'my_database.db';
12
13// データベースファイルを事前に削除し、クリーンな状態にする (開発時のみ推奨)
14if (file_exists($dbFile)) {
15    unlink($dbFile);
16}
17
18// データベースに接続
19$db = new SQLite3($dbFile);
20
21// 接続エラーチェック
22if (!$db) {
23    die("データベース接続エラー: " . $db->lastErrorMsg());
24}
25
26echo "データベース '$dbFile' に接続しました。\n";
27
28/**
29 * カスタム照合順序のためのコールバック関数を定義します。
30 * この関数は2つの文字列を受け取り、比較結果を整数で返します。
31 *   - $str1 が $str2 より小さい場合、負の値を返す
32 *   - $str1 と $str2 が等しい場合、0 を返す
33 *   - $str1 が $str2 より大きい場合、正の値を返す
34 *
35 * この例では、標準の strcmp 関数を逆にする（逆順ソート）照合順序を作成します。
36 */
37$is_reverse_sort_enabled = false; // 特定の条件で逆順にするフラグ
38
39$myReverseCollationCallback = function (string $str1, string $str2): int {
40    global $is_reverse_sort_enabled; // グローバル変数を参照
41    if ($is_reverse_sort_enabled) {
42        // 大文字小文字を区別せず、逆順にソートする例
43        return strcasecmp($str2, $str1);
44    } else {
45        // 通常の順序（大文字小文字を区別しない）
46        return strcasecmp($str1, $str2);
47    }
48};
49
50// SQLite3 データベースにカスタム照合順序 'MY_REVERSE_COLLATION' を作成
51$collationName = 'MY_REVERSE_COLLATION';
52$success = $db->createCollation($collationName, $myReverseCollationCallback);
53
54if ($success) {
55    echo "カスタム照合順序 '$collationName' が正常に作成されました。\n";
56
57    // サンプルテーブルを作成
58    $db->exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');
59    echo "テーブル 'users' を作成しました。\n";
60
61    // サンプルデータを挿入
62    $db->exec("INSERT INTO users (name) VALUES ('Charlie')");
63    $db->exec("INSERT INTO users (name) VALUES ('Alice')");
64    $db->exec("INSERT INTO users (name) VALUES ('bob')"); // 小文字も含む
65    echo "サンプルデータを挿入しました。\n";
66
67    echo "\n--- 通常の ORDER BY （大文字小文字を区別しない）---\n";
68    $result = $db->query('SELECT name FROM users ORDER BY name COLLATE NOCASE');
69    while ($row = $result->fetchArray(SQLITE3_ASSOC)) {
70        echo "名前: " . $row['name'] . "\n";
71    }
72
73    // フラグをtrueに設定して、カスタム照合順序が逆順ソートとして機能するようにする
74    $is_reverse_sort_enabled = true;
75
76    echo "\n--- カスタム照合順序 '$collationName' を使用した ORDER BY ---\n";
77    $result = $db->query("SELECT name FROM users ORDER BY name COLLATE $collationName");
78    while ($row = $result->fetchArray(SQLITE3_ASSOC)) {
79        echo "名前: " . $row['name'] . "\n";
80    }
81
82} else {
83    echo "カスタム照合順序 '$collationName' の作成に失敗しました。\n";
84    echo "エラー: " . $db->lastErrorMsg() . "\n";
85}
86
87// データベース接続を閉じる
88$db->close();
89echo "\nデータベース接続を閉じました。\n";
90
91// データベースファイルを削除する (オプション: クリーンアップ)
92if (file_exists($dbFile)) {
93    unlink($dbFile);
94    echo "データベースファイル '$dbFile' を削除しました。\n";
95}
96
97?>

SQLite3::createCollationメソッドは、PHP 8でSQLite3データベースに独自の文字列比較ルール、いわゆる「照合順序」を定義するために使用されます。これにより、SQLのORDER BY句などで、標準とは異なる順序でデータを並べ替えたい場合に柔軟な制御が可能になります。

このメソッドは2つの引数を取ります。最初の引数$nameは、データベース内で作成するカスタム照合順序を識別するための名前（文字列）です。SQLクエリでこの名前を使って独自のソートルールを指定します。2番目の引数$callbackは、実際に2つの文字列を比較するロジックを実装したコールバック関数を指定します。このコールバック関数は、比較対象の2つの文字列を受け取り、最初の文字列が2番目の文字列より小さい場合は負の数、等しい場合は0、大きい場合は正の数を返します。

メソッドの戻り値はbool型で、カスタム照合順序の作成が成功した場合はtrue、失敗した場合はfalseが返されます。サンプルコードでは、MY_REVERSE_COLLATIONという名前で、文字列を逆順にソートするカスタムルールを定義しています。この照合順序をデータベースに登録後、SELECT name FROM users ORDER BY name COLLATE MY_REVERSE_COLLATIONのようにSQLクエリ内で利用することで、定義した比較ルールに基づいてデータを並べ替えることができます。これにより、データベースのソート処理をアプリケーションの要件に合わせて詳細にカスタマイズすることが可能です。

Copy
1<?php
2
3/**
4 * SQLite3::createCollation メソッドを使用して、カスタムの文字列比較順序を定義するサンプルです。
5 *
6 * この機能は、データベース内の文字列の「コレクション」（例: 複数の名前や単語の集まり）を
7 * 標準的なアルファベット順ではなく、特定のルール（この例では文字列の長さ）に基づいて
8 * ソートしたい場合に非常に役立ちます。
9 * PHPの配列を usort でカスタムソートするのと同様に、SQLiteデータベースのデータを
10 * ユーザー定義のルールでソートできるようになります。
11 */
12
13// 1. インメモリデータベースを開きます。
14//    これにより、ファイルを作成せずに一時的にデータベースを使用でき、単体で動作します。
15$db = new SQLite3(':memory:');
16if (!$db) {
17    die("データベース接続に失敗しました。\n");
18}
19
20echo "データベース接続に成功しました。\n";
21
22// 2. カスタム照合順序（Collation）を登録します。
23//    この例では、文字列の「長さ」に基づいて比較する照合順序 'length_collation' を定義します。
24//
25//    - 第1引数 ($name): 照合順序の名前。SQLで `COLLATE` キーワードと共に使用します。
26//    - 第2引数 ($callback): 2つの文字列を比較し、結果を整数で返すコールバック関数。
27//      - str1 < str2 の場合: 負の整数を返す
28//      - str1 == str2 の場合: 0 を返す
29//      - str1 > str2 の場合: 正の整数を返す
30$success = $db->createCollation('length_collation', function (string $str1, string $str2): int {
31    $len1 = mb_strlen($str1); // マルチバイト文字を考慮した文字列長を取得
32    $len2 = mb_strlen($str2);
33
34    if ($len1 === $len2) {
35        return 0; // 長さが同じなら、等しいとみなす
36    }
37
38    // 長さが短い方を「小さい」と判断する
39    return ($len1 < $len2) ? -1 : 1;
40});
41
42if (!$success) {
43    die("カスタム照合順序の登録に失敗しました。\n");
44}
45
46echo "カスタム照合順序 'length_collation' を登録しました。\n";
47
48// 3. サンプルデータ用のテーブルを作成します。
49$db->exec('CREATE TABLE IF NOT EXISTS words (
50    id INTEGER PRIMARY KEY AUTOINCREMENT,
51    text TEXT NOT NULL
52)');
53
54// 4. テーブルにデータを挿入します。異なる長さの文字列を混ぜて挿入します。
55$wordCollection = ['apple', 'banana', 'kiwi', 'grape', 'orange', 'pear'];
56foreach ($wordCollection as $word) {
57    $db->exec("INSERT INTO words (text) VALUES ('" . $db->escapeString($word) . "')");
58}
59
60echo "サンプルデータを挿入しました。\n";
61
62// 5. デフォルトの照合順序（アルファベット順）でデータを取得し、表示します。
63echo "\n--- デフォルトのソート順 (アルファベット順) ---\n";
64$result = $db->query('SELECT text FROM words ORDER BY text');
65while ($row = $result->fetchArray(SQLITE3_ASSOC)) {
66    echo $row['text'] . "\n";
67}
68// 期待される出力例: apple, banana, grape, kiwi, orange, pear
69
70// 6. カスタム照合順序 'length_collation' を使用してデータを取得し、表示します。
71//    これにより、文字列の「長さ」に基づいてデータがソートされます。
72echo "\n--- カスタム照合順序 'length_collation' でのソート順 (文字列の長さ順) ---\n";
73$result = $db->query('SELECT text FROM words ORDER BY text COLLATE length_collation');
74while ($row = $result->fetchArray(SQLITE3_ASSOC)) {
75    echo $row['text'] . "\n";
76}
77// 期待される出力例 (長さ順): pear (4), kiwi (4), apple (5), grape (5), orange (6), banana (6)
78// 同じ長さの文字列の場合、SQLiteのデフォルトの二次的なソート順が適用されます。
79
80// 7. データベース接続を閉じます。
81$db->close();
82echo "\nデータベース接続を閉じました。\n";
83
84?>

SQLite3::createCollationメソッドは、SQLiteデータベース内で文字列の比較順序を独自に定義するために使用します。これにより、標準的なアルファベット順ではなく、ユーザーが指定したルールに基づいてデータベース内の文字列データ（コレクション）をソートできるようになります。例えば、文字列の長さや特定の文字の出現頻度など、複雑な条件でデータを並べ替えたい場合に非常に有効です。

このメソッドは二つの引数を受け取ります。一つ目の$nameは、定義するカスタム照合順序の名前を文字列で指定します。この名前はSQLクエリのCOLLATE句で使用します。二つ目の$callbackは、二つの文字列を受け取り、その比較結果を整数で返すコールバック関数です。この関数内で、文字列の比較ロジックを実装します。具体的には、最初の文字列が二番目より小さい場合は負の整数、等しい場合はゼロ、大きい場合は正の整数を返すように定義します。

戻り値はbool型で、カスタム照合順序の登録が成功した場合はtrue、失敗した場合はfalseを返します。

このサンプルコードでは、length_collationという名前で、文字列の長さに基づいて比較を行うカスタム照合順序を登録しています。mb_strlen関数を使ってマルチバイト文字も考慮した文字列長で比較し、その順序でデータをソートするSQLクエリの実行結果を示しています。これにより、デフォルトのアルファベット順とは異なる、長さ順でのデータ表示が実現できます。