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

Copy
1<?php
2
3/**
4 * SQLiteデータベースからBLOBデータを読み込み、HTTP経由でファイルをダウンロードさせる関数。
5 * システムエンジニアを目指す初心者向けに、SQLite3::openBlobメソッドの使用例を示します。
6 *
7 * @param string $dbPath データベースファイルのパス (例: ':memory:' または 'path/to/database.db')
8 * @param string $table BLOBデータが格納されているテーブル名
9 * @param string $column BLOBデータが格納されているカラム名
10 * @param int $rowid 取得したいBLOBデータのある行のrowid（またはINTEGER PRIMARY KEYの値）
11 * @param string $filename ダウンロード時にクライアントに提示するファイル名
12 * @param string $contentType ダウンロードするファイルのMIMEタイプ (例: 'image/jpeg', 'application/pdf')
13 * @return bool ファイルのダウンロードが正常に開始された場合はtrue、失敗した場合はfalseを返す。
14 */
15function downloadBlobFile(string $dbPath, string $table, string $column, int $rowid, string $filename, string $contentType): bool
16{
17    // 1. SQLite3 データベースに接続
18    // データベースファイルが存在しない場合は作成されます。
19    $db = new SQLite3($dbPath);
20    if (!$db) {
21        error_log("データベース接続エラー: " . $db->lastErrorMsg());
22        return false;
23    }
24
25    // 2. BLOBデータのサイズを取得
26    // Content-Length HTTPヘッダーを設定するために必要です。
27    $stmt = $db->prepare("SELECT LENGTH({$column}) FROM {$table} WHERE rowid = :rowid");
28    if (!$stmt) {
29        error_log("SQL準備エラー: " . $db->lastErrorMsg());
30        $db->close();
31        return false;
32    }
33    $stmt->bindValue(':rowid', $rowid, SQLITE3_INTEGER);
34    $result = $stmt->execute();
35    $length = $result ? ($result->fetchArray(SQLITE3_NUM)[0] ?? 0) : 0;
36    if ($result) {
37        $result->finalize();
38    }
39    $stmt->close();
40
41    if ($length === 0) {
42        error_log("指定されたBLOBデータが見つからないか、空です。(Table: $table, Column: $column, RowID: $rowid)");
43        $db->close();
44        return false;
45    }
46
47    // 3. SQLite3::openBlob() を使用してBLOBデータをストリームとして開く
48    // このメソッドは、データベースからBLOBデータを直接読み取るためのストリームリソースを返します。
49    // 第5引数はデフォルトで SQLITE3_OPEN_READONLY なので、読み取り専用の場合は省略可能です。
50    $blobStream = $db->openBlob($table, $column, $rowid);
51    if (!$blobStream) {
52        error_log("BLOBストリームのオープンエラー: " . $db->lastErrorMsg() . "(Table: $table, Column: $column, RowID: $rowid)");
53        $db->close();
54        return false;
55    }
56
57    // ヘッダーが既に送信されているか確認。
58    // headers_sent() は、既に何らかの出力があったためにヘッダーが送信済みかどうかをチェックします。
59    // 送信済みの場合、header() 関数はエラーを発生させます。
60    if (headers_sent($file, $line)) {
61        error_log("エラー: HTTPヘッダーが既に送信されています。(File: $file, Line: $line)");
62        // ブラウザへの直接出力は避けるべきですが、サンプルコードのため簡略化
63        echo "エラー: ファイルダウンロードヘッダーを送信できませんでした。";
64        $blobStream->close();
65        $db->close();
66        return false;
67    }
68
69    // 4. HTTPヘッダーを設定
70    // これらのヘッダーは、ブラウザにファイルをダウンロードさせ、
71    // ダウンロード時のファイル名とファイルの種類を指示します。
72    header('Content-Type: ' . $contentType); // ファイルのMIMEタイプを設定
73    header('Content-Disposition: attachment; filename="' . basename($filename) . '"'); // ダウンロードファイル名を設定
74    header('Content-Length: ' . $length); // ファイルサイズを設定
75
76    // キャッシュを無効化するヘッダー（ダウンロードの確実性を高めるため）
77    header('Cache-Control: no-cache, no-store, must-revalidate');
78    header('Pragma: no-cache');
79    header('Expires: 0');
80
81    // 5. BLOBストリームの内容を直接HTTPレスポンスに出力
82    // php://output は、現在のスクリプトの出力バッファ（通常はHTTPレスポンスボディ）への書き込みストリームです。
83    $outputStream = fopen('php://output', 'wb');
84    if ($outputStream === false) {
85        error_log("出力ストリームのオープンエラー。");
86        $blobStream->close();
87        $db->close();
88        return false;
89    }
90
91    // stream_copy_to_stream() は、片方のストリームからもう片方のストリームへ、
92    // 効率的にデータをコピーします。これにより、大きなBLOBデータでも
93    // 全てをメモリに読み込むことなく処理できます。
94    stream_copy_to_stream($blobStream, $outputStream);
95
96    // 6. ストリームとデータベース接続を閉じる
97    // リソースを解放することは重要です。
98    fclose($outputStream);
99    $blobStream->close();
100    $db->close();
101
102    return true;
103}
104
105// --- サンプルコードの実行部分 ---
106// このスクリプトはウェブサーバー上で実行されることを想定しています。
107// ウェブブラウザでこのPHPファイルにアクセスすると、ファイルがダウンロードされます。
108
109// エラー表示設定 (開発中のみ有効にしてください。本番環境では '0' に設定するか、ログにのみ出力してください)
110error_reporting(E_ALL);
111ini_set('display_errors', '1');
112
113// データベースファイルのパス (今回は一時的なインメモリデータベースを使用)
114// 実際のアプリケーションでは、永続的なファイルパス (例: './data/mydatabase.db') を指定します。
115$dbPath = ':memory:';
116
117// ダウンロードするテストデータ (1x1ピクセルの透明GIF画像データ)
118$imageData = base64_decode('R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==');
119$imageName = 'sample_image.gif';
120$imageMimeType = 'image/gif';
121
122// データベースの初期化とテストデータの挿入
123// まず、データベースを開いてテーブルを作成し、BLOBデータを挿入します。
124$db = new SQLite3($dbPath);
125if (!$db) {
126    die("データベース接続エラー（初期化時）: " . $db->lastErrorMsg());
127}
128
129// 'downloads' テーブルを作成します。'file_data' カラムにBLOBデータを保存します。
130$db->exec('CREATE TABLE IF NOT EXISTS downloads (
131    id INTEGER PRIMARY KEY AUTOINCREMENT,
132    name TEXT,
133    mime_type TEXT,
134    file_data BLOB
135)');
136
137// BLOBデータをデータベースに挿入します。
138$stmt = $db->prepare('INSERT INTO downloads (name, mime_type, file_data) VALUES (:name, :mime_type, :file_data)');
139if (!$stmt) {
140    die("INSERT文準備エラー: " . $db->lastErrorMsg());
141}
142$stmt->bindValue(':name', $imageName, SQLITE3_TEXT);
143$stmt->bindValue(':mime_type', $imageMimeType, SQLITE3_TEXT);
144$stmt->bindValue(':file_data', $imageData, SQLITE3_BLOB); // BLOBデータをバインド
145$stmt->execute();
146$stmt->close();
147
148$insertedRowId = $db->lastInsertRowID(); // 挿入された行のrowid（またはid）を取得
149$db->close(); // データベース接続を一旦閉じます (downloadBlobFile関数内で再度開くため)
150
151
152// downloadBlobFile 関数を呼び出してファイルをダウンロードさせます。
153// ブラウザからこのスクリプトにアクセスすると、'downloaded_image.gif' という名前でファイルがダウンロードされます。
154if (downloadBlobFile($dbPath, 'downloads', 'file_data', $insertedRowId, 'downloaded_image.gif', 'image/gif')) {
155    // ダウンロードが開始された場合、スクリプトを終了します。
156    // これにより、余分な出力がブラウザに送られるのを防ぎます。
157    exit();
158} else {
159    // ダウンロード処理が失敗した場合の処理です。
160    // エラーメッセージは既に error_log() で出力されています。
161    if (!headers_sent()) {
162        header('Content-Type: text/plain');
163        echo "ファイルのダウンロード処理に失敗しました。詳細はサーバーのログを確認してください。";
164    } else {
165        echo "ファイルのダウンロード処理に失敗しました。ヘッダー送信後にエラーが発生した可能性があります。";
166    }
167}

