Laminas Loader Laravel Package

Getting Started

Minimal Steps

1. Installation: Add the package to your composer.json under "require":

   composer require laminas/laminas-loader:^2.12
   

   Run composer dump-autoload to generate the autoloader.

2. First Use Case: Use the ClassMapAutoloader for static class mapping or AutoloaderFactory for dynamic PSR-4 autoloading:

   use Laminas\Loader\ClassMapAutoloader;
   
   $loader = new ClassMapAutoloader([
       'App\LegacyClass' => __DIR__ . '/legacy/LegacyClass.php',
   ]);
   $loader->register();
   

3. Where to Look First:

   • Official Documentation for API references.
   • src/ directory in the package for core classes (ClassMapAutoloader, AutoloaderFactory, PluginClassLoader).
   • Laravel’s bootstrap/app.php or composer.json for integration points.

Implementation Patterns

Usage Patterns

1. Static Class Mapping: Use ClassMapAutoloader for classes not following PSR-4 (e.g., legacy code):

   $loader = new ClassMapAutoloader([
       'Vendor\Legacy\Class' => __DIR__ . '/path/to/Class.php',
   ]);
   $loader->register();
   

2. PSR-4 Autoloading: Leverage AutoloaderFactory for dynamic PSR-4 loading (similar to Composer):

   use Laminas\Loader\AutoloaderFactory;
   
   $factory = new AutoloaderFactory();
   $autoloader = $factory->createAutoloader([
       'App\\' => __DIR__ . '/app/',
   ]);
   $autoloader->register();
   

3. Plugin Loading: Use PluginClassLoader for loading plugins dynamically (e.g., service providers):

   $pluginLoader = new PluginClassLoader();
   $pluginLoader->addNamespace('App\Plugins');
   $pluginLoader->register();
   

Workflows

1. Laravel Integration:

   • Register the Laminas loader after Laravel’s default autoloader in bootstrap/app.php:

     $loader = new \Laminas\Loader\ClassMapAutoloader($classMap);
     $loader->register();
     

   • Use for fallback loading (e.g., legacy classes not covered by PSR-4).

2. Modular Applications:

   • Load vendor-specific classes (e.g., Zend\* or Laminas\*) via ClassMapAutoloader to avoid namespace collisions:

     $loader = new ClassMapAutoloader([
         'Zend\Legacy\Class' => __DIR__ . '/vendor/zend/legacy/Class.php',
     ]);
     

3. Dynamic Class Resolution:

   • Use AutoloaderFactory to generate autoloaders at runtime (e.g., for microservices):

     $autoloader = (new AutoloaderFactory())->createAutoloader([
         'Service\\' => __DIR__ . '/services/',
     ]);
     

Integration Tips

1. Avoid Duplicates: Ensure the Laminas loader does not overlap with Laravel’s ClassLoader. Use spl_autoload_register() with a priority flag:

   $loader->register(true); // Set to true to prepend (higher priority)
   

2. Composer Autoload: Combine with Composer’s autoloader for hybrid setups:

   {
       "autoload": {
           "psr-4": {
               "App\\": "app/",
               "Legacy\\": "legacy/"
           },
           "classmap": ["legacy/classmap.php"]
       }
   }
   

3. Testing: Mock the autoloader in PHPUnit:

   $this->getMockBuilder(\Laminas\Loader\ClassMapAutoloader::class)
        ->disableOriginalConstructor()
        ->setMethods(['loadClass'])
        ->getMock();
   

Gotchas and Tips

Pitfalls

1. Namespace Collisions:

   • Avoid registering Laminas\* or Zend\* classes if they conflict with Laravel’s dependencies. Use unique prefixes (e.g., App\Legacy\Laminas\*).

2. Performance Overhead:

   • Multiple autoloaders can slow down class resolution. Benchmark with Xdebug or Blackfire before production use.

3. PHP Version Mismatches:

   • While the package supports PHP 8.4, Laravel’s core may have stricter constraints. Test thoroughly in your target PHP version.

4. Archived Status:

   • The package is abandoned (per README). Use only if you’re already dependent on it or need legacy support. Consider alternatives like symfony/class-loader for new projects.

Debugging

1. Class Not Found:

   • Verify the class map or PSR-4 paths are correct. Use spl_autoload_functions() to inspect registered autoloaders:

     print_r(spl_autoload_functions());
     

2. Autoloader Conflicts:

   • Disable other autoloaders temporarily to isolate issues:

     spl_autoload_unregister([$loader, 'loadClass']);
     

3. Composer Cache Issues:

   • Clear Composer’s cache if autoloading fails:

     composer dump-autoload --optimize --no-dev
     

Config Quirks

1. Priority Handling:

   • Use spl_autoload_register($loader, true) to prepend the Laminas loader (higher priority) or omit true to append (lower priority).

2. ClassMap Generation:

   • Generate classmap.php for static mapping:

     composer dump-autoload --classmap-authoritative
     

3. Laravel Service Providers:

   • Register the loader in a service provider’s boot() method:

     public function boot()
     {
         $loader = new \Laminas\Loader\ClassMapAutoloader($this->getClassMap());
         $loader->register();
     }
     

Extension Points

1. Custom Autoloader: Extend Laminas\Loader\AutoloaderInterface for custom logic:

   class CustomAutoloader implements AutoloaderInterface {
       public function loadClass($class) {
           // Custom logic here
       }
   }
   

2. Plugin System: Use PluginClassLoader to dynamically load plugins:

   $pluginLoader = new PluginClassLoader();
   $pluginLoader->addNamespace('App\Plugins');
   $pluginLoader->register();
   

3. Integration with Laravel Events: Trigger autoloader events in Laravel’s AppServiceProvider:

   public function boot()
   {
       if ($this->app->environment('local')) {
           $loader = new \Laminas\Loader\ClassMapAutoloader($this->getLocalClassMap());
           $loader->register();
       }
   }