Class Finder Laravel Package

Getting Started

Install via Composer (composer require danog/class-finder) and start by scanning a directory for classes implementing a known interface or extending an abstract class. The most common first use is discovering event listeners or plugin classes:

use Danog\ClassFinder\ClassFinder;

$finder = new ClassFinder();
$listeners = $finder->findClasses(app_path('Listeners'), 'App\Contracts\EventListener');

This returns fully-qualified class names as strings. Verify autoloading works by ensuring App\Listeners\* maps correctly in composer.json. No config files—just instantiating and scanning.

Implementation Patterns

• Dynamic Service Registration: In a service provider, scan app/Actions for classes implementing HandlesRequestInterface, then bind them to a repository or container using a macroable tag.
• Plugin System Bootstrapping: Loop over directories under plugins/*, detect all classes implementing PluginInterface, load metadata from static methods (e.g., ::getName()), and register routes/permissions.
• CLI Tooling: In Artisan commands, scan test directories for *Test.php classes matching a convention, then generate coverage reports or execute filtered suites.
• Event Dispatcher Wiring: Combine with Laravel’s event system: find handler classes (e.g., implements MessageHandlerInterface) and map them to event classes via ::getSubscribedEvents() static method.
  Workflow: Scan → Filter (via ReflectionClass) → Instantiate → Register. Always wrap discovery in caching (e.g., file hash–based cache).

Gotchas and Tips

• No Auto-loading: This package only finds classes—it does not load them. Always call composer dump-autoload after adding new classes, and avoid new directly on returned class names until autoloading is confirmed.
• Trait/Interface Limitations: The package detects classes using a trait or implementing an interface, but does not recursively resolve inherited traits or interfaces in parent chains. Use ReflectionClass::getTraits() and getInterfaces() post-discovery.
• Symlink Pitfall: On Unix systems, ClassFinder follows symlinks by default—critical when scanning storage/ or vendor/. Use ClassFinder::setFollowSymlinks(false) for production scans.
• Performance: For large apps (>500 classes), add caching keyed on directory checksum (e.g., md5_file('composer.json') . '-' . spl_object_hash($finder)). Laravel’s Cache facade integrates cleanly.
• PHP 8+ Attributes: While reflection-based, it does not parse attributes by default. Extend Scanner or post-process with getAttributes() to detect tagged classes (e.g., #[Handler]).
• Unknown Repo Risk: Since the repository isn’t public on Packagist, verify stability manually (clone source, run tests). Consider forking to add tests and pin to a private Git repository if adopted.