PHP 8のSQLite3::openBlobメソッドは、SQLiteデータベースに格納されているBLOB（Binary Large OBject）データを、メモリ全体に読み込むことなく直接ストリームとして扱うための機能を提供します。これは、画像やPDFファイルのような大きなバイナリデータを効率的に処理する際に非常に有用です。

このメソッドは、$table（BLOBデータがあるテーブル名）、$column（BLOBデータがあるカラム名）、$rowid（取得したいデータの行ID）を引数として受け取ります。オプションでデータベース名やフラグも指定できますが、通常は読み取り専用のSQLITE3_OPEN_READONLYがデフォルトです。成功するとBLOBデータを読み書きするためのSQLite3Blobオブジェクトを返し、失敗するとfalseを返します。

提供されたサンプルコードは、このopenBlobメソッドを使ってSQLiteデータベースからBLOBデータを読み出し、それをHTTPレスポンスとしてクライアントにダウンロードさせる方法を示しています。まず、データベースに接続し、ダウンロードするBLOBデータのサイズを取得してContent-Lengthヘッダーを設定します。次に、openBlobでBLOBストリームを開き、適切なContent-TypeやContent-DispositionなどのHTTPヘッダーを設定します。最後に、stream_copy_to_stream関数を用いて、開いたBLOBストリームの内容を直接HTTP出力ストリームへ効率的にコピーすることで、大きなファイルでもメモリを圧迫せずにダウンロードを可能にしています。処理後は、開いたストリームやデータベース接続を適切に閉じることでリソースを解放します。

