Laravel Auto Discoverer Laravel Package

Technical Evaluation

Architecture Fit

• Laravel-Native Integration: The package is designed for Laravel (via spatie/laravel-auto-discoverer wrapper) and leverages Laravel’s service container, caching, and Artisan commands, making it a seamless fit for Laravel-based architectures.
• Modularity: The package’s core (spatie/php-structure-discoverer) is framework-agnostic, allowing it to integrate into non-Laravel PHP applications if needed, though Laravel-specific features (e.g., cache drivers, Artisan commands) are optimized for Laravel.
• Use Case Alignment: Ideal for:
  • Dynamic class/interface/enum discovery (e.g., for plugins, modular apps, or reflection-heavy workflows).
  • Runtime dependency resolution (e.g., finding all Arrayable models).
  • Code generation or analysis tools (e.g., auto-registering services).
• Caching Layer: Built-in caching (via Laravel’s cache or file-based) mitigates performance overhead in production, critical for large codebases.

Integration Feasibility

• Low Friction: Composer install + optional config publish (php artisan vendor:publish) is the only setup required. No database migrations or complex dependencies.
• Laravel Ecosystem Synergy:
  • Works with Laravel’s autoloader (PSR-4 compliant).
  • Cache drivers integrate with Laravel’s cache system (e.g., Redis, database).
  • Artisan commands (structure-scouts:cache, structure-scouts:clear) align with Laravel’s CLI workflows.
• Parallel Processing: Supports amphp/parallel for large-scale discovery, reducing runtime for monolithic apps.
• Customization: Extensible via:
  • Custom DiscoverCondition classes for complex filtering.
  • Custom cache drivers (e.g., for distributed systems).
  • Structure scouts for reusable discovery logic.

Technical Risk

• Performance in Large Codebases:
  • Risk: Initial discovery scans can be slow for projects with >10K files (even with parallel processing).
  • Mitigation: Use structure scouts + caching. Pre-warm caches during deployment (php artisan structure-scouts:cache).
  • Workaround: Limit scan directories via config (structure_scout_directories).
• Cache Invalidation:
  • Risk: Stale caches if files are added/removed outside the cache warm-up process.
  • Mitigation: Clear caches manually (php artisan structure-scouts:clear) or integrate with Laravel’s filesystem events.
• Dependency on Reflection:
  • Risk: Discovery relies on PHP’s reflection, which can be slow or fail in edge cases (e.g., dynamically generated classes).
  • Mitigation: Test with your app’s class structure; fall back to manual registration if needed.
• Laravel-Specific Features:
  • Risk: Non-Laravel PHP apps lose cache drivers/Artisan commands.
  • Mitigation: Use the underlying spatie/php-structure-discoverer package directly for non-Laravel projects.

Key Questions for TPM

1. Discovery Scope:
   • Will this replace manual class registration (e.g., for service providers, event listeners) or supplement it?
   • Are there directories (e.g., vendor/, node_modules/) that should be excluded by default?
2. Performance Requirements:
   • What’s the acceptable latency for discovery in production? (E.g., <100ms for cached queries.)
   • Should parallel processing be enabled by default, or is it only for CI/CD?
3. Cache Strategy:
   • How often will the codebase change? (Frequent changes may require more aggressive cache invalidation.)
   • Should cache warming be automated (e.g., via Laravel’s booted event)?
4. Use Cases:
   • Will this power dynamic features (e.g., plugin systems, auto-generated APIs) or static analysis (e.g., linting)?
   • Are there security implications (e.g., exposing class metadata to users)?
5. Testing:
   • How will you verify discovery accuracy (e.g., unit tests for specific class filters)?
   • Should discovery results be logged for debugging?

Integration Approach

Stack Fit

• Laravel Core: Fully compatible with Laravel 8+ (tested up to 2026-06-15). No breaking changes expected given Spatie’s maturity.
• Dependencies:
  • Required: PHP 8.1+, amphp/parallel (optional, for parallel scans).
  • Optional: Laravel cache drivers (Redis, database) for distributed caching.
