Weave Code
Finder Laravel Package
symfony/finder
Symfony Finder is a fluent API for locating files and directories. Filter by name, size, date, depth, permissions, and content; include/exclude paths; sort results; and iterate efficiently across local filesystems.
Finds files and directories via an intuitive fluent interface
Frequently asked questions about Finder
- How do I use Symfony Finder in a Laravel Artisan command to list all PHP files in a directory?
- Use `Finder::create()->in($path)->name('*.php')->files()` to get an iterable collection. Chain methods like `->depth('<= 2')` to limit recursion. For Artisan, inject the Finder instance via constructor or resolve it in the command’s `handle()` method. Example: `$finder = new Finder(); $files = $finder->in(storage_path('app'))->name('*.php')->files();`
- Does Symfony Finder support Laravel’s filesystem adapters (e.g., S3, FTP)?
- Yes, but indirectly. Finder works with local paths, so pair it with Laravel’s `Storage::disk('s3')->path()` to target remote files. Example: `$finder->in(Storage::disk('s3')->path('uploads'))->name('*.jpg')->files()`. For direct S3/FTP support, consider Spatie’s filesystem packages as a complement.
- What Laravel versions and PHP versions does Symfony Finder support?
- Finder requires PHP 8.1+ and is fully compatible with Laravel 9.x and 10.x. It’s framework-agnostic but aligns with Laravel’s modern stack. Check the [Symfony docs](https://symfony.com/doc/current/components/finder.html) for minor version notes, though it’s stable across recent Laravel releases.
- Can I exclude vendor/ and node_modules/ directories from Finder searches?
- Absolutely. Use `->exclude(['vendor', 'node_modules'])` or `->ignoreDotFiles(true)` for hidden directories. For recursive exclusions, chain `->depth('<= 3')` with `->notPath('/vendor/')`. Example: `$finder->in(base_path())->exclude(['vendor', 'node_modules'])->files()`.
- How does Finder’s performance compare to native PHP functions like glob() or scandir()?
- Finder is optimized for lazy iteration (via `IteratorAggregate`), avoiding memory spikes for large directories (e.g., `/storage/app`). Benchmarks show it’s comparable to `glob()` for simple queries but excels in complex filtering (e.g., size, permissions). For critical paths, test with `->depth()` and `->limit()` to control recursion.
- Is Symfony Finder thread-safe for Laravel queue jobs or concurrent CLI tasks?
- Yes, Finder is stateless and thread-safe. Each instance operates independently, making it safe for queue workers or parallel Artisan commands. Avoid sharing a single instance across threads unless you’re explicitly managing concurrency (e.g., with locks for shared paths).
- How can I test Finder logic in Laravel unit tests without hitting the filesystem?
- Mock the `Finder` class or use a temporary directory (e.g., `sys_get_temp_dir()`) with known files. Laravel’s `Storage::fake()` can simulate filesystem operations. Example: `$finder = $this->getMockBuilder(Finder::class)->disableOriginalConstructor()->getMock(); $finder->method('files')->willReturn([new SplFileInfo('test.txt')]);`
- What’s the best way to integrate Finder into a Laravel service provider for reusable file searches?
- Bind Finder to the container in `register()`: `$this->app->singleton(Finder::class, fn() => new Finder());`. Then inject it into classes via constructor or resolve it with `app(Finder::class)`. For shared configurations (e.g., ignored paths), use a config file and pass them to `Finder::create()->ignore([...])`.
- Are there alternatives to Symfony Finder for Laravel, and when should I use them?
- Alternatives include `SplFileInfo`/`RecursiveIteratorIterator` (for low-level control) or Spatie’s `laravel-finder` (Laravel-specific wrapper). Use Finder for fluent, readable queries; opt for `Spl*` for edge cases like custom file attributes. Spatie’s package adds Laravel integrations (e.g., `Storage` facade) but isn’t needed if you prefer Symfony’s native API.
- How do I handle symlinks in Finder to avoid infinite loops or security risks?
- Use `->followLinks()` to traverse symlinks or `->ignoreVCS(true)` to exclude them. For safety, combine with `->depth()` to limit recursion. Example: `$finder->in(base_path())->followLinks()->depth('<= 1')->files()`. Avoid `->followLinks()` in untrusted directories (e.g., user uploads) to prevent path traversal attacks.
Weaver
How can I help you explore Laravel packages today?