PHP 遞歸遍歷目錄獲取所有文件路徑：scandir、SPL 迭代器、Generators 三種方案對比與生產級封裝

PHP 遞歸遍歷目錄獲取所有文件路徑：scandir、SPL 迭代器、Generators 三種方案對比與生產級封裝

獲取目錄及所有子目錄下的文件路徑是文件處理、掃描上傳、構建工具、靜態站點生成等場景的基礎操作。本文對比 scandir() 手寫遞歸、RecursiveDirectoryIterator (SPL)、Generator (生成器) 三種主流方案，從性能、內存、易用性、功能豐富度維度深度分析，並提供生產級通用工具類。

方案一：scandir() + 手寫遞歸 (經典、兼容性最好)

<?php
function getFilesScandir(string $dir): array {
    $dir = rtrim($dir, '/\\');
    if (!is_dir($dir)) return [];

    $files = [];
    $entries = scandir($dir);
    foreach ($entries as $entry) {
        if ($entry === '.' || $entry === '..') continue;
        $path = $dir . DIRECTORY_SEPARATOR . $entry;
        if (is_dir($path)) {
            $files = array_merge($files, getFilesScandir($path)); // 遞歸合併
        } else {
            $files[] = $path;
        }
    }
    return $files;
}
// 使用
$allFiles = getFilesScandir('/var/www/uploads');

優點： 代碼簡單、PHP 4+ 兼容、返回完整數組便於隨機訪問。
缺點： 遞歸深度受限於 xdebug.max_nesting_level (默認 256)；array_merge 複製數組導致內存峰值 ≈ 2x 文件列表大小；無法流式處理。

方案二：RecursiveDirectoryIterator (SPL 標準庫、功能最豐富)

<?php
function getFilesSpl(string $dir, bool $skipDots = true): array {
    $dir = rtrim($dir, '/\\');
    if (!is_dir($dir)) return [];

    $iterator = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($dir, FilesystemIterator::KEY_AS_PATHNAME | FilesystemIterator::CURRENT_AS_FILEINFO),
        RecursiveIteratorIterator::SELF_FIRST
    );
    if ($skipDots) {
        $iterator = new RegexIterator($iterator, '/^([^.].*|.+[^.])$/', RegexIterator::MATCH);
    }

    $files = [];
    foreach ($iterator as $path => $info) {
        if ($info->isFile()) {
            $files[] = $path;
        }
    }
    return $files;
}
// 進階：只獲取 .jpg 文件，按修改時間倒序
$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator($dir));
$files = new RegexIterator($iterator, '/\.jpg$/i');
$sorted = iterator_to_array($files);
usort($sorted, fn($a, $b) => $b->getMTime() <=> $a->getMTime());

優點： 內建 C 實現、支援過濾 (RegexIterator)、排序、權限/時間/類型訪問 (SplFileInfo)、自動處理跨平台路徑分隔符。
缺點： 仍需 iterator_to_array 才能隨機訪問，內存佔用同方案一。

方案三：Generator 生成器 (內存恆定、流式處理、PHP 5.5+)

<?php
function getFilesGenerator(string $dir): Generator {
    $dir = rtrim($dir, '/\\');
    if (!is_dir($dir)) return;

    $iterator = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($dir, FilesystemIterator::SKIP_DOTS),
        RecursiveIteratorIterator::CHILD_FIRST // 先文件後目錄，便於刪除操作
    );

    foreach ($iterator as $path => $info) {
        if ($info->isFile()) {
            yield $path => [
                'path'   => $path,
                'name'   => $info->getFilename(),
                'size'   => $info->getSize(),
                'mtime'  => $info->getMTime(),
                'ctime'  => $info->getCTime(),
                'perm'   => $info->getPerms(),
                'mime'   => mime_content_type($path), // 可選，較慢
            ];
        }
    }
}

// 使用：流式處理，內存 O(1)
foreach (getFilesGenerator('/var/www/uploads') as $path => $info) {
    if ($info['size'] > 10 * 1024 * 1024) {
        echo "大文件: $path ({$info['size']} bytes)\n";
    }
    // 可直接 unlink、copy、上傳 OSS、入庫，無需載入所有列表
}

// 如果確實需要數組 (小目錄)
$allFiles = iterator_to_array(getFilesGenerator($dir), true); // true 保留鍵名

優點： **內存恆定**，無論多少文件；支援中途 break、return；可組合 array_filter、array_map (轉數組後)；天然適合大目錄掃描、備份、遷移。
缺點： 無法隨機訪問 (除非轉數組)；PHP 5.5+。

效能基準測試 (10 萬文件、5 層深度、總 2GB、PHP 8.2, SSD)

生產級通用工具類：支援三種模式自動選擇

<?php
namespace App\Utils;

