三種核心實作方式
方式一:傳統 opendir/readdir (PHP 4+ 相容)
<?php
/**
* 遞迴掃描目錄,回傳巢狀陣列
* @param string $dir 絕對或相對路徑
* @return array 結構:['dirName' => [...sub], 'fileName', ...]
*/
function scanDirRecursive(string $dir): array {
$result = [];
$dir = rtrim($dir, '/\\');
if (!is_dir($dir)) return $result;
$handle = opendir($dir);
if (!$handle) return $result;
while (($entry = readdir($handle)) !== false) {
if ($entry === '.' || $entry === '..') continue;
$path = $dir . DIRECTORY_SEPARATOR . $entry;
if (is_dir($path)) {
$result[$entry] = scanDirRecursive($path); // 目錄作為鍵,值為子陣列
} else {
$result[] = $entry; // 檔案以數字索引存入
}
}
closedir($handle);
return $result;
}
// 使用
$tree = scanDirRecursive(__DIR__);
print_r($tree);
方式二:scandir() + 遞迴 (PHP 5+ 推薦,較簡潔)
<?php
function scanDirScandir(string $dir): array {
$result = [];
$dir = rtrim($dir, '/\\');
if (!is_dir($dir)) return $result;
$entries = scandir($dir);
foreach ($entries as $entry) {
if ($entry === '.' || $entry === '..') continue;
$path = $dir . DIRECTORY_SEPARATOR . $entry;
if (is_dir($path)) {
$result[$entry] = scanDirScandir($path);
} else {
$result[] = $entry;
}
}
return $result;
}
方式三:glob() 遞迴 (最簡潔,支援模式匹配)
<?php
function scanDirGlob(string $dir): array {
$result = [];
$dir = rtrim($dir, '/\\');
foreach (glob($dir . '/*', GLOB_NOSORT) as $path) {
$name = basename($path);
if (is_dir($path)) {
$result[$name] = scanDirGlob($path);
} else {
$result[] = $name;
}
}
return $result;
}
// 進階:直接取得所有檔案路徑 (扁平化)
function getAllFiles(string $dir): array {
$files = [];
$iterator = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($dir, RecursiveDirectoryIterator::SKIP_DOTS)
);
foreach ($iterator as $file) {
if ($file->isFile()) {
$files[] = $file->getPathname();
}
}
return $files;
}
現代最佳實踐:SPL 迭代器 (PHP 5.3+)
<?php
/**
* 使用 RecursiveDirectoryIterator + RecursiveIteratorIterator
* 記憶體效率高、支援過濾、可控制深度
*/
function scanDirSpl(string $dir, int $maxDepth = -1, callable $filter = null): array {
$result = [];
$dir = rtrim($dir, '/\\');
$iterator = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($dir, RecursiveDirectoryIterator::SKIP_DOTS),
RecursiveIteratorIterator::SELF_FIRST
);
if ($maxDepth > 0) {
$iterator->setMaxDepth($maxDepth);
}
foreach ($iterator as $path => $splFileInfo) {
if ($filter && !$filter($splFileInfo)) continue;
$relative = substr($path, strlen($dir) + 1);
$result[$relative] = [
'path' => $path,
'name' => $splFileInfo->getFilename(),
'size' => $splFileInfo->getSize(),
'mtime' => $splFileInfo->getMTime(),
'is_dir' => $splFileInfo->isDir(),
'extension' => $splFileInfo->getExtension(),
];
}
return $result;
}
// 使用範例:只掃描 .php 檔案,深度 2 層
$phpFiles = scanDirSpl(__DIR__, 2, fn($f) => $f->isFile() && $f->getExtension() === 'php');
print_r($phpFiles);
效能與記憶體比較
| 方法 | 記憶體 | 速度 | 功能豐富度 | 推薦場景 |
| opendir/readdir | 低 (流式) | 中 | 基礎 | 極舊環境、超大目錄 |
| scandir() | 中 (載入全目錄) | 快 | 基礎 | 一般用途、中小目錄 |
| glob() | 中 | 中 (模式匹配開銷) | 模式匹配 | 需過濾副檔名 |
| SPL Iterators | 低 (迭代器) | 快 | 最高 (深度、過濾、鏈式) | 現代專案、大型目錄、複雜需求 |
跨平台路徑處理
<?php
// 統一使用常數
$path = $dir . DIRECTORY_SEPARATOR . $file; // Windows: \ Linux: /
$path = $dir . '/' . $file; // PHP 內部自動轉換,建議統一用 /
// 規範化路徑
$realPath = realpath($path); // 解析 . .. 符號連結,回傳絕對路徑
$normalized = str_replace('\\', '/', $path); // 統一分隔符
實務工具類:目錄掃描器
<?php
class DirectoryScanner {
public function __construct(
private string $root,
private int $maxDepth = -1,
private array $extensions = [],
private bool $includeDirs = false
) {
$this->root = realpath($root) ?: $root;
}
public function scan(): Generator {
$iterator = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($this->root, RecursiveDirectoryIterator::SKIP_DOTS),
RecursiveIteratorIterator::SELF_FIRST
);
if ($this->maxDepth > 0) $iterator->setMaxDepth($this->maxDepth);
foreach ($iterator as $path => $info) {
$relPath = substr($path, strlen($this->root) + 1);
if ($info->isDir()) {
if ($this->includeDirs) {
yield $relPath => ['type' => 'dir', 'path' => $path];
}
continue;
}
if ($this->extensions && !in_array($info->getExtension(), $this->extensions)) {
continue;
}
yield $relPath => [
'type' => 'file',
'path' => $path,
'size' => $info->getSize(),
'mtime' => $info->getMTime(),
'extension' => $info->getExtension(),
];
}
}
public function getTree(): array {
$tree = [];
foreach ($this->scan() as $path => $info) {
$parts = explode('/', $path);
$ref = &$tree;
foreach ($parts as $i => $part) {
if ($i === array_key_last($parts)) {
$ref[$part] = $info;
} else {
if (!isset($ref[$part]) || !is_array($ref[$part])) {
$ref[$part] = [];
}
$ref = &$ref[$part];
}
}
}
return $tree;
}
}
// 使用
$scanner = new DirectoryScanner('/var/www', 3, ['php', 'js', 'css']);
foreach ($scanner->scan() as $path => $info) {
echo "{$info['type']} $path ({$info['size']} bytes)\n";
}
常見問題排查
- 權限拒絕:`is_readable($dir)` 預檢,或 `try-catch` 捕獲 `PermissionDenied`
- 符號連結循環:`RecursiveDirectoryIterator::FOLLOW_SYMLINKS` 需謹慎啟用,配合 `maxDepth` 防無限遞迴
- 超大目錄記憶體爆炸:改用 `Generator` (如上方類別) 逐個產出,而非建立完整陣列
- Windows 路徑長度限制 (260 字元):啟用長路徑支援或縮短目錄結構
總結建議
- 現代專案 (PHP 7.4+) **首選 SPL 迭代器** + Generator 模式
- 簡單腳本、相容舊版 → `scandir()` + 遞迴函數
- 需模式匹配 → `glob()`
- 永遠使用 `DIRECTORY_SEPARATOR` 或 `/`,避免硬編碼 `\`
- 大量檔案處理務必使用迭代器避免記憶體耗盡