［PHP］fpassthru関数完全ガイド：ファイル内容を出力する効率的な方法

はじめに
fpassthru関数とは？
1. 引数
2. 戻り値
基本的な使い方
fpassthru関数の特徴と活用シーン
readfile関数との比較
実践的な応用例
1. 画像ファイルの表示
2. 動的なファイル生成と出力
注意点とベストプラクティス
まとめ

はじめに

PHPでファイル処理を行う際、様々な関数が用意されていますが、その中でも「fpassthru」関数は特定の用途において非常に便利なツールです。この関数は簡潔ながらも強力な機能を持っており、大きなファイルを扱う場面で真価を発揮します。

fpassthru関数とは？

fpassthru関数は、開いているファイルポインタから読み込んだすべての残りのデータを標準出力（通常はブラウザ）に出力する関数です。基本構文は次のとおりです：

int fpassthru(resource $stream)

引数

$stream: ファイルポインタリソース。fopen()やfsockopen()などで開いたもの

戻り値

成功した場合：出力されたバイト数
失敗した場合：false

基本的な使い方

<?php
$file = fopen('example.txt', 'r');
// ファイルポインタを特定の位置まで進める場合（オプション）
// fseek($file, 10); // 最初の10バイトをスキップ
$bytes = fpassthru($file);
fclose($file);
echo "出力したバイト数: $bytes";
?>

fpassthru関数の特徴と活用シーン

1. メモリ効率の良いファイル出力

fpassthruの最大の利点は、ファイル全体をメモリに読み込まずにストリームとして直接出力できる点です。これは大きなファイルを扱う際に特に重要です。

<?php
// 大きなファイルを効率的に出力
$file = fopen('large_document.pdf', 'r');
header('Content-Type: application/pdf');
header('Content-Disposition: inline; filename="document.pdf"');
fpassthru($file);
fclose($file);
exit;
?>

2. 部分的なファイル出力

fseek()と組み合わせることで、ファイルの特定の部分だけを出力することも可能です。

<?php
$file = fopen('data.txt', 'r');
fseek($file, 100); // 最初の100バイトをスキップ
fpassthru($file);  // 残りの部分を出力
fclose($file);
?>

3. ダウンロード機能の実装

ファイルダウンロード機能を実装する際に非常に便利です：

<?php
function downloadFile($path, $filename = null) {
    if (!file_exists($path)) {
        return false;
    }

    $filename = $filename ?: basename($path);
    $file = fopen($path, 'rb');

    // 必要なヘッダーを設定
    header('Content-Type: application/octet-stream');
    header('Content-Disposition: attachment; filename="' . $filename . '"');
    header('Content-Length: ' . filesize($path));
    header('Cache-Control: no-cache');

    // ファイル内容を出力
    fpassthru($file);
    fclose($file);
    exit;
}

// 使用例
downloadFile('/path/to/document.docx');
?>

readfile関数との比較

PHPには似た機能を持つreadfile()関数もありますが、使用シーンが若干異なります：

<?php
// readfile()の例
$bytes = readfile('example.txt');
echo "出力したバイト数: $bytes";

// fpassthru()の例
$file = fopen('example.txt', 'r');
$bytes = fpassthru($file);
fclose($file);
echo "出力したバイト数: $bytes";
?>

主な違い：

readfile()：ファイル名を直接指定し、開いて読み込んで閉じる処理を一度に行う
fpassthru()：既に開いているファイルポインタに対して使用し、現在の位置から読み込む

実践的な応用例

画像ファイルの表示

<?php
function displayImage($imagePath) {
    if (!file_exists($imagePath)) {
        return false;
    }

    $extension = pathinfo($imagePath, PATHINFO_EXTENSION);
    $contentType = 'image/jpeg'; // デフォルト

    // Content-Typeを適切に設定
    switch (strtolower($extension)) {
        case 'png':
            $contentType = 'image/png';
            break;
        case 'gif':
            $contentType = 'image/gif';
            break;
        case 'webp':
            $contentType = 'image/webp';
            break;
    }

    $file = fopen($imagePath, 'rb');
    header('Content-Type: ' . $contentType);
    fpassthru($file);
    fclose($file);
    exit;
}

// 使用例
displayImage('photos/landscape.jpg');
?>

動的なファイル生成と出力

<?php
// 一時ファイルを生成して出力する例
function generateAndOutputCSV($data) {
    $tempFile = tempnam(sys_get_temp_dir(), 'csv_');
    $file = fopen($tempFile, 'w');

    // CSVヘッダー
    fputcsv($file, array_keys($data[0]));

    // データ行
    foreach ($data as $row) {
        fputcsv($file, $row);
    }

    // ファイルポインタを先頭に戻す
    fseek($file, 0);

    // ヘッダー設定
    header('Content-Type: text/csv');
    header('Content-Disposition: attachment; filename="export.csv"');

    // 出力して終了
    fpassthru($file);
    fclose($file);
    unlink($tempFile); // 一時ファイルを削除
    exit;
}
?>

注意点とベストプラクティス

メモリ使用量: fpassthru()は大きなファイルをメモリ効率良く扱えますが、出力バッファリングが有効になっている場合は注意が必要です。大きなファイルを扱う場合はob_end_clean()などでバッファをクリアすることも検討しましょう。
エラーハンドリング: 戻り値をチェックして処理の成功/失敗を確認することをお勧めします。

<?php
$file = fopen('document.pdf', 'r');
if ($file) {
    $bytes = fpassthru($file);
    if ($bytes === false) {
        echo "ファイルの出力に失敗しました。";
    }
    fclose($file);
} else {
    echo "ファイルを開けませんでした。";
}
?>