【PHP8.x】gzpassthru()関数の使い方

Copy
1<?php
2
3/**
4 * gzpassthru関数の基本的な使用方法を示すサンプルコードです。
5 * gzopenで開いたgzip圧縮ファイルの内容を、非圧縮状態で直接出力します。
6 *
7 * システムエンジニアを目指す初心者向けに、以下の手順で動作を説明します。
8 * 1. テスト用のgzip圧縮ファイルを作成します。
9 * 2. gzopen関数で圧縮ファイルを読み込みモードで開きます。
10 * 3. gzpassthru関数を使用して、開いたファイルの内容を直接標準出力に出力します。
11 * 4. ファイルを閉じ、テストファイルを削除してクリーンアップします。
12 */
13function demonstrateGzPassthru(): void
14{
15    // 圧縮する元のデータとファイル名を定義
16    $filename = 'example.gz';
17    $original_data = "これはgzpassthru関数のテストデータです。\n";
18    $original_data .= "複数行のデータを含んでいます。\n";
19    $original_data .= "システムエンジニアを目指す初心者向けのサンプルコードです。";
20
21    echo "--- gzpassthru関数デモンストレーション ---" . PHP_EOL;
22
23    // 1. テスト用のgzファイルを作成する
24    // 'w9' は gzip 圧縮レベル9（最高圧縮）で書き込みモードを示します。
25    // gzopenは、通常のfopenと同様にファイルポインタ（リソース）を返します。
26    $gz_write_handle = gzopen($filename, 'w9');
27    if ($gz_write_handle === false) {
28        echo "エラー: gzファイル '$filename' を作成できませんでした。" . PHP_EOL;
29        exit(1); // 処理を終了
30    }
31    // gzwriteでデータをgzファイルに書き込みます。
32    gzwrite($gz_write_handle, $original_data);
33    // gzcloseでファイルポインタを閉じます。
34    gzclose($gz_write_handle);
35    echo "テストファイル '$filename' を作成しました。" . PHP_EOL;
36    echo "元のデータ:\n---" . PHP_EOL . $original_data . PHP_EOL . "---" . PHP_EOL;
37
38    echo PHP_EOL . "--- gzpassthruによる出力開始 ---" . PHP_EOL;
39
40    // 2. gzopen で gzファイルを読み込みモードで開く
41    // 'r' は読み込みモードを示します。
42    $gz_read_handle = gzopen($filename, 'r');
43    if ($gz_read_handle === false) {
44        echo "エラー: gzファイル '$filename' を開けませんでした。" . PHP_EOL;
45        // ファイル削除は後でまとめて行うため、ここではreturnで関数を終了
46        // 実際のアプリケーションでは、より適切なエラーハンドリングが必要です。
47        return;
48    }
49
50    // 3. gzpassthru を使用して、開いたgzファイルの内容を直接出力する
51    // gzpassthruは、gzopenで開かれた圧縮ファイルを展開しながら、
52    // その内容を直接出力バッファ（通常は標準出力）に読み込み、出力します。
53    // 戻り値は読み込まれたバイト数、または失敗時に false です。
54    $bytes_read = gzpassthru($gz_read_handle);
55
56    if ($bytes_read === false) {
57        echo PHP_EOL . "エラー: gzpassthru の実行に失敗しました。" . PHP_EOL;
58    } else {
59        echo PHP_EOL . "--- gzpassthruによる出力終了 (読み込んだバイト数: " . $bytes_read . ") ---" . PHP_EOL;
60    }
61
62    // 4. gzファイルを閉じる
63    gzclose($gz_read_handle);
64
65    // 5. テストファイルをクリーンアップする
66    if (file_exists($filename)) {
67        unlink($filename);
68        echo PHP_EOL . "テストファイル '$filename' を削除しました。" . PHP_EOL;
69    }
70}
71
72// 関数の実行
73demonstrateGzPassthru();

PHPのgzpassthru関数は、gzopen関数で開かれたgzip圧縮ファイルの内容を、非圧縮状態で直接出力するための関数です。この関数は、圧縮されたファイルを展開しながら、そのデータを効率的に標準出力へ送信したい場合に利用されます。

サンプルコードでは、まずテスト用のgzip圧縮ファイルを作成します。これはgzopenを書き込みモード（w9）で開き、gzwriteでデータを書き込んだ後、gzcloseで閉じます。次に、この圧縮ファイルをgzopenで読み込みモード（r）で開きます。gzpassthru関数は、このgzopenが返したファイルリソース（resource $stream）を引数として受け取ります。関数が実行されると、圧縮ファイルの内容を順次読み込み、展開しながら、その結果を直接出力バッファ（通常は標準出力）へ出力します。これにより、プログラム内で別途データを読み込んで表示する手間を省けます。処理が成功すると、読み込んだバイト数が整数値（int）として返され、失敗した場合はfalseが返されます。処理後は、必ずgzcloseでファイルリソースを閉じ、不要になったテストファイルはunlinkで削除してクリーンアップを行います。

