Sofinder Symfony Laravel Package

Getting Started

• Install with Composer: composer require sohophp/sofinder. Laravel's package auto-discovery registers the service provider and facade, so no manual wiring is needed on Laravel 9+.

• If you're on a non-standard Laravel skeleton, register Sohophp\SoFinder\SoFinderServiceProvider::class and alias the facade in config/app.php.

• Publish the config only if you need to override defaults (root directories, ignore patterns, hidden-file handling):

  php artisan vendor:publish --tag=sofinder-config
  

• First use case: enumerate files in a project directory with a fluent, Symfony-Finder-style chain:

  use Sohophp\SoFinder\Facades\SoFinder;
  
  $phpFiles = SoFinder::in(base_path('app'))
      ->name('*.php')
      ->files();
  
  foreach ($phpFiles as $file) {
      dump($file->getRealPath());
  }
  

• Read first: the README's fluent API table (it's the fastest reference for in(), name(), notName(), path(), depth(), files()/directories()) and the published config/sofinder.php. Most day-to-day questions are answered by those two.

Implementation Patterns

Fluent finder chains

The core workflow mirrors Symfony Finder. Build chains incrementally — start with in(), narrow with name()/path()/size(), then terminate with files(), directories(), or an iterator. Chains are immutable enough that you can store a base "finder" and clone/extend it per use case.

Facade vs. dependency injection

• Use the SoFinder facade for quick scripts, Artisan commands, and tinker.
• Inject the underlying contract/service via the container when unit-testing your own classes so you can swap it with a fake or mock.

Console & scheduler integration

Wrap finder queries in Artisan commands for common ops (e.g., "list stale cache files", "audit media directory"). Because the finder is IteratorAggregate, you can stream large trees with foreach instead of loading everything into memory.

Chunking and lazy iteration

For large trees, prefer iterating the finder directly or with your own chunk helper rather than calling ->files()->toArray(). Pair with lazy()/generators to keep memory flat on logs or storage folders.

Integration tips

• Compose with Laravel's filesystem (Storage) only when you actually need a disk abstraction; SoFinder operates on real paths, so use Storage::path() to bridge.
• For config-driven roots, resolve paths with config('sofinder.roots') and feed each into a chain — this makes multi-tenant or per-disk scans trivial.
• Combine with artisan schedule:run for periodic cleanup jobs (log rotation, orphaned uploads).

Gotchas and Tips

• Hidden files are typically excluded by default. If you're scanning dotfiles (.env, .htaccess), explicitly enable them — otherwise the finder silently skips them.
• Globs are not regexes. name('*.php') is a glob; use path() with a regex or Symfony's notName/name regex helpers when matching substrings. Mixing the two is a frequent source of empty results.
• Symlinks and mount boundaries: default behavior usually does not follow symlinks. For deploy trees that use symlinked current/ dirs, enable symlink following or resolve real paths first.
• Case sensitivity depends on the host FS. A pattern that works on macOS (case-insensitive APFS) can fail on Linux CI. Normalize or use case-insensitive helpers when portability matters.
• Depth and excluded directories: always exclude vendor, node_modules, and storage/framework on app-wide scans — otherwise traversal cost explodes. Put these in config/sofinder.php so it's a one-time fix.
• Path normalization: results may be absolute/relative depending on whether you used in(base_path()) or in('app'). Normalize before comparing or storing paths.
• Debugging empty results: drop the filters one at a time — start with only in() and files(), confirm it finds anything, then re-add name/path/depth to find the culprit.
• Extension points: the service provider binds the finder contract, so you can swap in a custom implementation for virtual filesystems or remote drives by rebinding in a service provider.
• Version note: v1.0.0 is a stable cut following v1.0.0-rc.1 with no documented breaking changes relative to the RC, so RC adopters should upgrade cleanly. Pin to ^1.0 and watch for a 1.1 with API additions.