Class Map Generator Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Compatibility: Aligns with Laravel’s PSR-4 autoloading but provides granular control over class discovery. Ideal for:
  • Custom autoloaders (e.g., plugin systems, dynamic modules).
  • Performance-critical paths (e.g., CLI tools, migrations, scheduled jobs).
  • Legacy codebases with non-standard namespace structures.
• Leverages Laravel’s Ecosystem:
  • Integrates with app_path(), base_path(), or storage_path() for path resolution.
  • Can complement Laravel’s bootstrap/cache or vendor/composer/autoload_classmap.php.
  • Works alongside Laravel Mix, Vite, or Pint for build-time optimizations.
• Microservices/Modular Apps:
  • Enables runtime class loading for feature flags, A/B testing, or tenant-specific logic.
  • Supports sandboxed directories (e.g., user-uploaded code) with exclusion rules.

Integration Feasibility

• Low Friction:
  • No Laravel core changes required; pure PHP utility.
  • Composer-friendly: Install via composer require composer/class-map-generator.
  • Minimal dependencies: Only requires PHP 7.2+ and symfony/finder (v7/8).
• Key Integration Points:

  Use Case	Integration Strategy	Laravel Hooks
  CLI Performance	Pre-generate maps in bootstrap/app.php or a service provider.	register() in AppServiceProvider
  Dynamic Plugins	Scan plugin directories at runtime (e.g., PluginManager::load()).	Custom Facade or Manager Class
  CI/CD Optimization	Cache maps in GitHub Actions/GitLab CI before tests.	php artisan or custom script
  Legacy Refactoring	Generate maps for incremental modularization (e.g., app/Modules/).	php artisan make:module extension
  User-Uploaded Code	Scan sandboxed directories with exclusion rules.	Storage or Filesystem integration

• Example Workflow:

  // In AppServiceProvider::boot()
  $generator = new ClassMapGenerator();
  $generator->scanPaths(app_path('Modules'));
  $generator->scanPaths(storage_path('plugins'));
  $classMap = $generator->getClassMap();
  
  // Cache for 1 hour
  Cache::put('class_map', $classMap->getMap(), now()->addHour());
  
  // Custom autoloader
  spl_autoload_register(function ($class) use ($classMap) {
      if (isset($classMap[$class])) {
          require $classMap[$class];
      }
  });
  

Technical Risk

Key Questions

1. Performance:
   • How does the 30% scan speedup (v1.7.3) compare to Laravel’s native autoloading in our environment?
   • Should we cache maps in Redis or filesystem for runtime use?
2. Use Case Prioritization:
   • Which CLI tool (e.g., migrate, queue:work) will benefit most from pre-generated maps?
   • Should we use this for dynamic plugins or legacy refactoring first?
3. Error Handling:
   • How will we handle ambiguous classes in production (e.g., plugins with duplicate class names)?
4. CI/CD Impact:
   • Can we parallelize scans in GitHub Actions to reduce build time?
5. Maintenance:
   • Who will update the class maps when new classes are added (e.g., via make:model)?
6. Security:
   • How will we sandbox user-uploaded code to prevent path traversal or malicious scans?
7. Alternatives:
   • Does Laravel’s OPcache or get_declared_classes() suffice for our needs?
   • Would a custom Autoloader be more maintainable than this package?

Integration Approach

Stack Fit

• Laravel Core:
  • Autoloading: Replaces or augments composer dump-autoload for custom paths.
  • Service Providers: Ideal for boot-time initialization (e.g., AppServiceProvider).
  • Artisan Commands: Pre-generate maps in php artisan optimize:classmap (custom command).
• PHP Ecosystem:
  • Composer: Native integration via composer.json.
  • Symfony Finder: Compatible with Laravel’s Filesystem or Storage components.
  • PSR-4/PSR-0: Supports both but prioritizes PSR-4 for Laravel.
• Tooling:
  • CI/CD: Cache maps in GitHub Actions/GitLab CI for faster test suites.
  • Static Analysis: Feed maps to PHPStan, Psalm, or Pint for optimized runs.
  • IDE Plugins: Generate .phpstorm.meta.php or vs-code class maps dynamically.

Migration Path

Compatibility

• Laravel Versions:
  • Laravel 9+: Full compatibility (PHP 8.1+ may require polyfills for PHP 7.2 features).
  • Laravel 8: Works but may miss PHP 8.x features (e.g., enums).
  • Laravel 7: Limited (PHP 7.4+ recommended for stability).
• PHP Extensions:
  • Required: php_fileinfo, tokenizer (for parsing).
  • Optional: xdebug (for debugging ambiguous classes).
• Dependency Conflicts:
  • None critical; symfony/finder is widely used in Laravel.
  • Avoid version conflicts with composer/class-map-generator pinned to ^1.7.

Sequencing

1. Pre-requisite:
   • Ensure PHP 7.2+ (or target PHP 8.x for Laravel 9+).
   • Audit autoloading bottlenecks (e.g., php artisan tinker cold start).
2. Initial Integration:
   • Add to composer.json:

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

   • Generate a baseline map for app/:

     vendor/bin/php class-map-generator.php app/ > bootstrap/cache/classmap.php
     

3. Runtime Integration:
   • Load maps in AppServiceProvider: