傳統 opendir/readdir 寫法繁瑣且易出錯(需手動跳過 . ..、處理路徑拼接)。PHP SPL (Standard PHP Library) 提供了強大的迭代器,讓目錄遍歷變得優雅、高效、可組合。本文詳細介紹 DirectoryIterator、RecursiveDirectoryIterator、GlobIterator 等類別的實戰用法。
<?php
$dir = new DirectoryIterator(__DIR__);
foreach ($dir as $fileInfo) {
if ($fileInfo->isDot()) continue; // 自動跳過 . 和 ..
echo sprintf(
"%-30s %10s %s %s\n",
$fileInfo->getFilename(),
$fileInfo->isDir() ? 'DIR' : 'FILE',
$fileInfo->getSize(),
$fileInfo->getMTime()->format('Y-m-d H:i:s')
);
}
關鍵方法:isFile()、isDir()、isLink()、isReadable()、isWritable()、getSize()、getMTime()(回傳 DateTime)、getPathname()、getBasename()、getExtension()。
<?php
$root = '/var/www/project';
$iterator = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($root, RecursiveDirectoryIterator::SKIP_DOTS),
RecursiveIteratorIterator::SELF_FIRST // 先目錄後檔案
);
foreach ($iterator as $fileInfo) {
$depth = $iterator->getDepth();
$indent = str_repeat(' ', $depth);
$type = $fileInfo->isDir() ? '📁' : '📄';
echo "$indent$type {$fileInfo->getBasename()}\n";
}
$phpFiles = new RegexIterator(
new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($root, RecursiveDirectoryIterator::SKIP_DOTS)
),
'/\.php$/i'
);
foreach ($phpFiles as $file) {
echo $file->getPathname() . "\n";
}
$filter = new CallbackFilterIterator(
new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($root, RecursiveDirectoryIterator::SKIP_DOTS)
),
function ($current, $key, $iterator) {
// 排除目錄
if ($current->isDir() && in_array($current->getBasename(), ['vendor', 'node_modules', '.git', 'storage'])) {
return false;
}
// 排除大檔
if ($current->isFile() && $current->getSize() > 1_000_000) {
return false;
}
return true;
}
);
foreach ($filter as $file) {
// 已過濾
}
// 找出所有子目錄下的 *.blade.php
$blades = new GlobIterator('/var/www/project/**/*.blade.php', GlobIterator::KEY_AS_PATHNAME);
foreach ($blades as $path => $file) {
echo $path . "\n";
}
// 多模式組合
$patterns = ['**/*.php', '**/*.html', '**/*.vue'];
$multiple = new AppendIterator();
foreach ($patterns as $p) {
$multiple->append(new GlobIterator($root . '/' . $p));
}
foreach ($multiple as $file) { /* ... */ }
SPL 迭代器本身不支援排序,需先收集到陣列再排序,或使用 FilesystemIterator::CURRENT_AS_FILEINFO 搭配 iterator_to_array:
$files = iterator_to_array(
new FilesystemIterator($dir, FilesystemIterator::SKIP_DOTS | FilesystemIterator::CURRENT_AS_FILEINFO)
);
// 依修改時間新舊排序
usort($files, fn($a, $b) => $b->getMTime() <=> $a->getMTime());
// 依大小排序
usort($files, fn($a, $b) => $b->getSize() <=> $a->getSize());
// 依名稱自然排序
uksort($files, 'strnatcasecmp');
| 方法 | 記憶體 | 速度 | 適用場景 |
|---|---|---|---|
| DirectoryIterator | O(1) 固定 | 快 | 單層列表、即時處理 |
| RecursiveIteratorIterator | O(深度) | 快 | 樹狀遍歷、遞歸處理 |
| iterator_to_array + usort | O(N) 全部載入 | 中 | 需完整排序的中小目錄 |
| glob() | O(N) 全部載入 | 慢 | 簡單模式匹配、小目錄 |
<?php
// api/files.php
$requestDir = $_GET['dir'] ?? '/var/www/public';
$realBase = realpath('/var/www/public');
$realTarget = realpath($requestDir);
if (!$realTarget || strpos($realTarget, $realBase) !== 0) {
http_response_code(403);
exit(json_encode(['error' => '路徑越界']));
}
$iterator = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator($realTarget, RecursiveDirectoryIterator::SKIP_DOTS)
);
$files = [];
foreach ($iterator as $item) {
$relPath = substr($item->getPathname(), strlen($realTarget) + 1);
$files[] = [
'name' => $item->getBasename(),
'path' => $relPath,
'type' => $item->isDir() ? 'dir' : 'file',
'size' => $item->isFile() ? $item->getSize() : null,
'mtime' => $item->getMTime()->format('c'),
'ext' => $item->isFile() ? $item->getExtension() : null,
];
}
// 依類型、名稱排序
usort($files, fn($a, $b) => ($a['type'] <=> $b['type']) ?: strnatcasecmp($a['name'], $b['name']));
header('Content-Type: application/json');
echo json_encode(['base' => $requestDir, 'files' => $files]);
SPL 迭代器是 PHP 處理檔案系統的標準工具,提供豐富的過濾、遞歸、鍵值模式,配合 CallbackFilterIterator 可實現任意複雜的業務邏輯過濾。大目錄排序時注意記憶體,必要時分頁或使用資料庫索引(如 FTS)替代。