Webエンジニア向けプログラミング解説動画をYouTubeで配信中!
▶ チャンネル登録はこちら

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

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

作成日: 更新日:

基本的な使い方

gzseek関数は、gzip形式で圧縮されたファイルの読み書き位置(ファイルポインタ)を移動させる関数です。この関数は、gzopen()関数によって開かれたgzip圧縮ファイルリソースに対して使用され、ファイル内の特定の場所からデータを読み込んだり、書き込んだりする際に、現在の読み書き位置を変更する目的で利用されます。

この関数は主に三つの引数を取ります。最初の引数には、gzopen()で開かれたgzipファイルのリソースを指定します。二番目の引数には、ファイルポインタを移動させるバイト数を示すオフセット値を指定します。そして三番目の引数には、オフセットの基準となる位置を指定します。この基準は、ファイルの先頭を意味するSEEK_SET、現在のファイルポインタの位置を意味するSEEK_CUR、またはファイルの末尾を意味するSEEK_ENDのいずれかを選択できます。

正常にファイルポインタの移動が完了した場合、この関数はファイルの先頭から数えた新しいファイルポインタの位置を整数で返します。もしファイルポインタの移動に失敗した場合は、-1が返されます。これにより、圧縮された大きなファイルの中から必要な部分だけを効率的に検索したり、特定の場所にデータを書き込んだりすることが可能になります。

構文(syntax)

1gzseek(GdGzFile|resource $stream, int $offset, int $whence = SEEK_SET): int

引数(parameters)

resource $stream, int $offset, int $whence = SEEK_SET

  • resource $stream: 圧縮ストリームリソースを指定します
  • int $offset: 移動するバイト数を指定します
  • int $whence = SEEK_SET: 移動の基準位置を指定します

戻り値(return)

int

指定されたファイルポインタの位置への移動が成功した場合は 0 を、失敗した場合は -1 を返します。

サンプルコード

PHP gzseekとgzdecodeでファイル操作する

