PHP 目錄與文件操作完全指南：從基礎 API 到實戰封裝

文件系統操作是 CMS、網盤、日誌系統等應用的核心功能。PHP 提供豐富的文件/目錄 API，但參數細節、版本差異、錯誤處理常讓開發者踩坑。本文系統整理核心函數並給出最佳實踐封裝。

一、目錄操作

1. 遍歷目錄：opendir/readdir/closedir 經典三部曲

$base_dir = "filelist/";
$handle = opendir($base_dir);
while (false !== ($entry = readdir($handle))) {
    echo $entry . "\n";
}
closedir($handle);

注意：返回 . 和 .. 需自行過濾。

2. 面向對象封裝：DirectoryIterator (PHP 5+)

$dir = new DirectoryIterator("/etc/php5");
foreach ($dir as $fileinfo) {
    if (!$fileinfo->isDot()) echo $fileinfo->getFilename() . "\n";
}

更符合現代風格，自動過濾 . ..，支持 SPL 迭代器鏈。

3. 路徑解析：dirname() basename() pathinfo()

$path = "/var/www/index.php";
echo dirname($path);   // /var/www
echo basename($path);  // index.php
print_r(pathinfo($path)); // ['dirname','basename','extension','filename']

4. 磁盤空間：disk_free_space() disk_total_space()

5. 目錄創建/刪除：mkdir() rmdir()

mkdir("path/to/dir", 0755, true); // 遞歸創建，權限受 umask 影響
rmdir("path/to/dir"); // 僅能刪除空目錄

二、文件操作

A. 讀取文件

前置檢查：is_readable($file) 同時驗證存在性與權限，優於單純 file_exists()。

整文件讀取：

• PHP 4.3+ 首選 file_get_contents($file)，內存映射極快。
• 舊版本回退：$h=fopen($file,'r'); $data=fread($h,filesize($file)); fclose($h);
• 二進制安全：implode('', file($file))。

B. 寫入文件

前置檢查：is_writable($file)。

整文件寫入：

• PHP 5+ 首選 file_put_contents($file, $data)，支持 FILE_APPEND、LOCK_EX 旗標。
• 舊版本：$h=fopen($file,'w'); fwrite($h,$data); fclose($h);

併發安全寫入（帶鎖）：

function cache_page($path, $data) {
    if (!$fp = fopen($path, 'w')) return false;
    if (!flock($fp, LOCK_EX)) { fclose($fp); return false; }
    if (!fwrite($fp, $data)) { flock($fp, LOCK_UN); fclose($fp); return false; }
    flock($fp, LOCK_UN);
    fclose($fp);
    return true;
}

C. 複製/刪除/重命名

unlink($file);           // 刪除
copy($src, $dest);       // 複製，目標目錄需可寫
rename($old, $new);      // 重命名/移動，跨分區可能失敗

D. 文件屬性獲取

三、實戰建議

1. 所有文件操作必須檢查返回值，失敗時記錄日誌並拋出異常。
2. 路徑拼接使用 DIRECTORY_SEPARATOR 或 realpath() 規範化，避免跨平台問題。
3. 大文件讀寫採用流式處理（fread/fwrite 循環），避免內存溢出。
4. 權限設置遵循最小權限原則：目錄 0755，文件 0644，敏感配置 0600。

熟練掌握上述 API 並封裝為專案通用的 FileSystem 工具類，是 PHP 後端工程師的基本功。