Di Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aura/di
   

2. Basic Container Initialization:

   use Aura\Di\Container;
   use Aura\Di\ContainerBuilder;
   
   $builder = new ContainerBuilder();
   $container = $builder->newInstance();
   

3. First Use Case - Manual Binding:

   $container->set('myService', function() {
       return new MyService();
   });
   
   $service = $container->get('myService');
   

4. Configuration via Class:

   use Aura\Di\ContainerConfig;
   
   class AppConfig implements ContainerConfig
   {
       public function define(Aura\Di\Container $di)
       {
           $di->params[\MyService::class]['param1'] = 'value1';
           $di->set('myService', \MyService::class);
       }
   }
   
   $builder = new ContainerBuilder();
   $container = $builder->newInstance(new AppConfig());
   

Where to Look First

• Documentation for detailed usage.
• ContainerBuilder for creating and configuring containers.
• Container for retrieving services and managing bindings.
• Attributes (PHP 8.0+) for declarative configuration (e.g., #[Service], #[Instance]).

Implementation Patterns

Core Workflows

1. Attribute-Based Configuration (PHP 8.0+)

Use attributes to define services declaratively:

use Aura\Di\Attribute\Service;

#[Service]
class MyService {
    public function __construct(private string $name) {}
}

// Scan and compile attributes into blueprints:
$builder = new ContainerBuilder();
$builder->scan([__DIR__ . '/src']);
$container = $builder->newInstance();

Key Attributes:

• #[Service]: Marks a class as a service.
• #[Instance]: Injects an existing instance.
• #[Value]: Injects a scalar value.
• #[Blueprint]: Compiles a class into a blueprint.

2. Lazy Loading

Defer instantiation until first use:

$container->lazy('expensiveService', function() {
    return new ExpensiveService();
});

$service = $container->lazyGet('expensiveService'); // Instantiated on first call

Lazy Types:

• LazyValue: Scalar values.
• LazyCallable: Callables.
• LazyArray: Arrays of lazy values.

3. Contextual Parameters

Pass parameters dynamically:

$di->params[\MyService::class]['context'] = $context;
$service = $di->get(\MyService::class);

4. Producer Pattern

Reuse instances across requests (e.g., for HTTP handlers):

$builder->setProducer('requestHandler', function() {
    return new RequestHandler();
});

5. Compilation

Pre-generate blueprints for performance:

$builder->scan([__DIR__ . '/src']);
$builder->compileToFile(__DIR__ . '/var/blueprints.php');
$container = include __DIR__ . '/var/blueprints.php';

Integration Tips

Laravel Integration

1. Service Provider Setup:

   use Aura\Di\ContainerBuilder;
   use Illuminate\Support\ServiceProvider;
   
   class AuraDiServiceProvider extends ServiceProvider
   {
       public function register()
       {
           $builder = new ContainerBuilder();
           $builder->scan([app_path('Config')]);
           $this->app->singleton('aura.di', function() use ($builder) {
               return $builder->newInstance();
           });
       }
   }
   

2. Binding Laravel Services:

   $container = app('aura.di');
   $container->set('router', function() {
       return app('router');
   });
   

3. Resolving Dependencies:

   $service = $container->get('myService');
   

Testing

• Use AbstractContainerConfigTest for unit testing configurations:

  use Aura\Di\AbstractContainerConfigTest;
  
  class MyConfigTest extends AbstractContainerConfigTest
  {
      protected function getConfigClass(): string
      {
          return AppConfig::class;
      }
  }
  

Scanning Directories

Automatically discover and configure classes in a directory:

$builder->scan([
    __DIR__ . '/src',
    __DIR__ . '/config',
]);

Gotchas and Tips

Pitfalls

1. Auto-Resolution Locking:

   • Avoid calling get() or newInstance() before finishing configuration.
   • Use lazyGet() or lazyNewInstance() to defer locking.

2. Circular Dependencies:

   • Aura.Di throws CircularReferenceException for circular dependencies.
   • Resolve by restructuring dependencies or using set() with a factory.

3. Attribute Scanning Quirks:

   • Ensure scanned classes are autoloadable.
   • Non-existent parent classes may break scanning (fixed in v5.0.4).

4. Serialization:

   • Containers with closures cannot be serialized.
   • Use compileToFile() for persistent containers.

5. PHP 8 Attributes:

   • Attributes like #[Service] must target TARGET_CLASS or TARGET_PROPERTY (fixed in v5.0.0-alpha.2).

Debugging Tips

1. Enable Debug Mode:

   $builder->setDebug(true);
   

   • Throws detailed exceptions for missing services or parameters.

2. Inspect Blueprints:

   $blueprints = $builder->getBlueprints();
   print_r($blueprints);
   

3. Check Class Map:

   $classMap = $builder->getClassMap();
   if (!$classMap->hasClass(MyService::class)) {
       // Class not found in scan
   }
   

4. Lazy Resolution Issues:

   • Use lazyLazy() to create directly invokable lazies:

     $lazy = $container->lazyLazy('service');
     $instance = $lazy(); // Invokes lazy
     

Extension Points

1. Custom Attribute Configs: Implement AttributeConfigInterface to handle custom attributes:

   use Aura\Di\AttributeConfigInterface;
   
   class MyAttributeConfig implements AttributeConfigInterface
   {
       public function configure(Aura\Di\Container $di, array $attributes)
       {
           // Custom logic
       }
   }
   

2. Container Compilation Hooks: Implement ContainerCompileInterface:

   use Aura\Di\ContainerCompileInterface;
   
   class MyCompiler implements ContainerCompileInterface
   {
       public function compile(Aura\Di\ContainerBuilder $builder)
       {
           // Modify blueprints before compilation
       }
   }
   

3. Custom Resolver: Replace the default resolver for advanced control:

   $builder->setResolver(new MyCustomResolver());
   

Configuration Quirks

1. Attribute Targets:

   • #[Service], #[Instance], and #[Value] must target TARGET_PROPERTY for constructor promotion (PHP 8.0+).

2. Scanner Exclusions:

   • Use #[CompileNamespace] to exclude namespaces from compilation.

3. Class Map Updates:

   • Files removed from the filesystem may linger in the class map (fixed in v5.0.2).
   • Clear the class map manually if needed:

     $builder->getClassMap()->clear();
     

4. PHP 8.4+ Attributes:

   • Yielding attributes for non-existent classes may fail (fixed in v5.0.9).

Performance Tips

1. Compile for Production:

   $builder->compileToFile(__DIR__ . '/var/production_blueprints.php');
   

   • Reduces runtime overhead by pre-generating blueprints.

2. Avoid Lazy Overhead:

   • Use set() for singletons or frequently used services.

3. Batch Scanning:

   • Scan directories once during bootstrap and reuse the builder.