class DirScanner {
    /**
     * 獲取目錄下所有文件
     * @param string $dir 目標目錄
     * @param string $mode 'array'|'generator'|'spl' 返回類型
     * @param array $options 選項 ['pattern'=>'/\.jpg$/i', 'maxDepth'=>3, 'minSize'=>0, 'maxSize'=>PHP_INT_MAX]
     * @return array|Generator|RecursiveIteratorIterator
     */
    public static function scan(string $dir, string $mode = 'generator', array $options = []): mixed {
        $dir = rtrim(realpath($dir), DIRECTORY_SEPARATOR);
        if ($dir === false || !is_dir($dir)) {
            throw new InvalidArgumentException("目錄不存在: $dir");
        }

        $flags = FilesystemIterator::SKIP_DOTS;
        if (!empty($options['followLinks'])) $flags |= FilesystemIterator::FOLLOW_SYMLINKS;

        $iterator = new RecursiveIteratorIterator(
            new RecursiveDirectoryIterator($dir, $flags),
            RecursiveIteratorIterator::CHILD_FIRST
        );

        // 深度限制
        if (!empty($options['maxDepth'])) {
            $iterator = new LimitIterator($iterator, 0, PHP_INT_MAX); // LimitIterator 不直接支援深度，需自定義
            // 簡易深度控制：在 yield 時檢查 substr_count($path, DIRECTORY_SEPARATOR)
        }

        // 過濾器鏈
        if (!empty($options['pattern'])) {
            $iterator = new RegexIterator($iterator, $options['pattern'], RegexIterator::MATCH);
        }

        // 尺寸過濾 (需 SplFileInfo)
        $filter = function (SplFileInfo $info) use ($options): bool {
            if (!$info->isFile()) return false;
            $size = $info->getSize();
            if (($options['minSize'] ?? 0) > $size) return false;
            if (($options['maxSize'] ?? PHP_INT_MAX) < $size) return false;
            return true;
        };

        match ($mode) {
            'generator' => {
                return new class($iterator, $filter) implements IteratorAggregate {
                    private Iterator $it;
                    private callable $filter;
                    public function __construct(Iterator $it, callable $filter) { $this->it = $it; $this->filter = $filter; }
                    public function getIterator(): Traversable {
                        return new class($this->it, $this->filter) implements Iterator {
                            private Iterator $it;
                            private callable $filter;
                            private mixed $current = null;
                            private mixed $key = null;
                            public function __construct(Iterator $it, callable $filter) { $this->it = $it; $this->filter = $filter; }
                            public function current(): mixed { return $this->current; }
                            public function key(): mixed { return $this->key; }
                            public function next(): void {
                                foreach ($this->it as $path => $info) {
                                    if (($this->filter)($info)) {
                                        $this->key = $path;
                                        $this->current = [
                                            'path' => $path, 'name' => $info->getFilename(),
                                            'size' => $info->getSize(), 'mtime' => $info->getMTime(),
                                            'perm' => $info->getPerms(), 'ext' => $info->getExtension(),
                                        ];
                                        return;
                                    }
                                }
                                $this->current = null; $this->key = null;
                            }
                            public function valid(): bool { return $this->current !== null; }
                            public function rewind(): void { $this->next(); }
                        };
                    }
                };
            },
            'array' => {
                $result = [];
                foreach ($iterator as $path => $info) {
                    if (($filter)($info)) {
                        $result[$path] = [
                            'path' => $path, 'name' => $info->getFilename(),
                            'size' => $info->getSize(), 'mtime' => $info->getMTime(),
                            'perm' => $info->getPerms(), 'ext' => $info->getExtension(),
                        ];
                    }
                }
                return $result;
            },
            'spl' => {
                return $iterator; // 返回原始迭代器，調用者自行遍歷
            },
            default => throw new InvalidArgumentException("未知模式: $mode"),
        };
    }
}

// === 使用範例 ===
// 1. 流式處理大目錄 (推薦)
foreach (DirScanner::scan('/var/www/uploads', 'generator', ['pattern' => '/\.log$/i']) as $path => $info) {
    if ($info['mtime'] < strtotime('-30 days')) {
        unlink($path); // 刪除 30 天前的日誌
    }
}

// 2. 獲取數組 (小目錄)
$images = DirScanner::scan('/var/www/images', 'array', ['pattern' => '/\.(jpg|png|webp)$/i']);

// 3. 直接操作 SPL 迭代器 (需詳細文件信息)
$it = DirScanner::scan('/var/www/data', 'spl');
foreach ($it as $path => $info) {
    if ($info->isFile() && $info->getSize() > 100 * 1024 * 1024) {
        echo "大文件: $path\n";
    }
}

常見需求擴展

• 計算目錄總大小： array_reduce(DirScanner::scan($dir, 'array'), fn($sum, $f) => $sum + $f['size'], 0) (小目錄) 或 Generator 累加 (大目錄)。
• 查找重複文件 (MD5)： Generator 讀取文件流計算哈希，分組查找。
• 同步到對象存儲 (OSS/S3)： Generator 逐個上傳，支援斷點續傳、並發控制。
• 排除 .git/node_modules/vendor： RegexIterator 反向匹配 '/^((?!\.git|node_modules|vendor).)*$/' 或在 RecursiveDirectoryIterator 子類中重寫 hasChildren() 跳過目錄。
• Windows 長路徑 (>260 字符)： PHP 7.1+ 自動支援長路徑，前提是系統啟用「啟用 Win32 長路徑」組策略。

總結

大目錄、流式處理、內存敏感場景：首選 Generator 方案，內存恆定、首項產出極快、天然支援中斷。需豐富文件元數據、過濾排序、中小目錄：SPL 迭代器 功能最全、性能優於手寫遞歸。舊項目、極簡需求、兼容性第一：scandir 遞歸 仍可用。建議封裝為統一工具類 DirScanner::scan()，根據場景動態選擇模式，業務代碼零感知切換。