PHP readdir() 遍歷目錄的隱藏陷阱：0 值目錄名導致循環提前終止

PHP readdir() 遍歷目錄的隱藏陷阱：0 值目錄名導致循環提前終止

readdir() 是 PHP 遍歷目錄的基礎函數，但其返回值特性極易導致一類難以排查的 Bug：當目錄下存在名為 "0" 的文件或子目錄時，while ($name = readdir($handle)) 會提前終止。本文解析根因並給出標準修正寫法。

問題復現

<?php
$dir = '/tmp/test_dir';
mkdir($dir . '/0');      // 創建名為 "0" 的子目錄
mkdir($dir . '/normal'); // 正常目錄
$handle = opendir($dir);

// ❌ 錯誤寫法：直接判斷賦值結果
while ($name = readdir($handle)) {
    echo "Found: $name\n";
}
// 輸出僅包含 "."、"0"，"normal" 被漏掉！
closedir($handle);

根因分析

• readdir() 成功時返回文件名（字符串），失敗/結束時返回 false；
• 字符串 "0" 在 PHP 中為 **falsy 值**（弱類型轉換為 false）；
• while ($name = readdir($handle)) 將賦值結果隱式轉為布爾判斷，遇到 "0" 即判定為 false，循環中止。

正確寫法三種

1. 嚴格比較 !== false（推薦，語義最清晰）

while (($name = readdir($handle)) !== false) {
    // 處理 $name
}

2. 顯式檢查 false

while (true) {
    $name = readdir($handle);
    if ($name === false) break;
    // 處理 $name
}

3. 先收集再遍歷（適用於需多次處理）

$files = [];
while (($name = readdir($handle)) !== false) {
    $files[] = $name;
}
foreach ($files as $name) { /* 處理 */ }

完整安全遍歷模板

function listDir(string $path): array {
    if (!is_dir($path)) throw new InvalidArgumentException("Not a directory: $path");
    $handle = opendir($path);
    if (!$handle) throw new RuntimeException("Cannot open directory: $path");

    $result = [];
    try {
        while (($name = readdir($handle)) !== false) {
            if ($name === '.' || $name === '..') continue; // 跳過特殊目錄
            $result[] = $name;
        }
    } finally {
        closedir($handle); // 確保關閉句柄
    }
    return $result;
}

現代替代方案

最佳實踐總結

1. **永遠使用 !== false** 判斷 readdir() 返回值；
2. 優先選用 scandir() 或 SPL 迭代器，避免手動資源管理；
3. 遍歷前檢查 is_dir()、is_readable()；
4. try/finally 保證 closedir() 執行，防句柄洩漏。