萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 目錄遞迴掃描完全指南:三種實作方式、效能比較與最佳實踐

三種核心實作方式

方式一:傳統 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 字元):啟用長路徑支援或縮短目錄結構

總結建議

  1. 現代專案 (PHP 7.4+) **首選 SPL 迭代器** + Generator 模式
  2. 簡單腳本、相容舊版 → `scandir()` + 遞迴函數
  3. 需模式匹配 → `glob()`
  4. 永遠使用 `DIRECTORY_SEPARATOR` 或 `/`,避免硬編碼 `\`
  5. 大量檔案處理務必使用迭代器避免記憶體耗盡
copyright © 萬盛學電腦網 all rights reserved