Psalm Psr Container Plugin Laravel Package

Getting Started

1. Install the plugin:

   composer require --dev lctrs/psalm-psr-container-plugin
   

2. Enable in Psalm config (psalm.xml):

   <plugins>
       <pluginClass class="Lctrs\PsalmPsrContainerPlugin\Plugin"/>
   </plugins>
   

3. First use case: Run Psalm on code using $container->get(SomeService::class). Previously returning mixed, Psalm now infers the actual return type if the service is registered (e.g., via a container config file or reflection-based metadata).

Implementation Patterns

• Type-safe service retrieval: Define service types via @psalm-return or @psalm-param annotations in your container’s get() method or rely on auto-discovered class-levelDocBlock type hints. The plugin infers types from:
  • Constructor type hints of service factories/factories classes
  • @psalm-return on factory __invoke() or get() methods
  • Explicit @psalm-type declarations mapped to service IDs (optional but powerful)
• Container-aware refactoring: When renaming or restructuring service classes, Psalm will surface violations like get(OldClassName::class) where no mapping exists.
• Hybrid containers: Works well with Symfony’s ServiceLocator, Symfony DependencyInjection (via ContainerInterface), or custom PSR-11 implementations. Just ensure your container’s get() method is correctly typed as returning mixed or object.

Gotchas and Tips

• False negatives with dynamic service IDs: If you use string literals derived from variables (e.g., get($serviceId)), Psalm can’t resolve the type—this plugin only handles static service IDs (string literals or class constant strings).
• Missing type info? Add @psalm-type annotations to your container’s get() method, or define a psalm-container.php config file (see docs) to map service IDs → types explicitly:

  // psalm-container.php
  return [
      'Service\EmailSenderInterface' => Service\SmtpEmailSender::class,
  ];
  

• Plugin doesn’t infer all container behavior: It doesn’t handle auto-wiring edge cases or advanced service aliases. Use @psalm-return hints on factory classes when ambiguity remains.
• Debug tip: Run Psalm with --debug to see why a type was inferred — look for PsalmPsrContainerPlugin entries in the output.
• Strongest impact in large apps: Benefits scale with codebase size and DI usage — small scripts see minimal gain; full-stack apps with 50+ services gain significant safety.