Copy
1<?php
2
3/**
4 * SQLite3::openBlob を使用して、指定されたファイルをSQLiteデータベースのBLOBカラムに保存します。
5 *
6 * この関数は、まず指定されたテーブルに空のBLOBデータを持つレコードを挿入し、そのrowidを取得します。
7 * 次に、取得したrowidとBLOBカラムに対して書き込みモード (SQLITE3_OPEN_READWRITE) で openBlob を呼び出し、
8 * 指定されたローカルファイルの内容をBLOBとしてデータベースに書き込みます。
9 *
10 * @param string $dbPath SQLiteデータベースファイルのパス。
11 * @param string $tableName BLOBを保存するテーブル名。
12 * @param string $columnName BLOBを保存するカラム名。
13 * @param string $filePath アップロードするローカルファイルのパス。
14 * @param string $targetFilename データベースに保存するファイル名 (例: 'my_image.png')。
15 * @return bool 処理が成功した場合は true、失敗した場合は false。
16 */
17function uploadFileAsBlobToSQLite(
18    string $dbPath,
19    string $tableName,
20    string $columnName,
21    string $filePath,
22    string $targetFilename
23): bool {
24    // 1. アップロード元ファイルの存在確認
25    if (!file_exists($filePath)) {
26        echo "エラー: 指定されたファイルが存在しません: " . $filePath . PHP_EOL;
27        return false;
28    }
29
30    try {
31        // 2. SQLiteデータベースに接続
32        $db = new SQLite3($dbPath);
33        // エラー発生時に例外をスローするように設定し、エラーハンドリングを簡素化します。
34        $db->enableExceptions(true); 
35
36        // 3. BLOBを保存するテーブルが存在しない場合は作成します。
37        // idはPRIMARY KEYとして、BLOBの更新に必要なrowidとして機能します。
38        $db->exec("CREATE TABLE IF NOT EXISTS $tableName (
39            id INTEGER PRIMARY KEY AUTOINCREMENT,
40            filename TEXT NOT NULL,
41            $columnName BLOB
42        )");
43
44        // 4. アップロードするファイルのコンテンツを全て読み込みます。
45        $fileContent = file_get_contents($filePath);
46        if ($fileContent === false) {
47            echo "エラー: ファイルの読み込みに失敗しました: " . $filePath . PHP_EOL;
48            return false;
49        }
50
51        // 5. まず空のBLOBデータを持つレコードを挿入し、そのrowidを取得します。
52        // SQLite3::openBlob は既存のrowidに対してBLOBを開くため、事前にレコードが存在する必要があります。
53        $stmt = $db->prepare("INSERT INTO $tableName (filename, $columnName) VALUES (:filename, :data)");
54        $stmt->bindValue(':filename', $targetFilename, SQLITE3_TEXT);
55        $stmt->bindValue(':data', null, SQLITE3_BLOB); // まずはNULLまたは空のBLOBで挿入
56        $stmt->execute();
57        $rowid = $db->lastInsertRowID(); // 新しく挿入されたレコードのrowidを取得
58
59        if (!$rowid) {
60            echo "エラー: レコードの挿入に失敗しました。" . PHP_EOL;
61            return false;
62        }
63
64        // 6. BLOBを書き込みモード (SQLITE3_OPEN_READWRITE) で開きます。
65        // これにより、SQLite3Blob オブジェクトを通じてBLOBデータを更新できるようになります。
66        $blob = $db->openBlob($tableName, $columnName, $rowid, 'main', SQLITE3_OPEN_READWRITE);
67
68        if ($blob === false) {
69            echo "エラー: BLOBのオープンに失敗しました。テーブル: $tableName, カラム: $columnName, rowid: $rowid" . PHP_EOL;
70            return false;
71        }
72
73        // 7. 読み込んだファイルの内容をオープンしたBLOBに書き込みます。
74        $bytesWritten = $blob->write($fileContent);
75
76        // SQLite3Blob オブジェクトは、参照がなくなると自動的にクローズされます。
77        // そのため、明示的な $blob->close() は不要です。
78
79        if ($bytesWritten === false || $bytesWritten !== strlen($fileContent)) {
80            echo "エラー: BLOBへの書き込み中にエラーが発生しました。書き込まれたバイト数: " . ($bytesWritten ?: 0) . ", 期待されるバイト数: " . strlen($fileContent) . PHP_EOL;
81            return false;
82        }
83
84        echo "BLOBが正常にデータベースに保存されました。rowid: $rowid, ファイル名: $targetFilename, サイズ: " . strlen($fileContent) . " バイト" . PHP_EOL;
85
86        return true;
87
88    } catch (Exception $e) {
89        // データベース操作中に例外が発生した場合
90        echo "例外が発生しました: " . $e->getMessage() . PHP_EOL;
91        return false;
92    } finally {
93        // データベース接続が開いている場合は必ず閉じます。
94        if (isset($db)) {
95            $db->close();
96        }
97    }
98}
99
100// --- サンプルコードの実行 ---
101
102// データベースファイル名
103$dbFile = 'my_blobs.db';
104// アップロード対象のダミーファイル名
105$sampleImageFile = 'sample_image.png';
106$sampleTextFile = 'sample_document.txt';
107
108// テスト用のダミーファイルを作成 (もし存在しない場合)
109if (!file_exists($sampleImageFile)) {
110    // 1x1ピクセルの透過PNG画像データ (Base64エンコード)
111    $imageData = base64_decode('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=');
112    file_put_contents($sampleImageFile, $imageData);
113    echo "ダミー画像ファイル '{$sampleImageFile}' を作成しました。" . PHP_EOL;
114}
115if (!file_exists($sampleTextFile)) {
116    file_put_contents($sampleTextFile, "これはSQLite BLOBとして保存されるテキストの例です。\nPHPのopenBlobメソッドの動作確認を行います。");
117    echo "ダミーテキストファイル '{$sampleTextFile}' を作成しました。" . PHP_EOL;
118}
119
120// 既存のデータベースファイルを削除して、クリーンな状態からテストを開始します。
121if (file_exists($dbFile)) {
122    unlink($dbFile);
123    echo "既存のデータベースファイル '{$dbFile}' を削除しました。" . PHP_EOL;
124}
125
126// 画像ファイルのBLOB保存テスト
127echo PHP_EOL . "--- 画像ファイルのBLOB保存テスト ---" . PHP_EOL;
128$successImage = uploadFileAsBlobToSQLite($dbFile, 'files', 'data_blob', $sampleImageFile, 'uploaded_photo.png');
129echo "画像BLOB保存結果: " . ($successImage ? '成功' : '失敗') . PHP_EOL . PHP_EOL;
130
131// テキストファイルのBLOB保存テスト
132echo PHP_EOL . "--- テキストファイルのBLOB保存テスト ---" . PHP_EOL;
133$successText = uploadFileAsBlobToSQLite($dbFile, 'documents', 'content_blob', $sampleTextFile, 'uploaded_report.txt');
134echo "テキストBLOB保存結果: " . ($successText ? '成功' : '失敗') . PHP_EOL . PHP_EOL;
135
136// 後処理: テスト用に作成したダミーファイルを削除します。
137if (file_exists($sampleImageFile)) {
138    unlink($sampleImageFile);
139}
140if (file_exists($sampleTextFile)) {
141    unlink($sampleTextFile);
142}
143
144// データベースファイルは確認のために残しておくことができます。
145// 必要に応じて最後に `unlink($dbFile);` で削除することも可能です。

