PHP でバッファー使用量を抑えて tar アーカイブをストリーミング
proc_open() を使い、GNU tar の出力をチャンク単位で読み取り、HTTP 応答として送信します。PHP はアーカイブをメモリに保持する必要も、一時アーカイブを書き出す必要もありません。ただし、トレードオフがあります。応答の開始後に tar が失敗すると、クライアントは HTTP 200 と、読み取りはできてもファイルが欠けたアーカイブを受信することがあります。ダウンロードの成功は、アーカイブが完全であることの証明にはなりません。
このチュートリアルでは、完了済みのビルドログを格納した固定ディレクトリ用に、ローカルのダウンロードエンドポイントを作成し、想定するすべてのメンバーとそのバイト列を検証します。Linux 上で、PHP 8.5.12 のローカルサーバーと、Nginx 1.28.3 配下の PHP-FPM 8.4.27 を使い、GNU tar 1.35 でテストしました。Bash、cURL、cmp も必要です。PHP では proc_open() を有効にしてください。Windows と BSD tar は、このチュートリアルの対象外です。
サポート対象の PHP 8.4 または 8.5 ブランチの、最新のパッチが適用されたリリースを使用してください。テストしたパッチリリースには、2026年10月21日のセキュリティ修正が含まれています。ディストリビューションが以前のバージョン番号を維持している場合は、ベンダーがこれらの修正をバックポート済みか確認してください。テストしたパッチリリースをいつまでも使い続けず、PHP を更新してください。
PHP の別の10月23日のセッションに関する勧告も、セッションのアップロード進捗が有効で、アプリケーションが実行時に
session.serialize_handler を php_binary または
php_serialize から php に変更し、その後に session_start() を実行する場合に該当します。この構成では、修正版がリリースされるまで、session.upload_progress.enabled=0 を
php.ini または FPM プールの設定に指定し、ワーカーを再起動してください。この例ではセッションを使用しません。
アーカイブを PHP のバッファーに保持しない
PHP の memory_limit は引き続き適用されます。この方法の利点は、転送ループがアーカイブ全体に相当する文字列ではなく、8 KiB のチャンクだけを保持することです。別の tar プロセス、PHP ランタイム、Web サーバー、OS もメモリを消費します。アプリケーションのバッファー使用量を一定範囲に抑える方法であり、すべてのメモリ制限を取り除く方法ではありません。
PharData は、ディスク上の tar アーカイブと ZIP アーカイブを操作する API を提供します。これを使うことが、必ずしもすべてのファイルの内容をひとつの文字列に読み込むことを意味するわけではありません。今回のように一度だけ生成するダウンロードでは、外部の tar プロセスを使うと、シンプルなパイプと作成処理の終了ステータスを得られます。
作業ディレクトリ内に次の内容を setup.sh として保存し、bash setup.sh を実行してください。新しい php-tar-demo ディレクトリを作成し、既存のディレクトリの再利用は拒否します。入力には、テキストファイル、空のファイル、バイナリのバイト列が含まれます。以降のファイルは php-tar-demo 内に配置します。
#!/usr/bin/env bash
set -euo pipefail
mkdir php-tar-demo
cd php-tar-demo
mkdir public logs logs/build-123
printf 'Build 123 passed\n' > logs/build-123/build.log
: > logs/build-123/empty.log
printf '\000\001\177\200\377\n' > logs/build-123/payload.bin
proc_open() で tar の出力をストリーミング
次の内容を tar-streaming.php として保存してください。proc_open() の配列形式は、シェルを介さずにプログラムを起動します。ディレクトリの絶対パスと
-- によって、ファイル名がコマンドオプションとして扱われるのを防ぎます。サーバーの信頼できる PATH を使い、TAR_OPTIONS は未設定のままにしてください。
<?php
declare(strict_types=1);
/** Both paths must already have been resolved with realpath(). */
function isWithin(string $path, string $root): bool
{
return $path === $root || str_starts_with($path, rtrim($root, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR);
}
function safeAttachmentName(string $downloadName): string
{
$name = trim((string) preg_replace('/[^A-Za-z0-9._-]+/', '_', basename($downloadName)), '._');
return $name === '' ? 'archive.tar' : substr($name, 0, 100);
}
function clearOutputBuffers(): void
{
while (ob_get_level() > 0) {
$status = ob_get_status();
if (($status['flags'] & PHP_OUTPUT_HANDLER_REMOVABLE) === 0 || !ob_end_clean()) {
throw new RuntimeException('Cannot disable output buffering for this response.');
}
}
}
function streamTarArchive(string $directory, string $downloadName = 'archive.tar'): void
{
$realDir = realpath($directory);
if ($realDir === false || !is_dir($realDir)) {
throw new InvalidArgumentException('Directory does not exist or is not accessible.');
}
clearOutputBuffers();
// Discard stderr rather than risk a full, unread pipe blocking tar.
// The exit status still tells the caller whether creation succeeded.
$descriptors = [
0 => ['file', '/dev/null', 'r'],
1 => ['pipe', 'w'],
2 => ['file', '/dev/null', 'w'],
];
$process = proc_open(['tar', '-C', $realDir, '-cf', '-', '--', '.'], $descriptors, $pipes);
if (!is_resource($process)) {
throw new RuntimeException('Could not start tar.');
}
// Let our cleanup run when PHP notices a disconnected client.
$previousIgnoreAbort = ignore_user_abort(true);
$reachedEnd = false;
try {
header('Content-Type: application/x-tar');
header('Content-Disposition: attachment; filename="' . safeAttachmentName($downloadName) . '"');
header('X-Content-Type-Options: nosniff');
header('Cache-Control: private, no-store');
header('X-Accel-Buffering: no');
while (true) {
$chunk = fread($pipes[1], 8192);
if ($chunk === false) {
throw new RuntimeException('Failed to read the tar output stream.');
}
if ($chunk === '') {
break;
}
echo $chunk;
flush();
if (connection_aborted()) {
throw new RuntimeException('Client disconnected.');
}
}
$reachedEnd = true;
} finally {
fclose($pipes[1]);
if (!$reachedEnd) {
proc_terminate($process);
}
$exitCode = proc_close($process);
ignore_user_abort($previousIgnoreAbort !== 0);
}
if ($exitCode !== 0) {
throw new RuntimeException("tar exited with status {$exitCode}");
}
}
class SecureTarStreamer
{
private array $allowedRoots;
public function __construct(array $allowedRoots)
{
$this->allowedRoots = array_map(function (string $root): string {
$resolved = realpath($root);
if ($resolved === false || !is_dir($resolved)) {
throw new InvalidArgumentException('Invalid allowed root directory.');
}
return $resolved;
}, $allowedRoots);
}
public function send(string $directory, string $downloadName = 'archive.tar'): void
{
$path = realpath($directory);
if ($path === false || !is_dir($path)) {
throw new InvalidArgumentException('Directory does not exist or is not accessible.');
}
foreach ($this->allowedRoots as $root) {
if (isWithin($path, $root)) {
streamTarArchive($path, $downloadName);
return;
}
}
throw new RuntimeException('Access to the specified directory is not allowed.');
}
}
パイプはブロッキング動作のため、空の読み取り結果は EOF を意味します。false は読み取り失敗を意味します。パイプを閉じた後、proc_close() は生成側の終了を待ち、その終了ステータスを返します。EOF も最後の書き込み成功も、tar の成功を示すものではありません。stderr を破棄すると、詳細な診断情報が失われます。診断情報が必要な場合は、stdout と stderr を並行して読み出し、診断テキストの保持量を一定範囲に制限してください。
完了済みのビルドログのディレクトリを配信
次の内容を public/download.php として保存してください。不透明な識別子 log_id で、設定済みのディレクトリをひとつ選択します。リクエストがファイルシステムのパスを指定することはありません。配信するのは public/ だけにし、元のログとヘルパーはドキュメントルートの外に置きます。
<?php
declare(strict_types=1);
require __DIR__ . '/../tar-streaming.php';
try {
$logId = $_GET['log_id'] ?? '';
$directories = ['build-123' => __DIR__ . '/../logs/build-123'];
if (!is_string($logId) || !isset($directories[$logId])) {
throw new InvalidArgumentException('Unknown log identifier.');
}
$streamer = new SecureTarStreamer([__DIR__ . '/../logs']);
$streamer->send($directories[$logId], $logId . '.tar');
error_log('Archive generation completed.');
} catch (Throwable $error) {
error_log('Archive generation failed: ' . $error->getMessage());
if (!headers_sent()) {
header_remove('Content-Disposition');
http_response_code($error instanceof InvalidArgumentException ? 400 : 500);
header('Content-Type: text/plain; charset=utf-8');
header('Cache-Control: private, no-store');
echo "The archive could not be generated.\n";
}
// After headers, adding an error message would contaminate the archive bytes.
}
proc_open() 呼び出しのセキュリティ強化
このローカル用の例には認証がありません。アプリケーションに組み込む前に、ログインと、選択したビルドへのアクセス認可の両方を必須にしてください。アーカイブ対象のディレクトリはアプリケーションの管理下に置き、先に書き込み元を停止してください。ルートの解決によって logs-evil のような兄弟ディレクトリへのアクセスは防げますが、別のプロセスによるツリーの変更までは防げません。コマンドはシンボリックリンクのエントリをたどらず、リンク先ファイルの内容は含めません。この例では、ソケットや特殊デバイスではなく、通常のファイルとディレクトリを使用してください。
次の内容を serve.sh として保存し、bash serve.sh を php-tar-demo から実行してください。フォアグラウンドで実行されます。停止するには Ctrl+C を押します。ポート 8080 が使用中の場合は PORT=8090 bash serve.sh を使い、後述のクライアントスクリプトでも同じ PORT を設定してください。バインドに失敗するとエラーで終了します。
#!/usr/bin/env bash
set -euo pipefail
if [ ! -f public/download.php ]; then
printf 'Run serve.sh from the project directory after saving public/download.php.\n' >&2
exit 1
fi
exec env -u TAR_OPTIONS php \
-d memory_limit=32M -d output_buffering=0 -d zlib.output_compression=0 \
-d display_errors=0 -d log_errors=1 \
-S "127.0.0.1:${PORT:-8080}" -t public
PHP の組み込みサーバーはローカル開発用です。既存の PHP-FPM 環境では、PHP の出力バッファリングと圧縮も無効にし、display_errors をオフにしたうえで、リクエストとアップストリームのタイムアウトを設定してください。PHP の flush() で、下流のすべてのバッファーを制御することはできません。Nginx では、このルートに
fastcgi_buffering off と fastcgi_ignore_client_abort off を使用してください。Nginx は、無視する設定になっていない限り、ヘルパーの
X-Accel-Buffering: no ヘッダーも認識します。ファイルシステムの読み取りや出力の書き込みがブロックすると、PHP のクリーンアップが遅れることもあります。このループを、実時間での期限を保証する仕組みや、永続性のあるバックグラウンドタスクとは考えないでください。
クライアントが実際に受信した内容の検証
次の内容を verify.sh として保存してください。別のターミナルで php-tar-demo 内に移動し、bash verify.sh を実行します。ダウンロード後、メンバー一覧の完全一致を確認し、ローカルのテストデータを展開して、すべての三つのファイルを元のファイルと比較します。downloaded/ は一度だけ作成し、再実行時の上書きは拒否します。いずれかの処理が失敗すると、調査用にそのディレクトリが残ります。不完全なアーカイブが含まれる場合もあるため、再実行には新しい空のプロジェクトを使用してください。
#!/usr/bin/env bash
set -euo pipefail
mkdir downloaded
curl -fsS --max-time 30 \
"http://127.0.0.1:${PORT:-8080}/download.php?log_id=build-123" \
--output downloaded/build.tar
tar -tf downloaded/build.tar | LC_ALL=C sort > downloaded/members.txt
printf './\n./build.log\n./empty.log\n./payload.bin\n' | cmp - downloaded/members.txt
tar -xf downloaded/build.tar -C downloaded
cmp logs/build-123/build.log downloaded/build.log
cmp logs/build-123/empty.log downloaded/empty.log
cmp logs/build-123/payload.bin downloaded/payload.bin
printf 'All expected members and bytes match.\n'
最後の行は、比較に合格した場合にのみ表示されます。アーカイブの一覧表示だけでは、検証として不十分です。GNU tar は、読み取りエラーを報告しながらアーカイブの書き込みを完了し、読み取れなかったメンバーを含めないことがあります。文書化されている終了ステータスでは、作成成功、入力の変更、失敗を区別していますが、生成側のステータスは HTTP 応答本文には記録されません。
たとえば、PHP ワーカーが payload.bin を読み取れない場合、ルートが tar の失敗をログに記録しても、cURL は正常終了し、tar -tf は残りのメンバーの一覧を正常に表示することがあります。上記のメンバー一覧の比較では、独立した期待値があるため、欠落を検出できます。リモートへのエクスポートで同様の検証を行うには、受信側に、別途提供された一覧とコンテンツハッシュが必要です。受信したアーカイブから一覧を作成しても、元のファイルの欠落については何も証明できません。
ダウンロードが中断された場合は?
接続が中断されると、不完全な tar ファイルが残ることがあります。一方、生成側が処理の終盤で失敗すると、解析はできても内容が不完全なアーカイブが残ることがあります。PHP がヘッダーを送信した後は、headers_sent() により、ハンドラーは HTTP 200 をエラーステータスに置き換えられません。ハンドラーは失敗をログに記録し、アーカイブにテキストを追加しません。cURL やブラウザーがダウンロード失敗を報告するとは保証できません。
ヘルパーは書き込み後に
connection_aborted() を確認し、パイプを閉じて tar に終了を要求します。検出できるかどうかは、PHP と Web サーバーが切断を認識するかに依存します。サーバー側の完了ログであっても、転送エラーが検出されずに生成が完了したことだけを意味し、クライアントがファイルを保存したことを意味するわけではありません。
このエンドポイントは HTTP 範囲リクエストを実装していません。再試行すると新しいアーカイブの作成が始まるため、入力元が変わっていればバイト列も変わる可能性があります。再開するには、同じ安定したアーカイブ表現を配信する必要があります。tar の逐次的なレイアウト自体が HTTP バイト範囲を妨げるわけではありません。
同じタスクから進捗を報告
別の tar -v プロセスが測定するのは、同じディレクトリを読み取っていても、別の実行の進捗です。ダウンロードの進捗や完了を示すものとして使わないでください。別の SSE エンドポイントには、タスク識別子と、実際の生成側が書き込む共有状態が必要です。タスクの作成ステータスとクライアントの転送ステータスは分けて管理してください。この同期処理の例には、進捗の保存先も、クライアントの完了受領通知もありません。
手法の比較
直接ストリーミングする方法は、一時アーカイブの保存を避けることが重要で、呼び出し側が処理終盤での失敗に関する制約を理解しているダウンロードに適しています。ダウンロード開始前に作成失敗を報告しなければならないバックアップやエクスポートでは、非公開の一時ファイルに生成し、生成側の終了ステータスを確認して、成功した結果だけを公開してください。この方法でも PHP のメモリ使用量を一定範囲に抑えられますが、アーカイブ用のディスク容量が必要です。
受信側が転送の完全性を検証したり転送を再開したりする必要がある場合は、完成済みで変更されないファイルを、既知の長さとチェックサムとともに配信してください。生成側を先に確認すると、作成エラーを検出するタイミングの問題は解決しますが、変化する入力元のファイルが一貫したスナップショットになるわけではありません。エクスポートでその一貫性を保証する必要がある場合は、入力を固定するか、ファイルシステムのスナップショットを使用してください。
