Php Autoload Override Laravel Package

Getting Started

1. Install via Composer: composer require --dev adriansuter/php-autoload-override
2. Enable autoloading override: In your bootstrap/autoload.php or test bootstrap file (e.g., tests/bootstrap.php), add:

   use Adriansuter\AutoloadOverride\AutoloadOverride;
   
   AutoloadOverride::enable();
   

3. First use case (testing): Suppose a class App\Service\EmailService depends on vendor/package/SenderInterface. To mock SenderInterface without modifying EmailService, register a stub before the dependency is instantiated:

   AutoloadOverride::register(\Vendor\Package\SenderInterface::class, \Tests\Stubs\MockSender::class);
   

   This ensures all future new SenderInterface() or instanceof SenderInterface checks in the app use your stub—ideal for unit/integration tests.

Implementation Patterns

• Test setup patterns: Use AutoloadOverride::register() at test bootstrap or per-test setup to inject mocks/stubs for real dependencies (e.g., external APIs, DB clients).

  // In TestCase::setUp()
  AutoloadOverride::register(\Monolog\Logger::class, \Tests\Stubs\NullLogger::class);
  

• Conditional overrides: Scope overrides to specific environments (e.g., if (app()->environment('testing'))) to avoid accidental prod impact.
• Legacy integration: When upgrading dependencies with breaking changes, override only the broken class in a migration layer:

  AutoloadOverride::register(\OldPackage\Service::class, \App\Legacy\CompatibilityService::class);
  

• Layered overrides: Multiple calls to register() for the same target override sequentially—last registration wins (useful for test isolation).

Gotchas and Tips

• Only affects new class instantiations: Overrides do not retroactively affect already-loaded classes. Ensure AutoloadOverride::enable() runs before Composer’s autoloader is invoked (typically at bootstrapping, before app/container initialization).
• FQN only: Overrides apply only to fully qualified class names (e.g., \Namespace\Classname). Aliased/namespaced references (use ...; new Class()) will resolve correctly if the FQN is used internally by Composer’s autoloader.
• Avoid production use: While safe for hotfixes, rely on this only for dev/test or critical emergency fixes—overrides complicate dependency tracing and may mask design debt.
• Debug tip: Use AutoloadOverride::getRegistered() to inspect active overrides during debugging.
• Conflict with static analysis: Tools like PHPStan or Psalm won’t respect runtime overrides—configure them to use override targets via stubFiles or parameters if type-checking mocks.