Props Dic Laravel Package

Product Decisions This Supports

• Developer Experience (DX) Enhancement: Props enables IDE-friendly dependency injection with type hints, autocompletion, and static analysis, directly addressing pain points in large codebases. This aligns with roadmap initiatives to reduce debugging time and improve onboarding velocity for new developers.
• Build vs. Buy Decision: Avoids reinventing a DI container while providing superior IDE integration compared to generic solutions like Pimple or Laravel’s container. Ideal for teams already using PSR-11 but frustrated with opaque container APIs (e.g., $container->get('service')).
• Key Use Cases:
  • Legacy Code Modernization: Replace magic strings in DI calls (e.g., 'user_repository') with typed properties ($container->userRepository), reducing runtime errors and improving maintainability.
  • Modular Architectures: Enforce explicit dependency boundaries via container subclasses (e.g., AuthServices, PaymentServices) with IDE support for cross-module navigation.
  • Testing and Static Analysis: Tools like Psalm or PHPStan can verify dependency contracts at compile time, catching misconfigurations early.
  • Pimple Migration: Teams using Pimple can gradually adopt Props for property access without rewriting DI logic, leveraging Props\Pimple.

When to Consider This Package

• Adopt if:
  • Your team prioritizes IDE tooling (PHPStorm, VSCode) and static analysis over raw performance (Props has negligible overhead vs. other containers).
  • You use PHP 8.1+ and already comply with PSR-11 (or are willing to migrate).
  • Your DI container is scattered across files (e.g., global $container instances) and lacks type safety.
  • You need fine-grained control over singleton vs. fresh instances (e.g., new_user() vs. user()).
  • You’re open to subclassing the container to add PHPDoc annotations for type hints.
• Look elsewhere if:
  • You require advanced features like circular reference detection, contextual binding, or macroable containers (consider Symfony DI or Laravel’s container).
  • Your team resists PHPDoc annotations or relies on dynamic property access (Props enforces explicit declarations).
  • You’re in a high-performance context (e.g., CLI scripts with tight loops)—Props isn’t optimized for microbenchmarks.
  • You’re locked into Pimple’s array-style API ($container['key']) and don’t want to refactor to property access.
  • You need Laravel-specific integrations (e.g., service providers, Artisan commands, or Scout).

How to Pitch It (Stakeholders)

For Executives:

*"Props is a low-risk, high-reward upgrade to our dependency injection system. It transforms our container from a 'black box' into a self-documenting tool, cutting debugging time by 30%+ while keeping our existing DI logic intact. For minimal effort, we’ll gain:

• Fewer production bugs from misconfigured dependencies (IDE catches errors early).
• Faster onboarding for new developers (autocomplete replaces memorizing service names).
• Future-proofing for static analysis tools, which will flag issues before they reach QA. This is a no-code-change migration for most teams—just add PHPDoc annotations and subclass the container. The payoff is immediate productivity gains with almost zero operational risk."*

For Engineering (Developers):

*"Props solves two critical pain points:

1. IDE Frustration: No more guessing service names or types when calling $container->get(). Now $container->userRepository is autocompleted with type hints.
2. Singleton vs. Fresh Instances: Need a new database connection? Use $container->new_connection(). Need the cached one? $container->connection. This is cleaner than Pimple’s offsetGet/offsetSet and works seamlessly with static analyzers. Migration Path:

• Start by subclassing your existing container (e.g., AppContainer extends Props\Container).
• Add @property-read and @method PHPDoc blocks.
• Replace $container['service'] with $container->service in new code. Trade-offs: Slightly more boilerplate for setup, but zero runtime cost and better tooling long-term. Let’s pilot it in [Module X] first to validate the benefits."*

For Engineering (Architects/Tech Leads):

*"Props is a lightweight, PSR-11-compliant DI container that excels in IDE integration and static analysis. Here’s how it fits into our stack:

• Pros:
  • Type Safety: PHPDoc annotations enable autocompletion, refactoring, and static analysis (Psalm/PHPStan).
  • Laravel Compatibility: Implements Psr\Container\ContainerInterface, so it can coexist with Laravel’s container (though not replace it fully).
  • Pimple Bridge: Props\Pimple allows gradual migration from Pimple without rewriting DI logic.
  • Low Overhead: Minimal runtime cost compared to Laravel’s container.
• Cons:
  • No Laravel-Specific Features: Lacks service providers, Artisan integration, or Scout support. Would require custom wrappers for advanced use cases.
  • Migration Effort: Replacing Laravel’s container entirely would need rewriting binding logic (e.g., bind() → setFactory()).
• Recommendation:
  • Use Props for domain-specific containers (e.g., App\Services\AuthContainer) where IDE support is critical.
  • Keep Laravel’s container for framework-level dependencies and use Props alongside it for type-safe property access.
  • Pilot in a non-critical module first to assess tooling benefits vs. migration effort."*

For QA/Testing Teams:

*"Props improves dependency injection clarity, which directly benefits testing:

• Static Analysis: Tools like Psalm can verify dependency contracts at compile time, reducing flaky tests caused by misconfigured DI.
• Explicit Dependencies: Typed properties ($container->userRepository) make it obvious what a class depends on, simplifying mocking in tests.
• Fresh Instances: The new_* pattern (e.g., $container->new_user()) ensures test isolation by avoiding cached singletons. Potential Impact:
• Fewer UndefinedIndexException or ContainerException errors in tests.
• Easier refactoring without breaking tests (IDE helps track dependencies).
• Better documentation of service lifecycles (singleton vs. fresh)."*