Copy
1<?php
2
3/**
4 * gzpassthru 関数の使用例を示します。
5 * この関数は、gzip圧縮されたファイルの内容を直接標準出力に出力します。
6 * gzread をループで使う代わりに効率的に利用できます。
7 *
8 * システムエンジニアを目指す初心者の方へ:
9 * gzpassthru は、gzipファイルを読み込み、その内容を直接ユーザーの画面やコンソールに表示したい場合に便利です。
10 * 大量のデータを扱う場合でも、メモリにすべてを読み込まずにストリーム処理するため、効率的です。
11 */
12function runGzPassthruExample(): void
13{
14    // 1. テスト用のgzipファイルを作成する準備
15    // 一時ディレクトリにユニークなファイル名でgzipファイルを作成します。
16    $tempDir = sys_get_temp_dir();
17    $testFileName = $tempDir . DIRECTORY_SEPARATOR . 'test_gzpassthru_' . uniqid() . '.gz';
18    $originalContent = "これはテスト用のgzipファイルの中身です。\n複数行のテキストデータ。\n日本語も対応しています。\n";
19
20    // gzipファイルを書き込みモード ('wb') で開きます。
21    // 'w' は書き込み、'b' はバイナリモードを意味します。
22    $gzStreamWriter = gzopen($testFileName, 'wb');
23    if ($gzStreamWriter === false) {
24        echo "エラー: gzip ファイル '{$testFileName}' を書き込み用に開けませんでした。\n";
25        return;
26    }
27
28    // 内容をgzipファイルに書き込みます。
29    // gzwrite の戻り値は書き込まれたバイト数、または false (失敗) です。
30    if (gzwrite($gzStreamWriter, $originalContent) === false) {
31        echo "エラー: gzip ファイル '{$testFileName}' への書き込みに失敗しました。\n";
32        gzclose($gzStreamWriter); // エラーの場合も開いたストリームは閉じます。
33        return;
34    }
35    gzclose($gzStreamWriter); // 書き込みが完了したらストリームを閉じます。
36
37    echo "--- gzpassthru の実行結果 ---\n";
38    echo "作成されたgzipファイル: {$testFileName}\n";
39    echo "元の内容:\n";
40    echo $originalContent;
41    echo "---------------------------\n\n";
42
43    // 2. gzopen で gzip ファイルを読み込みモードで開く
44    // 'rb' モード (read binary) で開きます。
45    $gzStreamReader = gzopen($testFileName, 'rb');
46
47    if ($gzStreamReader === false) {
48        echo "エラー: gzip ファイル '{$testFileName}' を読み込み用に開けませんでした。\n";
49    } else {
50        echo "gzpassthru を使用して圧縮されたファイルの内容を出力します:\n";
51        // 3. gzpassthru でファイルの内容を直接標準出力に出力する
52        // これは、gzread をループで何度も呼び出してデータを少しずつ読み込み、
53        // その都度出力する処理を、この関数一つで置き換えることができます。
54        $bytesOutput = gzpassthru($gzStreamReader);
55
56        // gzpassthru の戻り値は、読み込んで出力したバイト数、または false (失敗) です。
57        if ($bytesOutput === false) {
58            echo "\nエラー: ファイルの読み込みまたは出力に失敗しました。\n";
59        } else {
60            echo "\n({$bytesOutput} バイト読み込み、出力しました。)\n";
61        }
62
63        // 4. gzclose でストリームを閉じる
64        // 開いたファイルストリームは必ず閉じるべきです。
65        gzclose($gzStreamReader);
66    }
67
68    // 5. 後処理: 作成した一時ファイルを削除する
69    // サンプルコードなので、作成したファイルをクリーンアップします。
70    if (file_exists($testFileName)) {
71        unlink($testFileName);
72        echo "一時ファイル '{$testFileName}' を削除しました。\n";
73    } else {
74        echo "警告: 一時ファイル '{$testFileName}' が見つかりませんでした (既に削除されたか)。\n";
75    }
76}
77
78// gzpassthru の使用例を実行します。
79runGzPassthruExample();
80
81?>

PHPのgzpassthru関数は、gzopen関数などで開かれたgzip圧縮ファイルストリームから、残りのデータを直接標準出力へ出力するために使用されます。引数には、読み込みモードで開かれたresource型のgzipファイルストリームを指定します。この関数は、gzreadをループで繰り返し呼び出して少しずつデータを読み込み、その都度出力するよりも効率的です。特に、大量の圧縮データを扱う際に、データを全てメモリに読み込むことなくストリームとして処理できるため、メモリ使用量を抑えられます。

処理が成功した場合、gzpassthruは出力されたバイト数を整数で返します。ファイルや出力処理に問題があった場合はfalseを返しますので、戻り値を確認してエラーハンドリングを行うことが重要です。サンプルコードでは、まずテスト用のgzipファイルを作成し、次にそれを読み込みモードで開きます。そして、gzpassthruを使ってその内容を直接コンソールに出力する一連の流れを示しています。ファイルストリームは処理後に必ずgzcloseで閉じる必要があります。