PHP file_put_contents() 函數完全手冊：原子寫入、追加鎖定與效能優化

函數定位

file_put_contents() 將字符串、陣列或流資源一次性寫入文件，相當於 fopen()+fwrite()+fclose() 的原子封裝，是 PHP 5+ 寫入文件的標準方式。

語法與參數

int file_put_contents ( string $filename, mixed $data [, int $flags = 0 [, resource $context ]] )

• $filename：目標文件路徑。
• $data：要寫入的數據，支援字符串、陣列（自動 implode('')）、流資源（自動 stream_copy_to_stream()）。
• $flags：位掩碼組合：
  • FILE_USE_INCLUDE_PATH：在 include_path 搜尋
  • FILE_APPEND：追加模式（預設覆蓋）
  • LOCK_EX：寫入期間獲取獨佔鎖（防併發衝突）
  • FILE_TEXT / FILE_BINARY：編碼模式（PHP 6+）
• $context：流上下文。

返回值

• 成功返回寫入的字節數（int）。
• 失敗返回 FALSE。

核心應用場景與範例

場景 1：簡單覆蓋寫入

<?php
$file = 'people.txt';
$current = file_get_contents($file);
$current .= "John Smith\n";
file_put_contents($file, $current);
?>

場景 2：高併發安全的追加寫入（日誌、計數器）

<?php
$file = 'people.txt';
$person = "John Smith\n";
file_put_contents($file, $person, FILE_APPEND | LOCK_EX);
// 組合旗標：追加 + 獨佔鎖，防多進程數據交織
?>

關鍵點：LOCK_EX 確保寫入過程原子性，避免「讀取-修改-寫入」競態條件。但注意：LOCK_EX 僅鎖定文件指針，NFS 掛載下可能失效，極高併發建議用 Redis/資料庫。

場景 3：直接寫入流資源（大數據管道）

<?php
$src = fopen('huge_export.csv', 'r');
file_put_contents('backup.csv', $src); // 內部自動 stream_copy_to_stream
fclose($src);
?>

進階技巧與避坑指南

• 原子性替換：寫入臨時文件 file_put_contents("$file.tmp", $data) 成功後 rename("$file.tmp", $file)，防止讀到半寫文件。
• 目錄不存在：會報錯，先用 mkdir(dirname($file), 0755, true) 遞歸建目錄。
• 權限問題：PHP-FPM 運行用戶需有目錄寫入權限，生產環境常見 500 錯誤源頭。
• 二進制安全：PHP 4.3.0+ 完全二進制安全，圖片、壓縮包可直接寫入。

效能對比