1<?php
2
3/**
4 * gzippedファイルのシークとデコードを実演する関数。
5 *
6 * この関数は、`gzseek` を使用してgzippedファイル内で位置を移動する方法と、
7 * `gzdecode` を使用してgzippedデータを文字列として展開する方法を示します。
8 * システムエンジニアを目指す初心者の方にも分かりやすいよう、
9 * ファイル作成、読み込み、シーク、デコード、クリーンアップの各ステップを
10 * 順番に実行し、それぞれの結果を出力します。
11 */
12function demonstrateGzseekAndGzdecode(): void
13{
14    // 一時的なgzippedファイルのファイル名を定義
15    $filename = 'example_gzseek_gzdecode.gz';
16
17    // gzippedファイルに書き込む元の(非圧縮)コンテンツ
18    $originalContent = "Hello, this is a test string for PHP gzseek and gzdecode demonstration.\n"
19                     . "This is the second line of text within the gzipped file.\n"
20                     . "Finally, here is the third and last line of content.";
21
22    // 1. gzencode を使用してコンテンツをgzip形式に圧縮
23    // gzencodeはRFC 1952に準拠したgzip形式のデータを作成し、gzdecodeと互換性があります。
24    // 9は最高の圧縮レベルを示します。
25    $gzippedContent = gzencode($originalContent, 9);
26
27    // 圧縮が成功したかを確認
28    if ($gzippedContent === false) {
29        echo "エラー: 元のコンテンツを圧縮できませんでした。\n";
30        return;
31    }
32
33    // 2. 圧縮されたコンテンツを一時ファイルに書き込み
34    if (file_put_contents($filename, $gzippedContent) === false) {
35        echo "エラー: gzippedコンテンツをファイル '{$filename}' に書き込めませんでした。\n";
36        return;
37    }
38    echo "gzippedファイル '{$filename}' を正常に作成しました。\n";
39
40    // 3. gzopen を使用してgzippedファイルストリームを開く
41    // 'rb'モードは、gzippedファイルに適したバイナリ読み込みモードです。
42    $stream = gzopen($filename, 'rb');
43    if ($stream === false) {
44        echo "エラー: gzippedファイルストリームを開けませんでした。\n";
45        // 作成したファイルをクリーンアップ
46        unlink($filename);
47        return;
48    }
49    echo "gzippedファイルストリームを正常に開きました。\n";
50
51    echo "\n--- gzseek機能の実演 ---\n";
52
53    // 初期の読み込みを行い、現在の位置とコンテンツを示す
54    $initialReadLength = 20; // 最初の20バイトを読み込む
55    $initialRead = gzread($stream, $initialReadLength);
56    echo "1. 初期読み込み ({$initialReadLength}バイト): '" . $initialRead . "'\n"; // 期待値: "Hello, this is a tes"
57
58    // gzseek with SEEK_SET: 非圧縮データの先頭からの指定バイトオフセットにポインタを移動
59    $offsetSet = 25; // 非圧縮データの25バイト目(0インデックス)に移動
60    // gzseekは成功した場合に新しい位置を、失敗した場合に-1を返します。
61    $seekResultSet = gzseek($stream, $offsetSet, SEEK_SET);
62    if ($seekResultSet !== -1) {
63        echo "2. gzseek({$offsetSet}, SEEK_SET) 成功。非圧縮データの新しい位置: " . gztell($stream) . "。\n";
64        $readAfterSeekSetLength = 15;
65        $readAfterSeekSet = gzread($stream, $readAfterSeekSetLength);
66        echo "   SEEK_SET後の読み込み ({$readAfterSeekSetLength}バイト): '" . $readAfterSeekSet . "'\n"; // 期待値: "t string for PH" (元のコンテンツの25バイト目から)
67    } else {
68        echo "2. gzseek({$offsetSet}, SEEK_SET) 失敗。\n";
69    }
70
71    // gzseek with SEEK_CUR: 現在位置からの相対的なポインタ移動
72    $offsetCur = 10; // 現在位置から10バイト前方へ移動
73    // 前回の読み込み後の非圧縮データの現在位置は 25 + 15 = 40。
74    // さらに10バイト移動すると50バイト目になります。
75    $seekResultCur = gzseek($stream, $offsetCur, SEEK_CUR);
76    if ($seekResultCur !== -1) {
77        echo "3. gzseek({$offsetCur}, SEEK_CUR) 成功。非圧縮データの新しい位置: " . gztell($stream) . "。\n";
78        $readAfterSeekCurLength = 20;
79        $readAfterSeekCur = gzread($stream, $readAfterSeekCurLength);
80        echo "   SEEK_CUR後の読み込み ({$readAfterSeekCurLength}バイト): '" . $readAfterSeekCur . "'\n"; // 期待値: "P gzseek and gzde" (元のコンテンツの50バイト目から)
81    } else {
82        echo "3. gzseek({$offsetCur}, SEEK_CUR) 失敗。\n";
83    }
84
85    // gzseek with SEEK_END: 非圧縮データの末尾からの相対的なポインタ移動
86    $offsetEnd = -50; // 非圧縮データの末尾から50バイト後方に移動
87    $seekResultEnd = gzseek($stream, $offsetEnd, SEEK_END);
88    if ($seekResultEnd !== -1) {
89        echo "4. gzseek({$offsetEnd}, SEEK_END) 成功。非圧縮データの新しい位置: " . gztell($stream) . "。\n";
90        $readAfterSeekEndLength = 40; // そこから40バイト読み込む
91        $readAfterSeekEnd = gzread($stream, $readAfterSeekEndLength);
92        echo "   SEEK_END後の読み込み ({$readAfterSeekEndLength}バイト): '" . $readAfterSeekEnd . "'\n";
93        // 比較のために元のコンテンツから期待される部分文字列を取得
94        $expectedReadEnd = substr($originalContent, strlen($originalContent) + $offsetEnd, $readAfterSeekEndLength);
95        echo "   (期待される読み込み: '" . $expectedReadEnd . "')\n";
96    } else {
97        echo "4. gzseek({$offsetEnd}, SEEK_END) 失敗。\n";
98    }
99
100    // gzippedファイルストリームを閉じる
101    gzclose($stream);
102    echo "\ngzippedファイルストリームを閉じました。\n";
103
104    echo "\n--- gzdecode機能の実演 (gzippedデータ文字列に関連) ---\n";
105    echo "gzdecodeは、gzipped文字列を直接展開するために使用されます。\n";
106    // ファイルに書き込んだのと同じ圧縮済みコンテンツ文字列を使用します。
107    $decompressedString = gzdecode($gzippedContent);
108
109    if ($decompressedString !== false) {
110        echo "gzdecodeを使用してgzippedコンテンツを正常に展開しました。\n";
111        echo "元のコンテンツ (比較用):\n" . $originalContent . "\n";
112        echo "展開された文字列:\n" . $decompressedString . "\n";
113        if ($originalContent === $decompressedString) {
114            echo "検証: 展開された文字列は元のコンテンツと一致します。\n";
115        } else {
116            echo "検証: 展開されたコンテンツと元のコンテンツの間に不一致があります。\n";
117        }
118    } else {
119        echo "エラー: gzdecodeは文字列を展開できませんでした。\n";
120    }
121
122    // --- クリーンアップ ---
123    // 作成した一時ファイルを削除
124    unlink($filename);
125    echo "\n一時ファイル '{$filename}' をクリーンアップしました。\n";
126}
127
128// デモンストレーション関数を実行
129demonstrateGzseekAndGzdecode();
130
131?>

