Avoid Common Dependency Injection Pitfalls in PHP and Master Best Practices

Dependency Injection (DI) should be a core practice in modern PHP development, yet many developers misuse it, leading to more complex and harder-to-maintain code.

1. Common DI Misconceptions

Equating DI with using a container. Developers think that merely calling a service container (e.g., Laravel’s Service Container) means they are applying DI. The core idea is to inject dependencies via parameters, not to fetch them inside the class. Example of a wrong approach:

class UserService {
    public function getUser($id) {
        $db = Container::get('db'); // Wrong: fetching dependency directly
        return $db->query('SELECT * FROM users WHERE id = ?', [$id]);
    }
}

This is actually a Service Locator pattern, hiding the class’s dependencies.

Overusing constructor injection. Not all dependencies are suitable for constructor injection, especially those determined at runtime (e.g., request objects). Forcing them into the constructor adds redundancy and complexity.

Ignoring interfaces and abstractions. Many inject concrete classes instead of abstractions. Example:

class PaymentProcessor {
    private $paypalService; // Wrong: concrete dependency
    public function __construct(PayPalService $paypalService) {
        $this->paypalService = $paypalService;
    }
}

This tightly couples the code to a specific implementation.

Abusing the DI container. Using the container for dynamic resolution or excessive aliasing makes the code mysterious and hard to debug.

2. Correctly Practicing Dependency Injection

Explicitly inject dependencies via constructors, method parameters, or property injection (constructor injection is recommended). Fixed example:

class UserService {
    private $db;
    // Dependency is clearly injected through the constructor
    public function __construct(PDO $db) {
        $this->db = $db;
    }
    public function getUser($id) {
        return $this->db->query('SELECT * FROM users WHERE id = ?', [$id]);
    }
}

Combine interfaces and abstractions to increase flexibility and testability:

interface PaymentGateway {
    public function charge($amount);
}
class PayPalService implements PaymentGateway {
    public function charge($amount) { /* ... */ }
}
class PaymentProcessor {
    private $paymentGateway;
    // Depend on the abstraction, not the concrete class
    public function __construct(PaymentGateway $paymentGateway) {
        $this->paymentGateway = $paymentGateway;
    }
}

Use the container only for assembling objects, not inside business logic. Keep container configuration centralized.

Distinguish strong (required) dependencies, injected via constructor, from weak (optional) dependencies, injected via method parameters or default values.

Write testable code. Proper DI enables easy mocking in unit tests:

$mockDb = $this->createMock(PDO::class);
$userService = new UserService($mockDb);
// Test UserService behavior

Conclusion

DI is not merely using a container; it is a design principle based on Inversion of Control and the Dependency Inversion Principle. Avoid injecting dependencies inside the class, depending on concrete implementations, and abusing the container. By declaring clear dependencies, depending on abstractions, and using the container responsibly, you can achieve decoupled, testable, and maintainable PHP code.