• Tooling:
  • Artisan: Native support for cache management.
  • IDE: Works with PHPStorm/VSCode autocompletion for Discover methods.
  • CI/CD: Cache warming can be added to deployment pipelines.

Migration Path

1. Pilot Phase:
   • Install in a non-production environment: composer require spatie/laravel-auto-discoverer.
   • Publish config: php artisan vendor:publish --tag="structure-discoverer-config".
   • Test discovery in a single module (e.g., find all ShouldBeHidden models).
2. Incremental Rollout:
   • Replace manual class registrations (e.g., in AppServiceProvider) with dynamic discovery where possible.
   • Example:

     // Before
     $this->app->bind('model-registry', function () {
         return [ModelA::class, ModelB::class];
     });
     
     // After
     $this->app->bind('model-registry', function () {
         return Discover::in(app_path('Models'))->classes()->get();
     });
     

3. Cache Optimization:
   • Define structure scouts for critical discovery paths (e.g., UserModelScout).
   • Warm caches in bootstrap/app.php or a service provider:

     StructureScoutManager::cache(base_path('app'));
     

4. Monitoring:
   • Log discovery times to identify bottlenecks (e.g., using Laravel’s debugbar).
   • Set up alerts for cache misses in production.

Compatibility

• Backward Compatibility: No breaking changes in the package’s history. Laravel’s autoloader and reflection APIs are stable.
• Edge Cases:
  • Dynamic Classes: May fail for classes generated at runtime (e.g., via eval()). Test with your ORM (e.g., Eloquent) or API clients.
  • Namespaces: Ensure scanned directories align with your PSR-4 autoloader config.
  • PHP Attributes: Requires PHP 8.0+ for attribute-based discovery (e.g., withAttribute()).
• Alternatives: If discovery is too slow, consider:
  • Pre-generating a classes.json file during deployment.
  • Using symfony/finder for file-based filtering (lighter but less feature-rich).

Sequencing

1. Phase 1: Discovery Validation (1–2 sprints):
   • Implement a single discovery use case (e.g., auto-registering API resources).
   • Verify accuracy against manual lists (e.g., grep -r "class " app/).
2. Phase 2: Caching & Performance (1 sprint):
   • Set up structure scouts and cache warming.
   • Benchmark parallel processing for large directories.
3. Phase 3: Expansion (Ongoing):
   • Replace manual registrations with discovery where safe.
   • Add custom conditions for domain-specific logic (e.g., implementing(Serializable::class)).
4. Phase 4: Monitoring (Continuous):
   • Track cache hit ratios and discovery latency.
   • Automate cache invalidation for critical paths (e.g., via updated filesystem events).

Operational Impact

Maintenance

• Proactive:
  • Cache Management: Schedule regular cache warming (e.g., post-deployment) to avoid stale data.
  • Config Updates: Monitor ignored_files and structure_scout_directories as the codebase evolves.
  • Dependency Updates: Watch for spatie/php-structure-discoverer updates (MIT license allows easy forks if needed).
• Reactive:
  • Cache Invalidation: Clear caches when:
    • Running composer dump-autoload.
    • Adding/removing directories from structure_scout_directories.
    • Deploying new classes/interfaces/enums.
  • Debugging: Use DiscoveredStructure objects (via full()) to inspect metadata for issues.

Support

• Developer Onboarding:
  • Document common discovery patterns (e.g., "How to find all HasApiTokens models").
  • Provide examples for:
    • Structure scouts (reusable discovery logic).
    • Custom conditions (e.g., filtering by namespace).
    • Parallel processing (when to enable/disable).
• Troubleshooting:
  • Common Issues:
    • "No results found": Verify scan directories and file permissions.
    • "Slow discovery": Check for large directories or disabled caching.
    • "Stale cache": Ensure structure-scouts:clear is run post-deployment.
  • Logging: Add debug logs for discovery queries (e.g., using Laravel’s `Log::