Di Laravel Package

Technical Evaluation

Architecture Fit

• PSR-11 Compliance: Aura.Di fully adheres to the PSR-11 Container Interface, making it a drop-in replacement for Laravel’s built-in Illuminate/Container (which also implements PSR-11). This ensures seamless integration with Laravel’s service container ecosystem.
• Modern PHP Features: Supports PHP 8.0+, including attributes (PHP 8.0+) for dependency injection configuration, aligning with Laravel’s adoption of PHP 8.x.
• Serialization: Unique feature of serializable containers enables caching compiled configurations, reducing bootstrap overhead—a valuable optimization for Laravel’s heavy dependency graph.
• Attribute-Based DI: Leverages #[Service], #[Instance], #[Value], and #[Blueprint] for declarative configuration, reducing boilerplate compared to Laravel’s traditional bind()/singleton() methods.
• Interface/Trait Awareness: Resolves dependencies from interfaces and traits, improving flexibility in Laravel’s polymorphic service binding scenarios (e.g., repositories, event dispatchers).

Integration Feasibility

• Laravel Compatibility:
  • Replaces Illuminate/Container with Aura.Di’s Container while maintaining PSR-11 compatibility.
  • Laravel’s service provider bootstrapping (e.g., AppServiceProvider) can adapt to Aura.Di’s attribute-based or programmatic configuration.
  • Service context (e.g., app()->make()) remains unchanged, but under the hood uses Aura.Di’s resolver.
• Migration Path:
  • Low-risk: Start by replacing the container in non-critical modules (e.g., custom packages) before full adoption.
  • Hybrid Approach: Use Aura.Di alongside Laravel’s container via CompositeContainer (supported in Aura.Di 4.x+) for gradual migration.
• Key Laravel Integrations:
  • Service Providers: Replace bind()/singleton() with Aura.Di’s #[Service] or programmatic set().
  • Middleware/Events: Leverage Aura.Di’s lazy loading for performance-critical components.
  • Facades: No changes needed; facades delegate to the container interface.

Technical Risk

• Breaking Changes:
  • Laravel’s app() helper and Illuminate/Container facade are tightly coupled to the container implementation. Replacing the container requires facade/method overrides or a custom facade (e.g., Aura\Di\Container).
  • Service Context: Laravel’s app()->make() uses contextual binding; Aura.Di’s contextual parameters must be manually configured if relying on this feature.
• Performance Trade-offs:
  • Compiled Blueprints: Aura.Di’s pre-compilation (ContainerCompileInterface) reduces runtime overhead but adds build-time complexity (e.g., generating class maps).
  • Lazy Loading: Aura.Di’s lazyGet() is more granular than Laravel’s lazy containers but may require adjustments in eager-loading strategies (e.g., AppServiceProvider::boot()).
• Tooling Dependencies:
  • Class Map Generation: Requires composer/class-map-generator for scanning annotated classes, adding a build dependency.
  • PHP 8.0+: Dropped support for PHP 7.x may require runtime environment updates.

Key Questions

1. Service Provider Compatibility:
   • How will Laravel’s deferred providers (e.g., defer: true) interact with Aura.Di’s compiled blueprints?
   • Can Aura.Di’s #[Service] attributes replace Laravel’s bindWhen() or conditional binding?
2. Performance Impact:
   • What is the memory/CPU overhead of compiling blueprints vs. Laravel’s runtime resolution?
   • How does Aura.Di’s serialization compare to Laravel’s cached containers (bootstrap/cache/services.php)?
3. Debugging & Tooling:
   • Will Laravel’s tinker or debugbar work seamlessly with Aura.Di?
   • Are there IDE tooling gaps (e.g., PhpStorm’s DI inspection) when using attribute-based configuration?
4. Ecosystem Lock-in:
   • Does Aura.Di’s attribute system conflict with Laravel’s custom annotations (e.g., #[Route])?
   • How does this affect third-party Laravel packages that hook into the container?

Integration Approach

Stack Fit

• Laravel Core:
  • Container Replacement: Swap Illuminate/Container with Aura\Di\Container in config/app.php:

    'container' => [
        'bindings' => Aura\Di\Container::class,
        'contextual' => Aura\Di\ContextualContainer::class,
    ],
    

  • Service Provider Adaptation: Replace bind() calls with:

    $this->container->set(MyService::class, fn() => new MyService(deps));
    // OR via attributes:
    #[Service(MyService::class)]
    class MyServiceConfig {}
    

• Laravel Extensions:
  • Middleware: Use Aura.Di’s lazy resolution for middleware dependencies:

    #[Service]
    class AuthMiddleware implements Middleware {
        public function __construct(#[Service] AuthManager $auth) {}
    }
    

  • Events: Leverage Aura.Di’s event listeners with attribute-based wiring.
• Testing:
  • Replace Mockery/PHPUnit container mocks with Aura.Di’s AbstractContainerConfigTest.

Migration Path

1. Phase 1: Isolated Adoption
   • Replace the container in custom packages or non-core modules.
   • Use CompositeContainer to bridge Laravel’s and Aura.Di’s containers:

     $laravelContainer = new Illuminate\Container\Container();
     $auraContainer = new Aura\Di\Container($laravelContainer);
     

2. Phase 2: Hybrid Configuration
   • Migrate service providers to use Aura.Di’s attributes or programmatic API.
   • Example: Convert bind('App\Services\Foo', fn() => new Foo()) to:

     #[Service(App\Services\Foo::class)]
     class FooConfig {}
     

3. Phase 3: Full Replacement
   • Override Laravel’s container facade:

     class AuraContainerFacade extends Illuminate\Support\Facades\Facade {
         protected static function getFacadeAccessor() { return 'aura.container'; }
     }
     

   • Update config/app.php to use Aura\Di\Container as the default.

Compatibility

• PSR-11: Full compatibility ensures Laravel’s dependency resolution (e.g., app()->make()) works unchanged.
• Laravel-Specific Features:
  • Contextual Binding: Aura.Di’s contextual parameters can replicate Laravel’s behavior but require manual setup.
  • Tagging: Aura.Di lacks Laravel’s tagged services; workarounds include custom attributes or container extensions.
  • Singleton Groups: Aura.Di’s #[Instance] can replace Laravel’s singleton() but may need custom logic for grouped singletons.
• Tooling:
  • Laravel Mix/Vite: No impact.
  • Horizon/Queues: May require container facade overrides for dependency injection.

Sequencing

1. Replace Container Implementation:
   • Update config/app.php and container facade.
2. Migrate Service Providers:
   • Convert bind()/singleton() to Aura.Di’s API.
3. Adapt Core Services:
   • Update auth, caching, queue workers to use Aura.Di’s lazy loading.
4. Test & Optimize:
   • Benchmark compiled blueprints vs. runtime resolution.
   • Validate third-party package compatibility.

Operational Impact

Maintenance

• Configuration Complexity:
  • Pros: Attribute-based DI reduces boilerplate (e.g., no bind() calls).
  • Cons: Compiled blueprints require build-time scanning, adding complexity to CI/CD pipelines.
• Debugging:
  • Aura.Di’s detailed exception messages improve debugging over Laravel’s generic container errors.
  • Tooling Gaps: Lack of native Laravel IDE support for Aura.Di attributes may require custom plugins.
• Dependency Updates:
  • Aura.Di’s active development (PHP 8.4/8.5 support) aligns with Laravel’s roadmap.
  • Breaking Changes: Major versions (e.g., 5.x) may require Laravel-specific adjustments.

Support

• Community:
  • Aura Framework has a smaller ecosystem than Laravel; support may require self-service or custom extensions.