platform/doc/container_gap_analysis.md

Container Package Gap Analysis

Overview

This document analyzes the gaps between our Container package's actual implementation and our documentation, identifying areas that need implementation or documentation updates. It also outlines the migration strategy to achieve full Laravel compatibility.

Related Documentation

• See Container Package Specification for current implementation
• See Laravel Compatibility Roadmap for overall status
• See Foundation Integration Guide for integration patterns
• See Testing Guide for testing requirements

Implementation Status

Status Note: This status aligns with our Laravel Compatibility Roadmap. See there for overall framework status.

1. Core Features

Implemented

✓ Basic dependency injection
✓ Service location
✓ Auto-wiring
✓ Parent/child containers
✓ Named singletons
✓ Lazy singleton registration
✓ Async dependency resolution

Partially Implemented

~ Contextual binding (basic structure)
~ Method injection (basic reflection)
~ Tagged bindings (basic tagging)

Not Implemented

- Advanced contextual binding features
  * Instance-based context
  * Multiple contexts
  * Context inheritance

- Advanced method injection features
  * Parameter validation
  * Optional parameters
  * Named parameters

- Advanced tagged binding features
  * Tag inheritance
  * Tag groups
  * Tag conditions

Migration Strategy

Integration Note: This migration strategy follows patterns from Foundation Integration Guide. See there for detailed integration examples.

Phase 1: Internal Restructuring (No Breaking Changes)

1. Extract Binding Logic

// Move from current implementation:
class Container {
  final Map<Type, Object> _bindings = {};
  void bind<T>(T instance) => _bindings[T] = instance;
}

// To new implementation:
class Container {
  final Map<Type, Binding> _bindings = {};
  
  void bind<T>(T Function(Container) concrete) {
    _bindings[T] = Binding(
      concrete: concrete,
      shared: false,
      implementedType: T
    );
  }
}

2. Add Resolution Context

class Container {
  T make<T>([dynamic context]) {
    var resolutionContext = ResolutionContext(
      resolvingType: T,
      context: context,
      container: this,
      resolutionStack: {}
    );
    
    return _resolve(T, resolutionContext);
  }
}

Phase 2: Add New Features (Backward Compatible)

1. Contextual Binding

class Container {
  final Map<Type, Map<Type, Binding>> _contextualBindings = {};
  
  ContextualBindingBuilder when(Type concrete) {
    return ContextualBindingBuilder(this, concrete);
  }
}

2. Method Injection

class Container {
  dynamic call(
    Object instance,
    String methodName, [
    Map<String, dynamic>? parameters
  ]) {
    var method = reflector.reflectInstance(instance)
      .type
      .declarations[Symbol(methodName)];
      
    var resolvedParams = _resolveMethodParameters(
      method,
      parameters
    );
    
    return Function.apply(
      instance.runtimeType.getMethod(methodName),
      resolvedParams
    );
  }
}

3. Tagged Bindings

class Container {
  final Map<String, Set<Type>> _tags = {};
  
  void tag(List<Type> types, String tag) {
    _tags.putIfAbsent(tag, () => {}).addAll(types);
  }
  
  List<T> taggedAs<T>(String tag) {
    return _tags[tag]?.map((t) => make<T>(t)).toList() ?? [];
  }
}

Phase 3: Performance Optimization

Performance Note: These optimizations align with our Laravel Compatibility Roadmap performance targets.

1. Add Resolution Cache

class Container {
  final ResolutionCache _cache = ResolutionCache();
  
  T make<T>([dynamic context]) {
    var cached = _cache.get<T>(context);
    if (cached != null) return cached;
    
    var instance = _resolve<T>(T, context);
    _cache.cache(instance, context);
    return instance;
  }
}

2. Add Reflection Cache

class Container {
  final ReflectionCache _reflectionCache = ReflectionCache();
  
  dynamic call(Object instance, String methodName, [Map<String, dynamic>? parameters]) {
    var methodMirror = _reflectionCache.getMethod(
      instance.runtimeType,
      methodName
    ) ?? _cacheMethod(instance, methodName);
    
    return _invokeMethod(instance, methodMirror, parameters);
  }
}

Backward Compatibility Requirements

Note

: These requirements ensure compatibility while following Laravel Compatibility Roadmap guidelines.

1. Maintain Existing APIs

// These must continue to work:
container.make<T>();
container.makeAsync<T>();
container.has<T>();
container.hasNamed();
container.registerFactory<T>();
container.registerSingleton<T>();
container.registerNamedSingleton<T>();
container.registerLazySingleton<T>();

2. Preserve Behavior

// Parent/child resolution
var parent = Container(reflector);
var child = parent.createChild();
parent.registerSingleton<Service>(service);
var resolved = child.make<Service>();  // Must work

// Named singletons
container.registerNamedSingleton('key', service);
var found = container.findByName('key');  // Must work

// Async resolution
var future = container.makeAsync<Service>();  // Must work

Implementation Priority

Priority Note: These priorities align with our Laravel Compatibility Roadmap.

1. High Priority

• Complete contextual binding implementation
• Add parameter validation to method injection
• Implement tag inheritance

2. Medium Priority

• Add cache integration
• Improve error handling
• Add event system integration

3. Low Priority

• Add helper methods
• Add debugging tools
• Add performance monitoring

Development Guidelines

1. Getting Started

Before implementing features:

1. Review Getting Started Guide
2. Check Container Package Specification
3. Follow Testing Guide
4. Use Foundation Integration Guide

2. Implementation Process

For each feature:

1. Write tests following Testing Guide
2. Implement following Laravel Compatibility Roadmap
3. Document following Getting Started Guide
4. Integrate following Foundation Integration Guide

Next Steps

Would you like me to:

1. Start implementing Phase 1 changes?
2. Create detailed specifications for Phase 2?
3. Design the caching system for Phase 3?