PHPのgzseek関数は、gzopenで開かれたgzipped形式のファイル内で、非圧縮状態のデータの読み書きポインタを移動させる際に使用されます。第一引数$streamにはgzopenで得られたファイルリソースを指定し、第二引数$offsetで移動するバイト数、第三引数$whenceで移動の基準位置(SEEK_SETでファイルの先頭から、SEEK_CURで現在位置から、SEEK_ENDでファイルの末尾から)を設定します。成功すると新しいファイルポインタの位置を、失敗すると-1を整数値で返します。

このサンプルコードでは、まずgzencodeでテキストを圧縮し、一時的なgzippedファイルを作成します。次に、gzopenでそのファイルを開き、gzseekを様々な$whenceオプション(SEEK_SET、SEEK_CUR、SEEK_END)で実行し、gzreadで読み込まれるデータがどのように変化するかを実演しています。これにより、圧縮されたファイルにおいても、指定した位置から非圧縮データとしてアクセスできることを示します。また、gzdecode関数を使って、ファイルからではなく、メモリ上のgzippedデータ文字列を直接元のテキストに展開する機能も併せて紹介し、展開されたデータが元の内容と一致することを検証しています。最後に、作成した一時ファイルを削除し、クリーンアップを行っています。

gzseekは、gzippedファイル内の非圧縮データのオフセットを基準にポインタを移動します。圧縮後のファイルサイズではなく、元のデータサイズを考慮する点にご注意ください。戻り値は成功時に新しい位置の整数、失敗時に-1ですので、必ずエラーチェックを行ってください。SEEK_ENDを使う際は、末尾からの相対位置を指定するため、オフセットは通常負の値になります。gzopenで開いたファイルストリームは、処理完了後にgzcloseで必ず閉じるようにし、リソースリークを防ぎましょう。gzdecodeは、圧縮された文字列データを直接展開する関数で、gzseekのようなファイルストリーム操作とは用途が異なります。各関数の入力と出力を混同しないよう理解することが大切です。一時ファイルは、使用後にunlinkで確実に削除し、クリーンアップする習慣をつけることを推奨します。

PHP gzseekとgzreadでGZファイル操作

