Finder Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require nette/finder
   

   (Note: While archived, the package remains functional for legacy projects.)

2. Basic Usage:

   use Nette\Finder;
   
   $finder = new Finder();
   $files = $finder->in(__DIR__)->files();
   foreach ($files as $file) {
       echo $file->getPathname() . "\n";
   }
   

3. First Use Case:

   • Asset Discovery: Locate all .js or .css files in a public/assets directory for bundling.
   • Configuration Files: Scan for .php or .yaml files in config/ to validate or merge them.

Implementation Patterns

Core Workflows

1. Filtering Files/Directories:

   // Find all PHP files in a directory (recursive)
   $finder->in('src')->name('*.php')->files();
   
   // Exclude vendor/ and tests/
   $finder->in('src')->exclude(['vendor', 'tests']);
   

2. Sorting and Grouping:

   // Sort by modification time (newest first)
   $finder->sortBy('mtime')->reverse();
   
   // Group by extension
   $filesByExt = [];
   foreach ($finder->in('public')->files() as $file) {
       $filesByExt[$file->getExtension()][] = $file;
   }
   

3. Integration with Laravel:

   • Service Provider:

     public function register()
     {
         $this->app->singleton('finder', function () {
             return new Finder();
         });
     }
     

   • Artisan Commands:

     $finder = app('finder');
     $views = $finder->in(resource_path('views'))->files();
     

4. Dynamic Paths:

   • Use Laravel’s storage_path(), public_path(), or base_path() for cross-environment consistency:

     $finder->in(public_path('uploads'))->name('*.jpg');
     

Gotchas and Tips

Pitfalls

1. Archived Package:

   • No active maintenance; avoid for new projects. Prefer alternatives like symfony/finder (used by Laravel under the hood).
   • Example migration:

     composer require symfony/finder
     

     Replace Nette\Finder with Symfony\Component\Finder\Finder.

2. Performance:

   • Avoid deep recursion (->depth('> 10')) on large directories (e.g., node_modules). Use ->depth('== 0') for top-level files.
   • Cache results if reused:

     $cachedFiles = cache()->remember('finder_files', now()->addHours(1), function () {
         return iterator_to_array($finder->in('storage')->files());
     });
     

3. Path Handling:

   • Windows Line Endings: Use ->ignoreDotFiles(false) to avoid hidden files (e.g., .gitignore).
   • Case Sensitivity: On case-insensitive filesystems (e.g., Windows), ->name('*.PHP') may miss files. Use ->name('*.php') consistently.

4. Iterator Behavior:

   • Finder returns a Traversable object. Convert to array with iterator_to_array() or loop directly:

     foreach ($finder->files() as $file) { ... } // Correct
     $array = $finder->files()->toArray(); // ❌ Error: No toArray() method
     

Tips

1. Laravel-Specific Shortcuts:

   • Combine with Laravel’s helpers:

     $finder->in(app_path())->name('*.php')->filter(function ($file) {
         return str_contains(file_get_contents($file), 'namespace App');
     });
     

2. Extension Points:

   • Custom Filters: Use ->filter() for logic not covered by built-in methods:

     $finder->filter(function ($file) {
         return $file->getMTime() > strtotime('-1 month');
     });
     

   • Events: Trigger events when files are found (e.g., via Laravel’s Events facade):

     foreach ($finder->files() as $file) {
         event(new FileFound($file));
     }
     

3. Debugging:

   • Log paths for debugging:

     $finder->in('app')->files()->map->getPathname()->dump();
     

   • Check for hidden files with ->ignoreDotFiles(true) temporarily.

4. Alternatives:

   • For Laravel, leverage native methods:

     // Instead of Finder, use:
     File::allFiles(app_path());
     File::directories(database_path());
     

```markdown
---
**Note**: Replace `nette/finder` with `symfony/finder` in production code. The patterns above translate directly to Symfony’s Finder API.