萬盛學電腦網

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

PHP 列出目錄內容的現代化實作:SPL 迭代器、遞歸、過濾、排序完整指南

前言

傳統 opendir/readdir 寫法繁瑣且易出錯(需手動跳過 . ..、處理路徑拼接)。PHP SPL (Standard PHP Library) 提供了強大的迭代器,讓目錄遍歷變得優雅、高效、可組合。本文詳細介紹 DirectoryIterator、RecursiveDirectoryIterator、GlobIterator 等類別的實戰用法。

基礎:DirectoryIterator(單層目錄)

<?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()。

遞歸遍歷:RecursiveDirectoryIterator + RecursiveIteratorIterator

<?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";
}

進階過濾:RegexIterator、CallbackFilterIterator

只列出 PHP 檔案

$phpFiles = new RegexIterator(
    new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($root, RecursiveDirectoryIterator::SKIP_DOTS)
    ),
    '/\.php$/i'
);

foreach ($phpFiles as $file) {
    echo $file->getPathname() . "\n";
}

自訂邏輯過濾(如:排除 vendor、node_modules、大於 1MB)

$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) {
    // 已過濾
}

GlobIterator:支援萬用字元模式

// 找出所有子目錄下的 *.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) { /* ... */ }

排序:配合 Iterator 使用

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');

效能與記憶體考量

方法記憶體速度適用場景
DirectoryIteratorO(1) 固定快單層列表、即時處理
RecursiveIteratorIteratorO(深度)快樹狀遍歷、遞歸處理
iterator_to_array + usortO(N) 全部載入中需完整排序的中小目錄
glob()O(N) 全部載入慢簡單模式匹配、小目錄

實戰:建立檔案清單 JSON API

<?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)替代。

copyright © 萬盛學電腦網 all rights reserved