このサンプルコードは、PHPのSQLite3::openBlobメソッドを利用して、ローカルファイルをSQLiteデータベースのBLOB（Binary Large Object）カラムに保存する方法を解説しています。BLOBは、画像や文書ファイルなどの大きなバイナリデータをデータベース内に直接格納するために使用されるデータ型です。

SQLite3::openBlobメソッドは、指定されたテーブル、カラム、および既存のレコードのrowid（行ID）に対応するBLOBを開き、そのBLOBデータに対する操作を可能にするSQLite3Blobオブジェクトを返します。引数$table、$column、$rowidは、データベース内でBLOBを一意に特定するために必須です。また、$flags引数にSQLITE3_OPEN_READWRITEを指定することで、開いたBLOBへの書き込みが可能となります。このメソッドが失敗した場合、falseが返されます。

サンプルコードでは、まず保存対象のファイルを読み込みます。openBlobメソッドは既存のBLOBに対して機能するため、事前に空のBLOBデータを持つレコードをデータベースに挿入し、そのrowidを取得する手順を踏んでいます。その後、取得したrowidとBLOBカラム名を用いてopenBlobを書き込みモードで呼び出し、返されたSQLite3Blobオブジェクトのwriteメソッドを使ってファイルの内容をデータベースに効率的に書き込んでいます。この方法により、ファイルを一度にすべてメモリに読み込むことなく、BLOBデータをストリームとして扱えるため、大きなファイルでも処理が可能です。データベース操作中に発生しうる例外に対するエラーハンドリングや、データベース接続の確実なクローズも適切に実装されています。