Mastering PHP Dependency Injection: A Complete Guide to Scalable Architecture

Written by

webdevfundamentals

in

The Hidden Trap in Your PHP Code: The “New” Keyword Problem

Imagine you are building a modern PHP application. You have a UserRegistration class that needs to send a welcome email and save data to a database. Inside your method, you write: $mailer = new SendGridMailer();. It works perfectly. Your app goes live, and users are happy.

Six months later, your company switches from SendGrid to Mailgun. Suddenly, you have to hunt through dozens of classes, replacing every instance of new SendGridMailer() with new MailgunMailer(). While doing this, you realize your unit tests are failing because they are trying to send real emails during the test run. You have fallen into the trap of Tight Coupling.

This is where Dependency Injection (DI) comes to the rescue. DI is not just a fancy design pattern used by framework developers; it is the fundamental pillar of clean, maintainable, and testable PHP code. In this comprehensive guide, we will explore everything from basic manual injection to advanced PSR-11 compliant containers, utilizing modern PHP 8.2+ features like Constructor Property Promotion and Attributes.

What is Dependency Injection?

At its core, Dependency Injection is a simple concept: A class should not create the objects it needs to do its job. Instead, those objects (dependencies) should be “injected” into it from the outside.

Think of it like a professional chef. A chef doesn’t build their own stove, forge their own knives, or grow their own tomatoes before cooking a meal. Those tools and ingredients are provided to them. This allows the chef to focus on the logic of cooking, regardless of whether the stove is gas or electric.

The Dependency Inversion Principle (DIP)

DI is the practical implementation of the “D” in SOLID principles: Dependency Inversion. It suggests that high-level modules should not depend on low-level modules; both should depend on abstractions (interfaces).

The Three Primary Flavors of Dependency Injection

In PHP, there are three main ways to inject dependencies into a class. Each has its own use case, pros, and cons.

1. Constructor Injection (Recommended)

This is the most common and robust form of DI. Dependencies are passed through the class constructor. This ensures that the class is never in an “incomplete” state; it cannot be instantiated without its requirements.


// The Interface (Abstraction)
interface MailerInterface {
    public function send(string $to, string $message): bool;
}

// The Concrete Class
class UserRegistration {
    private MailerInterface $mailer;

    // We inject the dependency here
    public function __construct(MailerInterface $mailer) {
        $this->mailer = $mailer;
    }

    public function register(string $email): void {
        // Logic to save user...
        $this->mailer->send($email, "Welcome!");
    }
}

2. Setter Injection

Dependencies are passed via “setter” methods. This is useful for optional dependencies or objects that might change during the lifecycle of the class.


class LoggerAware {
    private ?LoggerInterface $logger = null;

    public function setLogger(LoggerInterface $logger): void {
        $this->logger = $logger;
    }

    public function logAction(string $msg): void {
        $this->logger?->info($msg);
    }
}

3. Interface Injection

This is less common in PHP but involves an interface that defines a setter method for a dependency. It forces any class implementing the interface to accept the dependency.

Modern PHP 8+ Enhancements for DI

PHP 8.0 and 8.2 introduced features that make Dependency Injection significantly cleaner and less verbose. If you are still writing PHP 7.4 style constructors, you are doing more work than necessary.

Constructor Property Promotion

Before PHP 8.0, you had to declare a property, accept it in the constructor, and assign it. Now, you can do it all in one line.


// Old Way (Pre PHP 8.0)
class DatabaseService {
    private PDO $pdo;
    public function __construct(PDO $pdo) {
        $this->pdo = $pdo;
    }
}

// New Way (PHP 8.0+)
class DatabaseService {
    public function __construct(
        private readonly PDO $pdo
    ) {}
}

The readonly keyword (introduced in PHP 8.1) adds an extra layer of security, ensuring the dependency cannot be replaced after the object is initialized.

The Nightmare of Manual Wiring

Dependency Injection sounds great, but as your application grows, you encounter “Dependency Hell.” If Class A needs Class B, and Class B needs Class C, and Class C needs a DatabaseConnection and a ConfigReader, instantiating Class A becomes a mess:


$config = new ConfigReader(__DIR__ . '/config.php');
$db = new DatabaseConnection($config->get('db_dsn'));
$repo = new UserRepository($db);
$logger = new FileLogger('/logs/app.log');
$service = new UserRegistration($repo, $logger);

Writing this “wiring” code manually in every controller or command is repetitive and error-prone. This is why we use a Dependency Injection Container (DIC).

Understanding the Dependency Injection Container (DIC)

A DI Container is a specialized object that knows how to instantiate and configure other objects. Think of it as a giant “lookup table” for your application’s services. Instead of you calling new, you ask the container for an object, and the container handles the construction logic.

What is PSR-11?

The PHP community established the PSR-11 (Container Interface) standard to ensure interoperability between different container implementations. It defines two main methods:

  • get(string $id): Retrieves an entry from the container.
  • has(string $id): Returns true if the container can return an entry for the ID.

Building a Simple PSR-11 Container from Scratch

To understand how modern containers work, let’s build a basic one. This will demonstrate the logic behind “Service Registration” and “Resolution.”


namespace MyFramework;

use Psr\Container\ContainerInterface;
use Exception;

class SimpleContainer implements ContainerInterface {
    private array $entries = [];

    // Register a service
    public function set(string $id, callable $factory): void {
        $this->entries[$id] = $factory;
    }

    public function get(string $id) {
        if (!$this->has($id)) {
            throw new Exception("Service not found: " . $id);
        }

        // Execute the factory function to create the object
        $factory = $this->entries[$id];
        return $factory($this);
    }

