Class Map Generator Laravel Package

Product Decisions This Supports

• Performance-Critical Laravel Workflows: Pre-generate class maps to eliminate autoloading overhead in CLI tools (e.g., Artisan commands, migrations, or queue workers), reducing cold-start latency by 30%+ (aligned with Laravel’s performance roadmap).
• Modular Laravel Architecture: Enable dynamic plugin/theme loading without modifying composer.json (e.g., for SaaS platforms like Laravel Nova or Laravel Jetstream), supporting the Laravel Package Development initiative.
• Legacy System Refactoring: Isolate monolithic Laravel apps into microservices by granularly scanning and mapping dependencies, reducing technical debt (e.g., for enterprises migrating from Laravel 5.x to Laravel 10).
• Build vs. Buy for Internal Tools: Replace custom class-scanning logic in IDE plugins, static analyzers (PHPStan/Psalm), or security tools with a maintained, dependency-light solution (MIT license).
• CI/CD Optimization: Cache class maps in pipelines (e.g., GitHub Actions, Laravel Envoyer) to accelerate test suites and deployments, directly impacting DevOps efficiency (e.g., reduce CI runtime by 20% for large codebases).
• Custom Autoloading Use Cases:
  • Dynamic Feature Flags: Load classes conditionally (e.g., Feature::enabled('experimental') ? new ExperimentalClass() : ...).
  • User-Uploaded Code: Safely scan sandboxed directories (e.g., for Laravel-based SaaS platforms with custom logic).
  • A/B Testing: Runtime class switching for experimental features without redeploying (e.g., toggle AnalyticsV2 vs. AnalyticsV1).

When to Consider This Package

Adopt When

• Autoloading is a measurable bottleneck:
  • CLI tools (e.g., php artisan migrate) exceed 500ms cold-start SLOs.
  • APIs or microservices have high latency due to autoloading (e.g., >10% of request time).
• Dynamic class loading is required:
  • Plugins, themes, or user-generated code need custom resolution (e.g., Laravel-based marketplaces or SaaS platforms).
  • Runtime-generated classes (e.g., dynamic proxies or code generation) can’t use composer dump-autoload.
• Legacy code lacks PSR-4 compliance:
  • Non-standard namespaces or file structures require manual class mapping (e.g., migrating from Laravel 4.x).
• Internal tools need class scanning:
  • Custom IDE helpers, static analyzers, or security scanners (e.g., replacing Laravel IDE Helper).
  • Build-time optimizations (e.g., pre-generating maps for Pint, PHPStan, or Psalm).
• CI/CD pipelines are slow:
  • Test suites or deployments are blocked by autoloading (e.g., >5min for Laravel + Pest).
  • Laravel Forge/Envoyer deployments have high boot time due to missing class caches.
• Ambiguous class resolution is a pain point:
  • Namespace collisions or duplicate classes break autoloading (e.g., in monorepos or multi-vendor plugins).

Look Elsewhere If

• Default Laravel autoloading suffices:
  • No custom logic needed; composer dump-autoload --optimize is adequate.
• PHP version <7.2:
  • Hard requirement blocks adoption (target PHP 8.1+ for Laravel 9+).
• Real-time reflection is needed:
  • Use get_declared_classes() or OPcache for dynamic environments (e.g., Laravel Livewire).
• Zero maintenance risk is critical:
  • Last release: 2026-05-05 (monitor GitHub activity; no recent stars/contributors).
• Class maps are static:
  • Laravel’s built-in caching (bootstrap/cache) may suffice for most apps.
• Dynamic classes (e.g., eval()) can’t be pre-scanned:
  • This tool is file-system bound and won’t work for runtime-generated code (e.g., Laravel’s dynamic facades).

How to Pitch It (Stakeholders)

For Executives

*"This package directly addresses [X]’s performance and scalability goals by eliminating autoloading delays in Laravel, with measurable ROI:

• Faster CLI tools: Reduce php artisan cold starts from 2s → 500ms for [Y] admin panel, boosting developer productivity by 30%.
• SaaS scalability: Enable dynamic plugins (e.g., for [Z] platform) without bloating composer.json, cutting maintenance costs by 20%.
• Legacy migration: Isolate dependencies in [A] monolith to enable modular upgrades with minimal risk. It’s a lightweight, MIT-licensed solution with 30% faster scans (v1.7.3) and no vendor lock-in. Quick win: Pilot for [B] feature to validate impact before wider adoption."*

For Engineering

*"We can use this to:

1. Optimize Laravel boot time by pre-generating class maps (e.g., for [D] microservice), reducing cold starts.
2. Support dynamic plugins (e.g., [E] system) without hacking composer.json or core Laravel.
3. Avoid reinventing the wheel: This is Composer’s own tool, used by thousands of projects (e.g., Symfony, Drupal). Tradeoffs:

• Pros: Fine-grained control, works with PSR-4, no Laravel core changes.
• Cons:
  • Manual class map management (mitigate with CI/CD hooks).
  • No native Laravel integration (e.g., Facades, Helpers).
  • PHP 7.2+ only (blocker for PHP 8.1+ apps). Recommendation: Start with [F] feature to measure impact (e.g., CI/CD speedup or plugin loading).

For Developers

*"This replaces manual composer dump-autoload tweaks with a programmable class scanner. Key use cases:

• Pre-generate maps in CI for faster test suites (e.g., Laravel Pest):

  composer require composer/class-map-generator
  

• Scan user-uploaded code safely (e.g., for [G] platform):

  $generator = new ClassMapGenerator();
  $generator->scanPaths(storage_path('user_uploads'));
  $map = $generator->getClassMap()->getMap();
  

• Debug ambiguous classes (e.g., namespace collisions):

  foreach ($classMap->getAmbiguousClasses() as $symbol => $paths) {
      log("Ambiguous: $symbol in " . implode(', ', $paths));
  }
  

How to integrate:

1. Add to composer.json:

   "require": {
       "composer/class-map-generator": "^1.7"
   }
   

2. Generate maps in bootstrap/app.php or a service provider:

   $classMap = ClassMapGenerator::createMap(app_path('Modules'));
   // Cache or use dynamically.
   ```"