Laravel Auto Discoverer Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • Reflection Alternative: Provides a lightweight, declarative alternative to PHP’s native Reflection* classes, reducing boilerplate for type/structure discovery.
  • Laravel-Native: Designed for Laravel’s ecosystem (e.g., cache integration, Artisan commands), aligning with Laravel’s conventions (e.g., app_path(), service providers).
  • Extensible: Supports custom conditions, caching strategies, and parallel processing, making it adaptable to complex use cases (e.g., dynamic feature flags, plugin systems).
  • Metadata-Rich: Returns detailed structure metadata (e.g., inheritance chains, attributes), useful for introspection-heavy applications (e.g., ORMs, testing frameworks).
  • Performance: Built-in caching and parallel scanning optimize runtime performance, critical for large codebases.

• Fit for:

  • Dynamic Discovery: Applications requiring runtime class/enum/trait discovery (e.g., plugin architectures, dynamic modules).
  • Code Analysis Tools: IDE plugins, static analyzers, or testing tools needing to inspect code structure.
  • Meta-Programming: Frameworks or libraries that generate code or enforce contracts (e.g., validation rules, event listeners).
  • Laravel-Specific: Use cases like auto-registering service providers, discovering policies, or implementing custom middleware.

• Misalignment:

  • Overhead for Simple Use Cases: If the application only needs basic reflection (e.g., checking if a class exists), native PHP reflection may suffice with less complexity.
  • Cache Management: Requires explicit cache warming in production, adding operational overhead for deployments.

Integration Feasibility

• Laravel Compatibility:

  • Seamless: Leverages Laravel’s service container, cache system, and Artisan commands. The published config and structure-scouts:cache command integrate cleanly.
  • Service Provider Hooks: Can be bootstrapped in a provider (e.g., for package-level scouts) or via facade bindings.
  • Testing: Mockable and testable due to its fluent interface and dependency injection (e.g., cache drivers).

• Non-Laravel PHP:

  • Possible but Manual: Requires manual setup of cache drivers and directory paths. Less "batteries-included" than in Laravel.
  • Use Case: Suitable for standalone PHP applications needing structured discovery without a framework.

• Key Integration Points:

  • Discovery Triggers: Hook into events (e.g., booted, registered) to cache scouts on demand.
  • Dynamic Loading: Useful for lazy-loading components (e.g., plugins) based on discovered classes.
  • Validation: Enforce contracts at runtime (e.g., "All request classes must implement ValidatesRequests").

Technical Risk

• Cache Invalidation:

  • Risk: Stale caches if files are modified but caches aren’t cleared. Mitigate by:
    • Automating cache warming on deploy (e.g., via post-deploy hooks).
    • Using file-watchers to invalidate caches dynamically (advanced).
  • Tradeoff: Cache invalidation adds complexity; weigh against discovery performance gains.

• Parallel Processing:

  • Risk: Resource contention in shared environments (e.g., serverless, low-memory instances). Mitigate by:
    • Limiting parallel workers (parallel(10) instead of default 50).
    • Testing under load to identify bottlenecks.

• Custom Conditions:

  • Risk: Complex conditions may introduce bugs if not thoroughly tested. Mitigate by:
    • Writing unit tests for custom DiscoverCondition classes.
    • Using the closure-based approach for simple conditions to avoid class overhead.

• Dependency Bloat:

  • Risk: Adds amphp/parallel for parallel scanning (~1MB). Mitigate by:
    • Only requiring it if parallel scanning is needed (composer require-dev for testing).
    • Evaluating if parallel scanning is critical for your use case.

• Laravel Version Lock:

  • Risk: Package may not support older Laravel versions (e.g., <9.x). Mitigate by:
    • Checking the Spatie Laravel package compatibility table.
    • Using ^ in composer.json to allow minor updates.

Key Questions for TPM

1. Use Case Clarity:

   • What specific problem does this solve? (e.g., "Auto-discover all event listeners implementing ShouldQueue.")
   • Is this replacing manual reflection or adding new functionality?

2. Performance Requirements:

   • How large is the codebase? (Parallel scanning may be critical for >10K files.)
   • What’s the acceptable tradeoff between discovery speed and cache invalidation complexity?

3. Operational Constraints:

   • Can the team automate cache warming in CI/CD? (e.g., via GitHub Actions or Deployer.)
   • Are there restrictions on file system access for caching? (e.g., serverless environments.)

4. Maintenance:

   • Who will own cache invalidation logic? (DevOps, developers, or a separate tool?)
   • How will custom conditions be tested and documented for future maintainers?

5. Alternatives:

   • Would native reflection or a simpler package (e.g., phpDocumentor/reflection-docblock) suffice?
   • Are there Laravel-specific alternatives (e.g., laravel/scout for search, but not discovery)?

6. Scaling:

   • Will this be used in microservices? (Cache consistency across services may be tricky.)
   • How will it handle dynamic class loading (e.g., plugins, compiled PHP)?

Integration Approach

Stack Fit

• Laravel Ecosystem:

  • Primary Fit: Ideal for Laravel applications due to native integration (cache, Artisan, service container).
  • Recommended Stack:
    • Cache: Use Laravel’s default cache (file, redis, or database) for scouts.
    • Parallel Scanning: Enable if discovering >5K files (benchmark to confirm ROI).
    • Testing: Use NullDiscoverCacheDriver in tests to avoid filesystem I/O.
  • Avoid: Overusing for trivial cases (e.g., checking if a single class exists).

• Non-Laravel PHP:

  • Fit: Useful but requires manual setup (e.g., custom cache driver, directory paths).
  • Recommended Stack:
    • Cache: FileDiscoverCacheDriver for simplicity.
    • Parallel Scanning: Only if performance is critical.
    • Testing: Mock the Discover class or use in-memory cache drivers.

• Complementary Tools:

  • IDE Plugins: Integrate with PHPStorm/Rector for static analysis.
  • Testing: Pair with Pest/PHPUnit for runtime contract enforcement.
  • CI/CD: Use cache warming as a build step.

Migration Path

Compatibility

• Laravel Versions:

  • Supported: 9.x–11.x (check Spatie’s compatibility table).
  • Legacy: May require backporting or forking for Laravel 8.x.

• PHP Versions:

  • Supported: 8.1+ (parallel scanning requires 8.0+).
  • Polyfill: Use amphp/parallel for PHP 7.4+ if needed.

• Dependencies:

  • Critical: illuminate/support (for Laravel cache), amphp/parallel (optional).
  • Conflicts: None reported; Spatie packages are dependency-stable.

• Custom Code:

  • Assumptions: Assumes PSR-4 autoloading (standard in Laravel).
  • Edge Cases: May struggle with:
    • Dynamically generated classes (e.g., via eval or create_function).
    • Namespaced classes outside app/ (configure structure_scout_directories).

Sequencing

1. Discovery Scope:

   • Start with a narrow scope (e.g., app/Commands) before global discovery.
   • Use ignored_files to exclude vendor/third-party code.

2. Cache Strategy:

   • Development: Disable caching (`'cache' => ['driver' => NullDiscoverCacheDriver::class