    public function has(string $id): bool {
        return isset($this->entries[$id]);
    }
}

// Usage:
$container = new SimpleContainer();

$container->set(PDO::class, function($c) {
    return new PDO('mysql:host=localhost;dbname=test', 'user', 'pass');
});

$container->set(UserRepository::class, function($c) {
    return new UserRepository($c->get(PDO::class));
});

// Retrieving the service
$userRepo = $container->get(UserRepository::class);

While this works, modern PHP development rarely requires you to write your own container. We use mature libraries like PHP-DI, Symfony DependencyInjection, or Laravel’s Service Container.

The Magic of Auto-wiring

Modern containers use Reflection to automatically detect what dependencies a constructor needs. This feature is called “Auto-wiring.” If your UserController needs a UserRepository, the container looks at the type-hint, creates the repository, and passes it in—all without you writing a single line of configuration.

Example using PHP-DI

PHP-DI is one of the most powerful standalone containers for PHP. Here is how it handles complex dependencies automatically:


use DI\ContainerBuilder;

$builder = new ContainerBuilder();
$container = $builder->build();

// No configuration needed! PHP-DI uses reflection to see 
// that MailerInterface needs an implementation.
// We only need to tell it WHICH implementation to use for the Interface.

$builder->addDefinitions([
    MailerInterface::class => DI\create(MailgunMailer::class)
]);

$container = $builder->build();

// The container automatically handles the rest
$registrationService = $container->get(UserRegistration::class);

Dependency Injection and Unit Testing

The single greatest benefit of DI is the ease of testing. When a class is tightly coupled, you cannot test it in isolation. With DI, you can inject “Mocks” or “Stubs.”

Let’s test our UserRegistration class without actually sending an email:


use PHPUnit\Framework\TestCase;

class UserRegistrationTest extends TestCase {
    public function testUserCanRegister() {
        // 1. Create a Mock of the MailerInterface
        $mockMailer = $this->createMock(MailerInterface::class);

        // 2. Expect the 'send' method to be called once
        $mockMailer->expects($this->once())
                   ->method('send')
                   ->willReturn(true);

        // 3. Inject the Mock into the Service
        $service = new UserRegistration($mockMailer);

        // 4. Run the method
        $service->register('test@example.com');
        
        // Assertion happens via the Mock expectation
    }
}

This test is lightning fast because it doesn’t touch a network or a database. It only tests the logic of the UserRegistration class.

Common Mistakes and How to Avoid Them

1. The Service Locator Anti-Pattern

A common mistake is passing the Container itself into your classes. This is known as the Service Locator pattern.

Wrong:


class MyService {
    public function __construct(private ContainerInterface $container) {}

    public function doSomething() {
        $db = $this->container->get('database'); // HIDDEN DEPENDENCY
    }
}

Why it’s bad: It hides the class’s real dependencies. You have to look inside the code to see what it needs. It also makes the class dependent on the container, making it harder to reuse in other projects.

2. Over-Injection

If your constructor has 15 arguments, your class is likely doing too much. This is a violation of the Single Responsibility Principle. If you see this, consider breaking the class into smaller, more focused services.

3. Injecting Values, Not Objects

While you can inject strings (like API keys), it’s often better to wrap configuration in a “Config” or “Settings” object. This provides type safety and prevents typos in string keys.

Step-by-Step: Refactoring Legacy PHP to DI

  1. Identify the dependencies: Look for the new keyword inside your methods.
  2. Create an Interface: Define what the dependency does (e.g., PaymentGatewayInterface).
  3. Implement the Interface: Create your concrete class (e.g., StripeGateway).
  4. Add a Constructor: Add the dependency to the constructor of the consuming class using the Interface type-hint.
  5. Wire it up: Use a container (like PHP-DI or Symfony) to map the Interface to the Concrete implementation.
  6. Clean up: Remove the new calls from your business logic.

Summary and Key Takeaways

  • DI is about passing dependencies, not creating them. It decouples your code and makes it modular.
  • Constructor Injection is the gold standard for reliability.
  • PHP 8.x features like Constructor Property Promotion and Readonly properties make DI code concise.
  • PSR-11 ensures your container choice doesn’t lock you into a specific vendor.
  • Auto-wiring significantly reduces the boilerplate configuration needed for modern PHP apps.
  • Testability is the primary driver for using DI in professional environments.

Frequently Asked Questions (FAQ)

Is Dependency Injection only for large projects?

No. While the benefits are more obvious in large systems, DI promotes clean habits in projects of any size. Even a small script benefits from the clear separation of configuration and logic.

Does Dependency Injection hurt performance?

The overhead of a DI container is negligible in most web applications. Modern containers like Symfony or Laravel compile their dependency graphs into optimized PHP files, making the lookup extremely fast. The maintenance benefits far outweigh any micro-performance costs.

What is the difference between DI and IoC?

Inversion of Control (IoC) is the broad principle where the control of the program flow is inverted. Dependency Injection is a specific method of implementing IoC focusing on object creation.

Should I inject 3rd party libraries directly?

It is often better to create a “Wrapper” or “Adapter” class around 3rd party libraries. This way, if the library changes its API, you only have to change your wrapper, not your entire application code.

Can I use DI without a Container?

Absolutely. This is called “Poor Man’s DI” or Manual DI. You manually instantiate the objects and pass them in. This is perfectly fine for small applications or CLI tools where a full container might be overkill.

This guide provided a deep dive into Dependency Injection for PHP development. By implementing these patterns, you ensure your code is ready for the future—flexible, testable, and professionally structured.

More posts