Dependency Inversion Principle

When to use

• The user wants a class to depend on an interface rather than a concrete implementation so the two can vary independently.
• The user wants collaborators injected through the constructor instead of being created with new inside a class.
• The user wants to substitute a fake or mock for a dependency in a test without editing the class under test.

When NOT to use

• Do not add an interface for a small internal helper that has one caller, no I/O, and no realistic second implementation.
• Do not invert a dependency on a stable standard-library type or a pure value (a string, a DateTimeImmutable, an array helper).

Core guidance

• Depend on abstractions, not concretions — Type constructor parameters and properties against interfaces, not concrete classes, so a class collaborates with a contract rather than a specific implementation.
• Let the high-level policy own the interface — Define the interface in the high-level module that needs it and phrase it in that module's terms; the low-level detail then implements the policy's contract.

Quick recipe

1. Name the role the consumer needs and declare an interface for it in the consumer's module, e.g. interface Mailer with send(Message $message): void. (verify: The interface is phrased in the consumer's terms, not a backend's API)
2. Replace any new Concrete() with a constructor parameter typed to the interface, e.g. public function __construct(private Mailer $mailer) {}. (verify: The class references only the interface and never constructs the concrete class)
3. Register the binding once in the composition root, e.g. $container->bind(Mailer::class, SmtpMailer::class), so consumers receive the concrete type. (verify: Rebinding to a fake mailer in a test injects it everywhere with no consumer change)

Best practices

• Receive every collaborator as a constructor parameter typed to its interface rather than calling new on a concrete class inside a method
• Shape each abstraction around the role the consumer needs (e.g
• Map each interface to its concrete implementation in a single composition root (a service provider or container config), never scattered across the codebase

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. An interface shaped around one implementation — Designing the interface around the quirks of one implementation (Redis-specific methods on a cache abstraction) leaks that detail to every consumer. Fix: Define the interface from the consumer's need in neutral terms, and hide backend-specific behavior inside the implementation.
2. Newing up a concrete dependency inside the class — Calling new ConcreteMailer() inside a class hardwires that implementation and defeats the inversion the interface was meant to provide. Fix: Accept the dependency as a constructor parameter typed to its interface, and let the composition root pass in the concrete instance.
3. Pulling dependencies from a global container — Reaching into a static container (app(Mailer::class)) from inside a class hides its real dependencies and re-introduces global coupling. Fix: Inject the dependencies you need as explicit constructor parameters and let the container resolve them at the composition root only.

Version notes

• Pure interfaces sharpened by PHP 8.1 types (PHP >=8.1) — PHP 8.1 enums, never return types, and readonly promotion let role interfaces and their injected implementations be expressed precisely without framework helpers.
• New in initializers eases default wiring in PHP 8.1+ (PHP >=8.1) — From PHP 8.1, new in parameter default values lets a class declare a sensible default implementation while still allowing the composition root to override it.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/architecture/dependency-inversion.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: architecture/hexagonal, laravel/service-container