PHP 目錄遞迴遍歷完整指南：readdir() 與 dir() 兩大核心方法實戰

場景導讀

目錄遍歷是 PHP 專案常見需求：掃描上傳目錄、建立檔案索引、批次處理檔案等。本文詳解兩種原生函數實作遞迴掃描的完整範例。

方法一：opendir() + readdir() 經典組合

function listDir(string $dir): void
{
    if (!is_dir($dir)) {
        echo "無效目錄: $dir
";
        return;
    }

    $handle = opendir($dir);
    if (!$handle) {
        echo "無法開啟目錄: $dir
";
        return;
    }

    while (($file = readdir($handle)) !== false) {
        // 跳過當前與上層目錄
        if ($file === '.' || $file === '..') continue;

        $fullPath = $dir . DIRECTORY_SEPARATOR . $file;

        if (is_dir($fullPath)) {
            echo "📁 目錄: $fullPath
";
            listDir($fullPath); // 遞迴
        } else {
            echo "📄 檔案: $fullPath
";
        }
    }
    closedir($handle);
}

// 使用
listDir('./phpmyadmin');

方法二：dir() 物件導向風格

function tree(string $dir): void
{
    $mydir = dir($dir);
    if (!$mydir) {
        echo "無法開啟目錄: $dir
";
        return;
    }

    while (($file = $mydir->read()) !== false) {
        if ($file === '.' || $file === '..') continue;

        $fullPath = "$dir/$file";

        if (is_dir($fullPath)) {
            echo "📁 目錄: $fullPath
";
            tree($fullPath);
        } else {
            echo "📄 檔案: $fullPath
";
        }
    }
    $mydir->close();
}

tree('./phpmyadmin');

進階增強版：收集結果而非直接輸出

function scanDirectory(string $path, array &$result = [], int $depth = 0): array
{
    $items = scandir($path);
    foreach ($items as $item) {
        if ($item === '.' || $item === '..') continue;
        
        $fullPath = $path . DIRECTORY_SEPARATOR . $item;
        $info = [
            'name' => $item,
            'path' => $fullPath,
            'type' => is_dir($fullPath) ? 'dir' : 'file',
            'depth' => $depth,
            'size' => is_file($fullPath) ? filesize($fullPath) : null,
            'mtime' => filemtime($fullPath),
        ];
        
        $result[] = $info;
        
        if ($info['type'] === 'dir') {
            scanDirectory($fullPath, $result, $depth + 1);
        }
    }
    return $result;
}

$files = scanDirectory(__DIR__ . '/storage');
// 現在 $files 包含完整結構化資料，可進一步過濾、排序、匯出 JSON 等

效能與選擇建議

常見坑點避雷

• 權限問題：is_dir() / opendir() 可能因權限失敗，務必加 @ 或 try-catch（PHP 8+）
• 符號連結：遞迴可能陷入無限迴圈，需用 is_link() 檢測並決定是否跟隨
• 路徑分隔符：跨平台請恆用 DIRECTORY_SEPARATOR 常數
• 超大目錄：考慮使用 RecursiveDirectoryIterator (SPL) 獲得更好控制

現代化替代：SPL 迭代器

$iterator = new RecursiveIteratorIterator(
    new RecursiveDirectoryIterator('./phpmyadmin', 
        RecursiveDirectoryIterator::SKIP_DOTS)
);

foreach ($iterator as $file) {
    echo ($file->isDir() ? '📁 ' : '📄 ') . $file->getPathname() . "
";
}
// 內建支援過濾、深度限制、排序等進階功能