Di Laravel Package

Getting Started

Start by installing via Composer: composer require nette/di. Define services in a NEON config file (e.g., services.neon) using simple key-value syntax—Nette auto-detects services by type-hints and uses autowiring by default. For a basic setup:

services:
    - App\Model\UserRepository
    App\Service\EmailService: [@App\Model\UserRepository]
parameters:
    debugMode: %env.ADAPTIVE_DEBUG%

Then compile the container:

$compiler = new Nette\DI\Compiler();
$compiler->addConfig(['services' => [...]]); // or load from NEON
$container = $compiler->compile();

First use case: inject services via constructor autowiring in your classes—no configuration needed for most cases.

Implementation Patterns

• Autowiring-first design: Rely on type-hinted constructor dependencies—Nette resolves them automatically using PHP reflection.
• Explicit service definitions for non-trivial cases (e.g., custom factories, non-public constructors):

  services:
      cacheFactory:
          factory: App\Factory\CacheFactory::create()
          setup:
              - setTtl(3600)
  

• Dynamic parameters using %env.VAR% or parameters section—expanded at compile time for performance.
• Lazy services: Declare lazy: true to defer instantiation until first use:

  services:
      dbConnection:
          lazy: true
          factory: PDO
  

• Extension customization: Extend Nette\DI\CompilerExtension to register service definitions programmatically (e.g., bundling related services like Doctrine or logging).
• PHP 8 attributes: Use #[Nette\DI\Attributes\Inject] on properties/methods for injection where constructors are impractical (e.g., controllers).

Gotchas and Tips

• BC breaks in v3.2+: class option renamed to type in earlier versions; reverse in v3.1.8+. Verify config keys.
• Dynamic parameters misuse: %parameters% expands only static params—avoid for runtime values. Use getParameter() at runtime instead.
• Nullable/fallback type handling: Resolver may silently fail on ambiguous mixed or object type hints—explicit nullable types (?Type) or union types improve reliability.
• Circular references: If services depend on each other, inject containers or use lazy to break cycles: @self prefix for setup helps with self-references.
• Compilation caching: Always set cache directory (via ContainerBuilder::$tempDir)—reduces cold-start overhead from ~200ms to near-zero.
• Container debugging: Use Container::getService('debug Tracy') or inspect $container->getByType(...) outputs with Container::dump()—great for troubleshooting service definitions.
• Generics in autowiring: Since v3.2.5, prefer array<ClassName> or list<ClassName> annotations for collections over raw array.
• Named parameters only: Since v3.2.4, positional + named args are forbidden—ensure factories use consistent named params to avoid resolver errors.
• Performance tip: Mark rarely-used services as lazy and group infrequently loaded extensions in separate config files—reduces compiled container size and compile time significantly.