| 旗標 | 值 | 作用 |
FILE_APPEND | 1 | 追加模式(不截斷文件),指針移至末尾 |
LOCK_EX | 2 | 獨佔鎖定(寫入前 flock(LOCK_EX),寫入後自動釋放) |
FILE_TEXT | 32 | 文本模式轉換換行符(Windows \r\n ↔ Unix \n),PHP 6+ 棄用 |
FILE_BINARY | 0 | 二進制模式(默認),不轉換換行符 |
組合使用:FILE_APPEND | LOCK_EX(追加+鎖定)、**FILE_APPEND | LOCK_EX | FILE_TEXT**(Windows 文本追加)。
進階用法
1. 寫入陣列(自動 implode)
$lines = ['Line 1', 'Line 2', 'Line 3'];
file_put_contents('lines.txt', $lines); // 自動用 '' 連接,無換行
file_put_contents('lines.txt', implode("\n", $lines) . "\n"); // 手動控制格式
2. 追加寫入日誌(高併發安全)
function log_message(string $message, string $file = 'app.log'): void {
$line = date('Y-m-d H:i:s') . " $message\n";
// LOCK_EX 確保多進程併發寫入不交錯
file_put_contents($file, $line, FILE_APPEND | LOCK_EX);
}
3. 原子化寫入(防止讀到半寫文件)
function atomic_write(string $file, string $data): bool {
$tmp = $file . '.tmp.' . bin2hex(random_bytes(8));
$bytes = @file_put_contents($tmp, $data, LOCK_EX);
if ($bytes === false) return false;
// rename 在同一文件系統上是原子操作
return @rename($tmp, $file);
}
4. 流上下文:寫入遠程 FTP/HTTP、設置權限
$ctx = stream_context_create([
'ftp' => [
'username' => 'user',
'password' => 'pass',
'overwrite' => true,
],
]);
file_put_contents('ftp://server/path/file.txt', $data, 0, $ctx);
// 設置文件權限(需 PHP 7.1+ 支持 chmod 上下文選項)
$ctx = stream_context_create(['wrapper' => ['chmod' => 0644]]);
file_put_contents('local.txt', $data, 0, $ctx);
返回值與錯誤處理
- 成功:返回寫入的 **字節數**(int)。
- 失敗:返回
false,並觸發 E_WARNING。
- 必須用
=== false 判斷,因寫入 0 字節返回 0(弱類型等於 false)。
if (($bytes = file_put_contents($file, $data, FILE_APPEND | LOCK_EX)) === false) {
error_log("寫入失敗: $file");
// 降級處理...
}
性能優化建議
- 批量寫入:累積日誌在內存緩衝區,定時/達閾值批量
file_put_contents(..., FILE_APPEND)。
- 避免頻繁 LOCK_EX:極高併發下鎖競爭嚴重,考慮異步寫入(消息隊列 + 消費者單寫)。
- 大文件分片:>100MB 文件用
fopen/fwrite 流式處理,避免內存峰值。
- 啟用 OPcache:減少腳本編譯開銷,間接提升 I/O 函數吞吐。
避坑清單
| 坑點 | 現象 | 修正 |
| 忘記 FILE_APPEND | 每次寫入覆蓋文件 | 追加場景必加 FILE_APPEND |
| 併發未加 LOCK_EX | 內容交錯、數據丟失 | 多進程寫入必加 LOCK_EX |
| 路徑目錄不存在 | Warning + 返回 false | 先 mkdir(dirname($file), 0755, true) |
| 磁盤滿/權限不足 | 返回 false,無異常 | 嚴格判斷 === false,記錄錯誤日誌 |
| Windows 換行符混亂 | \r\n / \n 混用 | 統一用 \n,或開啟 FILE_TEXT(PHP 8.1+ 棄用) |
總結
file_put_contents() 是 PHP 文件寫入的 **首選 API**:簡潔、原子性友好、內建鎖定、支援流上下文。掌握 FILE_APPEND | LOCK_EX 組合拳,配合臨時文件重命名實現真正原子寫入,是構建高可靠文件存儲系統的基石。
copyright ©
萬盛學電腦網 all rights reserved