README

概述

包 dynoser/walkdir 包含以下文件

• WalkDir.php - 带有多种迭代器和基准测试的初始版本
• WalkDirGlob.php - 仅使用 glob 函数的版本
• WalkDirTree.php - 经过先前开发经验改进的、在我看来最有效的版本

每个文件都包含一个类，没有依赖关系。（只需连接选定的一个文件即可使用）。推荐使用 WalkDirTree，因为它最简单、最有效，支持 php7 及以上版本。

class WalkDir

这是一个旧的、完全可行的类，在某些项目中使用，因此保留在包中。它提供静态函数 walkFiles 和 getFilesArr，允许从指定路径递归遍历文件（或以数组形式返回它们）。函数有参数 $mode，允许设置用于遍历的类型和迭代器。

• 0 - 基于函数 ScanDir 的遍历，
• 1 - 基于函数 Glob 的遍历，
• 2 - 使用 DI ( \DirectoryIterator )，
• 3 - 使用 GI ( \GlobIterator )

还有一个名为 benchMarkWalkFiles 的静态函数，可以比较指定目录遍历模式的速度。

class WalkDirGlob

与 WalkDir 不同，WalkDirGlob 类仅使用 glob 函数进行文件遍历，没有 $mode 参数。函数不是静态的，参数顺序也与 WalkDir 不兼容。逻辑和工作格式与 WalkDir 相同。需要 php8。

使用时，首先创建一个对象 new WalkDirGlob()，将路径数组、排除数组和其他参数传递给它。

然后可以调用对象的 walkFiles 方法以按掩码遍历文件，或调用 getFilesArr 以获取文件数组。

class WalkDirTree

该类首先根据指定路径构建目录树，然后根据已构建的目录树遍历文件。

这种方法在需要多次遍历同一“工作目录树”中的文件时，在性能上具有显著优势。

使用时，创建一个对象并传递用于构建目录树的文件夹数组。

可以创建一个空参数的对象，然后可以使用 addDirTree 方法单独添加路径。

要遍历文件，需要调用带有文件掩码的 walkFiles，这是一个生成器，它将根据已加载的目录树遍历文件。

请注意，生成器分别通过键和值传递基本路径和相对路径。要收集完整的文件名，只需连接键和值即可，请参阅下面的示例。

特性

• 高效的目录遍历： 支持排除路径和掩码的目录树构建。
• 文件过滤： 使用 glob 模式迭代文件以匹配特定文件类型。
• 缓存： 可选的文件列表缓存，以加快具有相同掩码的重复操作。
• 隐藏文件： 能够在遍历中包含隐藏文件和目录。

安装

要安装 dynoser/walkdir 软件包，可以使用 Composer

composer require dynoser/walkdir

使用

以下是如何使用 WalkDirTree 类遍历目录和检索文件的步骤指南。

步骤 1：创建 WalkDirTree 对象

您可以使用源路径列表和可选的排除路径列表创建一个 WalkDirTree 对象。在对象创建过程中，会构建目录树。

use dynoser\walkdir\WalkDirTree;

// Example paths
$sourcePaths = ["/path/to/dir1", "/path/to/dir2"];
$excludePaths = ["/path/to/dir1/exclude"];

$treeObj = new WalkDirTree($sourcePaths, $excludePaths, true);

• $sourcePaths：要包含在树中的目录列表。
• $excludePaths：要排除在树外的目录列表。
• true：可选的布尔值，用于包含隐藏目录。

步骤 2：遍历文件

一旦构建了树，您可以使用指定的掩码遍历文件。以下示例展示了如何遍历 PHP 文件。

foreach ($treeObj->walkFiles("*.php") as $basePath => $subDirFile) {
    $fillFilePath = $basePath . $subDirFile;
    echo "$fullFilePath\n";
}

• "*.php"：用于筛选文件的 glob 模式（例如，所有 PHP 文件）。

步骤 3：（可选）缓存

如果您启用缓存，具有相同掩码的后续调用将使用缓存结果，从而减少重新扫描目录的需求。

foreach ($treeObj->walkFiles("*.txt", true) as $basePath => $subDirFile) {
    $fillFilePath = $basePath . $subDirFile;
    echo "$fullFilePath\n";
}

• true：第二个参数启用缓存。

示例：使用 addDirTree

您可以在创建对象后添加更多目录到树中

$treeObj->addDirTree("/path/to/another/dir", ["/path/to/another/dir/exclude"]);

示例：准备路径数组

您可以使用 pathAbsPrepareArr 将相对路径或 glob 模式路径转换为绝对路径

$preparedPaths = WalkDirTree::pathAbsPrepareArr("/base/path", ["subdir", "*.pattern"]);
print_r($preparedPaths);

贡献

欢迎贡献！请提交问题或拉取请求到 GitHub 仓库。

本 README 提供了使用 dynoser/walkdir 包的全面指南，确保您可以在 PHP 项目中高效地遍历和管理目录及其内容。