1<?php
2
3/**
4 * GZ圧縮ファイルに対するgzseek()とgzread()の基本的な使用方法を示す関数。
5 *
6 * この関数は、テスト用のGZ圧縮ファイルを作成し、
7 * gzseek()を使ってファイルポインタを移動させた後、
8 * gzread()で特定の位置からデータを読み込む方法を実演します。
9 */
10function demonstrateGzseekAndGzread(): void
11{
12    $fileName = 'example.gz'; // テスト用のGZファイル名
13    $originalContent = "これはGZファイルに書き込むサンプルコンテンツです。シークと読み込みを試します。";
14    $readLength = 15; // gzread()で読み込むバイト数
15
16    // 1. テスト用のGZファイルを作成し、内容を書き込む
17    // gzopen() でGZファイルを書き込みモード ('wb') で開きます。
18    $gzFileWriteHandle = gzopen($fileName, 'wb9'); // 'wb9'は書き込みモードで最高圧縮レベル
19    if ($gzFileWriteHandle === false) {
20        echo "エラー: GZファイル '{$fileName}' を書き込みモードで開けませんでした。\n";
21        return;
22    }
23
24    // gzwrite() でGZファイルにデータを書き込みます。
25    if (gzwrite($gzFileWriteHandle, $originalContent) === false) {
26        echo "エラー: GZファイルにデータを書き込めませんでした。\n";
27        gzclose($gzFileWriteHandle);
28        return;
29    }
30    gzclose($gzFileWriteHandle); // ファイルを閉じます
31    echo "GZファイル '{$fileName}' にテストデータが書き込まれました。\n\n";
32
33    // 2. GZファイルを読み込みモードで開く
34    // gzopen() でGZファイルを読み込みモード ('rb') で開きます。
35    $gzFileReadHandle = gzopen($fileName, 'rb');
36    if ($gzFileReadHandle === false) {
37        echo "エラー: GZファイル '{$fileName}' を読み込みモードで開けませんでした。\n";
38        // エラー発生時は作成したファイルを削除
39        if (file_exists($fileName)) {
40            unlink($fileName);
41        }
42        return;
43    }
44
45    // 3. gzread() で最初の部分を読み込む (シーク前の状態を確認)
46    echo "--- ファイルの先頭から{$readLength}バイトを読み込みます ---\n";
47    $firstRead = gzread($gzFileReadHandle, $readLength);
48    if ($firstRead === false) {
49        echo "エラー: GZファイルからデータを読み込めませんでした。\n";
50        gzclose($gzFileReadHandle);
51        if (file_exists($fileName)) {
52            unlink($fileName);
53        }
54        return;
55    }
56    echo "読み込みデータ (先頭から): \"{$firstRead}\"\n\n";
57
58    // 4. gzseek() でファイルポインタを特定の位置に移動させる
59    // 例: ファイルの先頭から20バイト目に移動
60    $offset = 20;
61    $whence = SEEK_SET; // ファイルの先頭 (SEEK_SET)、現在の位置 (SEEK_CUR)、ファイルの末尾 (SEEK_END) を基準にオフセットを指定
62
63    // gzseek() は成功した場合 0 を、失敗した場合 -1 を返します。
64    if (gzseek($gzFileReadHandle, $offset, $whence) === -1) {
65        echo "エラー: GZファイルポインタを {$offset} バイト目にシークできませんでした。\n";
66        gzclose($gzFileReadHandle);
67        if (file_exists($fileName)) {
68            unlink($fileName);
69        }
70        return;
71    }
72    echo "--- ファイルポインタを {$offset} バイト目 (ファイルの先頭から) にシークしました ---\n\n";
73
74    // 5. シーク後の位置から gzread() でデータを読み込む
75    echo "--- シーク後、次の{$readLength}バイトを読み込みます ---\n";
76    $seekedRead = gzread($gzFileReadHandle, $readLength);
77    if ($seekedRead === false) {
78        echo "エラー: GZファイルからデータを読み込めませんでした。\n";
79        gzclose($gzFileReadHandle);
80        if (file_exists($fileName)) {
81            unlink($fileName);
82        }
83        return;
84    }
85    echo "読み込みデータ (シーク後): \"{$seekedRead}\"\n\n";
86
87    // 6. GZファイルを閉じる
88    gzclose($gzFileReadHandle);
89    echo "GZファイル '{$fileName}' が閉じられました。\n";
90
91    // 7. 作成したテストファイルを削除 (クリーンアップ)
92    if (file_exists($fileName)) {
93        unlink($fileName);
94        echo "テストファイル '{$fileName}' が削除されました。\n";
95    }
96}
97
98// 関数を実行してデモンストレーションを開始
99demonstrateGzseekAndGzread();

PHPのgzseek関数は、GZ圧縮されたファイル内でデータを読み書きする位置(ファイルポインタ)を移動させるために使用されます。この関数を使うことで、GZ圧縮された大きなファイルの中から、必要な部分だけを効率的に読み込んだり、スキップしたりすることが可能になります。

第1引数$streamには、gzopen()などで開かれたGZ圧縮ファイルのファイルハンドラ(リソース)を指定します。 第2引数$offsetは、ファイルポインタを移動させたいバイト数を整数で指定します。 第3引数$whenceはオプションで、$offsetの基準となる位置を指定します。具体的には、ファイルの先頭からを意味するSEEK_SET、現在のファイルポインタの位置からを意味するSEEK_CUR、ファイルの末尾からを意味するSEEK_ENDのいずれかを設定し、デフォルトはSEEK_SETです。 関数の戻り値は整数で、ファイルポインタの移動に成功した場合は0を、失敗した場合は-1を返します。

提供されたサンプルコードは、このgzseek()関数とgzread()関数を組み合わせて使う方法を具体的に示しています。まず、テスト用のGZファイルを作成し、データを書き込みます。その後、ファイルを読み込みモードで開き、gzread()でファイルの先頭から一部を読み込みます。次に、gzseek()を使ってファイルポインタをファイルの先頭から20バイト目など特定のオフセットに移動させます。ファイルポインタの移動後、再度gzread()を呼び出すと、新しい位置からデータが読み込まれることを確認できます。これにより、GZ圧縮ファイル内の任意の場所から直接データを読み出す処理の流れを学習できます。

gzseek関数は、GZ圧縮ファイル内のポインタを移動させますが、成功時に0、失敗時に-1を返します。一般的なPHP関数の戻り値とは異なるため、処理の成否をこの戻り値で必ず確認してください。gzseekやgzreadを使用する際は、gzopenでファイルを'rb'(読み込みモード)で開く必要があります。オフセットはバイト単位で指定するため、日本語などのマルチバイト文字を扱う場合は、読み込み位置が意図した文字の途中になる可能性がある点も注意が必要です。全てのgz関連関数でエラーハンドリングを徹底し、使用後はgzcloseで確実にリソースを解放することが、安全で堅牢なコード作成に繋がります。

関連コンテンツ

関連プログラミング言語