Container Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require league/container
   

   Requires PHP 8.3+.

2. Basic Setup:

   use League\Container\Container;
   
   $container = new Container();
   

3. First Use Case: Register a service with its dependencies:

   $container->add(\App\Services\UserService::class)
       ->addArgument(\App\Repositories\UserRepository::class);
   
   $container->add(\App\Repositories\UserRepository::class);
   
   $userService = $container->get(\App\Services\UserService::class);
   

Where to Look First

• Basic Usage for core functionality.
• Argument Types for performance optimizations.
• Service Providers for modularity.

Implementation Patterns

Core Workflows

1. Constructor Injection:

   $container->add(\App\Services\OrderService::class)
       ->addArgument(\App\Services\PaymentService::class)
       ->addArgument(\App\Services\ShippingService::class);
   

2. Interface Binding:

   $container->add(\App\Contracts\LoggerInterface::class, \App\Services\MonologLogger::class);
   

3. Aliases for Flexibility:

   $container->add('logger', \App\Contracts\LoggerInterface::class);
   $logger = $container->get('logger'); // Resolves to MonologLogger
   

Integration Tips

• Laravel Integration: Use League\Container alongside Laravel's service container by extending Illuminate\Container\Container or using it as a fallback delegate:

  $laravelContainer->delegate(new Container());
  

• Middleware/Event Dispatchers: Register handlers as services:

  $container->add(\App\Middleware\AuthMiddleware::class);
  $authMiddleware = $container->get(\App\Middleware\AuthMiddleware::class);
  

• Configuration Management: Bind config objects early:

  $container->add(\App\Config\AppConfig::class);
  

• Testing: Mock dependencies by overriding bindings in tests:

  $container->add(\App\Services\UserService::class, \App\Mocks\MockUserService::class);
  

Service Providers

Group related bindings in a provider:

use League\Container\ServiceProvider\AbstractServiceProvider;

class AppServiceProvider extends AbstractServiceProvider {
    protected $provides = [
        \App\Services\UserService::class,
        \App\Repositories\UserRepository::class,
    ];

    public function register() {
        $this->container->add(\App\Repositories\UserRepository::class)
            ->addArgument(\App\Database\Connection::class);

        $this->container->add(\App\Services\UserService::class)
            ->addArgument(\App\Repositories\UserRepository::class);
    }
}

Register the provider:

$container = new Container();
$container->addServiceProvider(new AppServiceProvider());

Gotchas and Tips

Pitfalls

1. Circular Dependencies:

   • Error: League\Container\Exception\NotFoundException when services depend on each other.
   • Fix: Refactor to use interfaces or shared dependencies (e.g., a DatabaseConnection shared across services).

2. Overly Broad Bindings:

   • Binding concrete classes to interfaces can lead to unexpected behavior if multiple implementations exist.
   • Fix: Use aliases or qualify bindings with namespaces:

     $container->add(\App\Contracts\LoggerInterface::class, \App\Services\MonologLogger::class);
     

3. Performance with addArgument():

   • Chaining addArgument() for complex constructors can slow resolution.
   • Fix: Use LiteralArgument for static values:

     use League\Container\Argument\LiteralArgument;
     
     $container->add(\App\Services\EmailService::class)
         ->addArgument(new LiteralArgument('contact@example.com'));
     

4. Delegate Containers:

   • Delegates are checked in registration order. If a service exists in multiple delegates, the first match wins.
   • Fix: Use explicit namespacing or prioritize delegates logically.

Debugging

• Enable Debug Mode:

  $container->debug(true); // Logs resolution steps to stderr
  

• Check for Missing Services:

  if (!$container->has(\App\Services\UserService::class)) {
      throw new \RuntimeException('Service not registered');
  }
  

• Inspect Bindings:

  $bindings = $container->getBindings();
  print_r($bindings);
  

Extension Points

1. Custom Argument Resolvers: Extend League\Container\Argument\ArgumentInterface for custom logic (e.g., environment-based values):

   class EnvArgument implements ArgumentInterface {
       public function __invoke(ContainerInterface $container) {
           return $_ENV['APP_DEBUG'] ?? false;
       }
   }
   

2. Inflectors: Modify resolved objects post-construction:

   $container->addInflector(function ($object) {
       if ($object instanceof \App\Services\UserService) {
           $object->setLogger($container->get('logger'));
       }
       return $object;
   });
   

3. PSR-11 Compliance: Implement Psr\Container\ContainerInterface for third-party integration:

   $container->delegate(new \Your\Psr11Container());
   

Configuration Quirks

• Immutable Bindings: By default, bindings are immutable. Use addShared() for singletons:

  $container->addShared(\App\Database\Connection::class);
  

• Autowiring: League/Container does not support autowiring out-of-the-box. Use a library like php-di/php-di or implement a custom resolver.

Performance Tips

• Prefer LiteralArgument for Primitives:

  $container->add(\App\Services\CacheService::class)
      ->addArgument(new LiteralArgument(3600)); // TTL
  

• Avoid Deep Nesting: Flatten complex dependency graphs where possible to reduce resolution overhead.

Laravel-Specific Notes

• Avoid Mixing Containers: Laravel’s container is optimized for its ecosystem. Use League/Container for:
  • Micro-services.
  • Testing (mocking Laravel’s container).
  • Non-web contexts (CLI, queues).
• Service Provider Conflicts: Ensure provider methods (e.g., register(), boot()) don’t clash with League’s ServiceProvider interface.