PHP Symfony Finder怎么组合文件名与目录过滤

我在整理 PHP 项目的资源目录时，最容易失控的不是“能不能找到文件”，而是规则叠加后到底筛中了哪一批文件：文件名要是 *.php，目录还要落在 src/，同时不能进入缓存和遗留目录。Symfony Finder 适合把这些条件写成一条可读的链式配置。

官方地址：https://symfony.com/doc/current/components/finder.html

先把扫描范围和基线记录下来

Finder 的位置条件由 in() 提供，实际项目里建议先固定一个搜索根，再把文件类型和目录条件写在同一个对象上。这样复查时可以明确：数量变化来自搜索根、文件名规则还是目录排除，而不是把所有问题都归咎于正则。

先安装组件：

# 安装独立的 Finder 组件，运行 PHP 文件时还需要 Composer 自动加载器
composer require symfony/finder

示例把 projectDir 当成项目根目录，扫描范围、命中数量和首个相对路径都只作为记录字段，不代表本文已经在你的目录中执行。

files()
    // 先把搜索根固定下来，后面的 path() 都相对于它匹配。
    ->in($projectDir);

if (!$finder->hasResults()) {
    echo "没有找到文件\n";
} else {
    // 记录实际迭代数量；这里不写死示例目录的结果。
    echo '命中数量：'.iterator_count($finder)."\n";
}

name() 和 path() 要分别负责什么

name() 匹配文件名，可以接收 glob、字符串、正则或数组；path() 匹配路径中的目录片段。两者同时出现时，读者可以把规则理解成“文件名和路径都要满足”，而不是把目录名误当成文件名。

files()
    // 文件名只保留 PHP 源文件。
    ->name('*.php')
    // 路径条件限定在 src 目录，不是只看 basename。
    ->path('src/')
    // 排除旧目录，避免遗留代码进入结果。
    ->notPath('src/Legacy')
    ->in(__DIR__);

foreach ($finder as $file) {
    // relativePathname 便于日志和后续规则使用相对路径。
    echo $file->getRelativePathname()."\n";
}

这里的职责可以压缩成一张表：

exclude() 和 notPath() 的边界

如果一个目录根本不应该被扫描，可以用 exclude()；如果目录已经属于搜索范围，但某段路径不应出现在最终结果里，可以用 notPath()。前者强调遍历边界，后者强调匹配结果边界。目录名参数相对于 in() 指定的位置。

files()
    ->name(['*.php', '*.inc'])
    // cache 相对于搜索根，目录不需要继续遍历。
    ->exclude(['var/cache', 'vendor'])
    // Legacy 仍在搜索根下，但不进入结果集合。
    ->notPath('src/Legacy')
    ->in(__DIR__);

foreach ($finder as $file) {
    // SplFileInfo 提供文件名、真实路径和相对路径等信息。
    printf("%s => %s\n", $file->getRelativePathname(), $file->getRealPath());
}

实际项目中可以先记录搜索根、过滤规则和命中数量，再抽样记录相对路径。这样当结果突然变少时，可以分别检查 exclude() 是否过宽、notPath() 是否匹配到了更高层目录，以及 name() 是否漏掉了扩展名。

几个容易让结果失真的细节

• Finder 有状态。方法调用会改变当前对象；要做两次独立搜索，创建两个 Finder 或先复制公共配置后再修改。
• 路径统一用正斜杠。path() 的路径表达使用 /，不要把 Windows 反斜杠直接写进匹配条件。
• 多处 in() 要记录位置。多个搜索位置会合并迭代结果，转换为数组时要留意键名可能重复，避免把不同根目录的文件覆盖掉。
• 排序不是免费操作。sortByName() 等排序需要收集全部匹配项；目录很大时，先缩小 name()、path() 和排除范围，再决定是否排序。

常见问题

name() 能直接匹配目录名吗？

本文场景中把它当作文件名条件使用。目录范围应交给 in()、exclude() 或路径条件表达，先用 files() 排除目录结果会更清楚。

path() 和 notPath() 可以同时使用吗？

可以。先用 path() 收窄目标目录，再用 notPath() 排除其中的遗留子路径，规则更容易按“允许范围”和“拒绝范围”解释。

为什么 iterator_count() 后 foreach 没有结果？

计数会消耗当前迭代器视图，若要同时计数和遍历，先用 iterator_to_array() 保存结果，或先遍历并自行累加；大目录则要权衡内存成本。