symfony finder 是轻量独立的 php 文件查找组件，通过链式调用简化搜索逻辑；支持按类型、路径、名称、大小、时间等条件筛选，条件间为“且”关系。
Symfony Finder 是一个轻量、独立、功能完整的 PHP 文件查找组件，不依赖整个 Symfony 框架，只需 Composer 引入即可在任何 PHP 项目中使用。它用链式调用替代手写递归遍历，让文件搜索逻辑清晰、可读、易维护。
安装与初始化
通过 Composer 安装：
composer require symfony/finder
代码中引入并创建实例（推荐用 Finder::create()）：
use Symfony\Component\Finder\Finder; $finder = Finder::create();
这是所有操作的起点，后续所有筛选、排序、限制都基于这个对象链式调用。
基础筛选：按类型、路径、名称
必须明确指定是查文件还是目录，否则默认包含两者：
- →files()：只匹配普通文件
- →directories()：只匹配目录
- →in($path)：设置搜索根目录，支持字符串或数组（多个路径）
-
→name('*.log')：按通配符匹配文件名，支持多模式：
['*.php', '*.js'] - →name('/^config_.*\.yml$/')：用正则表达式精确控制命名规则
- →path('src/Controller')：要求路径中包含指定子串；→notPath('tests') 可排除
进阶过滤：大小、时间、内容
这些方法可自由组合，条件之间是“且”关系：
-
→size('> 500K')：支持单位 B / K / M / Mi / Gi，如
'>= 1Mi'表示 ≥1 MiB -
→date('since 3 days ago')：相对时间表达式，也支持绝对范围：
['>= 2026-05-01', ' -
→contains('ERROR')：搜索文件正文是否含指定字符串；支持正则：
→contains('/throw\s+new\s+\w+Exception/') - →exclude(['vendor', 'node_modules'])：跳过指定子目录，大幅提升大型项目搜索速度
- →ignoreVCSIgnored(true)：自动跳过 .gitignore 等版本控制忽略的文件
结果处理与优化
Finder 返回的是 SplFileInfo 对象迭代器，不是数组，因此适合大目录场景（内存友好）：
- 遍历时直接获取路径：
$file->getRealPath()或$file->getPathname() - 按需排序：
→sortByName(true)（启用自然排序）、→sortByModifiedTime()、→reverseSorting() - 限制数量：
→limit(10)获取前 10 个匹配项 - 深度控制：
→depth(' 表示最多进入子目录 2 层（即当前层为 0）
