PHP fopen() 函數深度解析：模式參數、流包裝協議與跨平台換行符處理

函數原型與核心功能

resource fopen(string $filename, string $mode [, bool $use_include_path = false [, resource $context ]])

fopen() 將 filename 指定的資源（本地檔案、URL 或其他流包裝協議）綁定到一個流資源上，返回檔案指標資源，失敗返回 false 並觸發 E_WARNING。

• filename：檔案路徑或 URL（如 https://example.com/file.txt、ftp://user:pass@server/file、php://input 等）。若格式為 scheme://...，PHP 會尋找對應的流包裝協議處理器。
• mode：指定存取模式（讀/寫/附加/二進位/文字等），詳見下表。
• use_include_path：若為 true，則在 include_path 中尋找檔案（主要用於引入腳本）。
• context：由 stream_context_create() 建立的上下文資源，可設定 HTTP 標頭、FTP 參數、SSL 選項等。

流包裝協議與設定限制

• 若 filename 為本地檔案，需確保 PHP 擁有讀寫權限；若啟用 safe_mode 或 open_basedir，將受進一步限制。
• 若為網絡 URL 協議（如 http、ftp），需 php.ini 中 allow_url_fopen=On，否則會發出警告並失敗。
• 未註冊的協議會被視為普通檔案名，PHP 會嘗試在本地檔案系統開啟。

mode 參數完整對照表

注意：x 和 x+ 模式自 PHP 4.3.2 起支援，僅適用於本地檔案。若檔案已存在，fopen() 返回 false 並拋出 E_WARNING（底層對應 O_EXCL|O_CREAT 旗標）。

跨平台換行符與二進位/文字模式旗標

不同作業系統換行符不同：

• Unix/Linux/macOS (現代)：\n (LF)
• Windows：\r\n (CRLF)
• 經典 Mac OS (9 及之前)：\r (CR)

若在 Windows 上以文字模式寫入 \n，PHP 可自動轉為 \r\n；讀取時反向轉換。為避免資料損壞（如圖片、壓縮檔），操作二進位檔案務必加上 b 旗標（如 rb、wb、ab）。

旗標用法：

• b：強制二進位模式，不做任何換行轉換（推薦用於所有非純文字檔）。
• t：Windows 文字模式，透明轉換 \n ⇄ \r\n（僅 Windows 有效）。

範例：fopen('data.bin', 'wb')、fopen('log.txt', 'at')。為提高可移植性，建議始終顯式指定 b 或 t，而非依賴預設值（預設值取決於 SAPI 與 PHP 版本）。

常見使用範例

<?php
// 讀取本地文字檔（自動處理換行）
$fp = fopen('config.ini', 'rt');
if ($fp) {
    while (($line = fgets($fp)) !== false) {
        echo $line;
    }
    fclose($fp);
}

// 以二進位模式寫入圖片資料
$imgData = file_get_contents('https://example.com/logo.png');
$fp = fopen('logo.png', 'wb');
if ($fp) {
    fwrite($fp, $imgData);
    fclose($fp);
}

// 使用 HTTP Context 發送 POST 請求
$ctx = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => 'Content-Type: application/x-www-form-urlencoded',
        'content' => http_build_query(['key' => 'value']),
    ]
]);
$fp = fopen('https://api.example.com/endpoint', 'rb', false, $ctx);
$response = stream_get_contents($fp);
fclose($fp);
?>