Getting Started with Dependency Injection Containers in PHP (Without Losing Your Mind)

Why Dependency Injection Containers Matter in Modern PHP

If you have ever opened a legacy PHP project and found classes that create other classes, connect to the database, start sessions, call APIs, and log messages all in the same method, you have met the natural enemy of maintainable code: tight coupling.

As PHP has grown from simple scripts to complex applications running entire businesses, developers have needed better ways to organize code. This is where dependency injection and, by extension, dependency injection containers in PHP come into play.

Dependency injection (DI) is not magic. At its core, it is a disciplined way of giving objects the things they need to do their work instead of letting them go and fetch those things themselves. A dependency injection container (DIC) is just a helper object that knows how to build and wire those dependencies for you.

This article will guide you through the essentials of getting started with dependency injection containers in PHP, from understanding the concept to writing your own tiny container and finally using popular libraries in real-world scenarios.

Understanding Dependency Injection Before the Container

Before plugging in a container, it is crucial to grasp what dependency injection is on its own. You can use DI without any container at all; the container just helps manage complexity at scale.

What Is a Dependency?

A dependency is simply an object or service that another object needs to perform its job. For example, a UserController might depend on a UserRepository to load and save users, and on a LoggerInterface to record events.

Example: a typical PHP class with dependencies
class UserController
{
    private UserRepository $users;
    private LoggerInterface $logger;

    public function __construct(UserRepository $users, LoggerInterface $logger)
    {
        $this->users  = $users;
        $this->logger = $logger;
    }

    public function show(int $id)
    {
        $user = $this->users->find($id);
        $this->logger->info('User viewed', ['id' => $id]);

        // render view...
    }
}

Here the controller does not know how the repository or logger are created. It just expects them to be provided. That is dependency injection in action.

Common Anti-Pattern: Creating Dependencies Inside Classes

Consider a different approach, where the controller creates everything it needs inside itself:

class UserController
{
    private UserRepository $users;
    private LoggerInterface $logger;

    public function __construct()
    {
        $this->users  = new UserRepository(new PDO('mysql:host=...', 'user', 'pass'));
        $this->logger = new FileLogger('/var/log/app.log');
    }
}

On day one this seems straightforward. But problems appear quickly:

• Hard to test: you cannot easily swap the real PDO or FileLogger for mocks in unit tests.
• Hard to change: switching from MySQL to PostgreSQL or from a file logger to a cloud logger requires editing the controller code.
• Tight coupling: the controller now depends on specific implementations instead of abstractions.

Dependency injection reverses this: it pushes the responsibility of creating objects to the “outside world”, allowing the class to receive only what it needs.

From Manual Wiring to a Dependency Injection Container

You can apply dependency injection manually. In a small PHP script or micro-project, that is often enough. But once your application grows to dozens or hundreds of classes, manually wiring everything becomes painful.

Manual Wiring Example

Here is how you might “wire” dependencies in a single entry point file like public/index.php:

// Configuration
$dsn      = 'mysql:host=localhost;dbname=app;charset=utf8mb4';
$dbUser   = 'app';
$dbPass   = 'secret';
$logFile  = __DIR__ . '/../var/log/app.log';

// Low-level services
$pdo      = new PDO($dsn, $dbUser, $dbPass);
$logger   = new FileLogger($logFile);

// Domain services
$userRepo = new UserRepository($pdo);

// Controllers
$userController = new UserController($userRepo, $logger);

// Now use the controller
$userController->show((int) $_GET['id']);

This is still pure dependency injection: everything is created outside the classes that use it. But as soon as you add more controllers, background workers, CLI commands, event subscribers, and so on, the bootstrap file becomes a jungle.

What a Dependency Injection Container Actually Does

Conceptually, a dependency injection container in PHP is just an object that:

• Stores definitions of how to build your services (objects).
• Knows whether a service should be a singleton (one instance) or a factory (new instance each time).
• Resolves dependencies, often using type hints and reflection.
• Returns a fully configured instance when you ask for UserController::class or some other identifier.

The rest of your code becomes much cleaner: instead of manually constructing object graphs, you just ask the container once (usually in your framework’s bootstrap) and pass the ready-made objects to the places that need them.

Building a Tiny Dependency Injection Container in Plain PHP

To demystify things, let’s write a very small dependency injection container in native PHP. It will not be production-grade, but it will illustrate the core ideas.

Step 1: Define a Basic Container Interface

The PSR-11 standard defines a simple interface for containers, called Psr\Container\ContainerInterface. It is widely supported in the PHP ecosystem. For learning, we can define something similar:

interface ContainerInterface
{
    public function get(string $id): mixed;
    public function has(string $id): bool;
}

Step 2: Implement a Minimalist Container

This container will support two main features:

• Registering services as factories (closures that build the service).
• Caching instances to behave like singletons by default.

class SimpleContainer implements ContainerInterface
{
    /** @var array<string, callable(self): mixed> */
    private array $definitions = [];

    /** @var array<string, mixed> */
    private array $instances = [];

    public function set(string $id, callable $factory): void
    {
        $this->definitions[$id] = $factory;
    }

    public function get(string $id): mixed
    {
        if (isset($this->instances[$id])) {
            return $this->instances[$id];
        }

        if (!isset($this->definitions[$id])) {
            throw new RuntimeException("Service '$id' not found in container.");
        }

        $this->instances[$id] = ($this->definitions[$id])($this);

        return $this->instances[$id];
    }

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

The set() method allows you to register how a service should be created. The get() method builds the service on first use and then stores it for reuse.

Step 3: Register Your Services

Now you can use the container to build the same object graph as before, but in a structured way:

$container = new SimpleContainer();

$container->set(PDO::class, function () {
    return new PDO(
        'mysql:host=localhost;dbname=app;charset=utf8mb4',
        'app',
        'secret'
    );
});

$container->set(LoggerInterface::class, function () {
    return new FileLogger(__DIR__ . '/../var/log/app.log');
});

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

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

Later, in your front controller:

$userController = $container->get(UserController::class);
$userController->show((int) $_GET['id']);

You have just created your first working dependency injection container in PHP.

Automatic Wiring with Reflection (Conceptual)

More advanced containers can examine your class constructors via reflection, figure out which dependencies they need based on type hints, and create everything automatically without you manually defining each relation.

For example, if you request OrderController::class, the container could inspect its __construct(), see that it requires OrderService and LoggerInterface, build those as well (recursively), and so on.

Popular Dependency Injection Containers in the PHP Ecosystem

In real applications you will rarely write your own container from scratch. Instead, you will rely on mature, battle-tested libraries or the containers embedded in popular frameworks.

Framework-Integrated Containers

• Symfony DependencyInjection – a powerful container used by the Symfony framework and many standalone projects. It supports configuration via PHP, XML, YAML, and offers compilation for high performance.
• Laravel Service Container – central to how Laravel applications are wired. It offers service providers, automatic injection via method signatures, and many convenient helpers.
• Yii, Laminas, Slim, and others – most modern PHP frameworks ship with a container or integrate closely with a PSR-11 compliant one.

Standalone, Framework-Agnostic Containers

• PHP-DI – a popular, flexible container with autowiring and annotations support. Great for projects that do not rely on a full framework.
• League Container – part of The PHP League ecosystem, offering a clean API and PSR-11 compatibility.
• Auryn – reflection-based container focused strongly on autowiring and minimal configuration.

Whatever your choice, understanding the concepts behind dependency injection containers in PHP will make it much easier to switch tools or frameworks later.

Using a Dependency Injection Container in a Real-World PHP Application

Let us walk through a more realistic scenario: a small web application that exposes controllers, services, and repositories. We will use a generic container approach that looks similar to what you find in many libraries.

Typical Layers in a PHP Application

A classic architecture might include:

• Controllers – handle HTTP requests, interact with services, return responses.
• Services – hold business logic, orchestrate repositories and other services.
• Repositories – talk to the database or external APIs.
• Infrastructure – loggers, mailers, queues, cache, etc.

The container acts as the central hub that knows how these pieces fit together.

Example: Wiring Layers with a Container

$container->set(PDO::class, function () {
    $pdo = new PDO('mysql:host=localhost;dbname=app;charset=utf8mb4', 'app', 'secret');
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    return $pdo;
});

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

$container->set(MailerInterface::class, function () {
    return new SmtpMailer('smtp.example.com', 587);
});

$container->set(UserService::class, function (SimpleContainer $c) {
    return new UserService(
        $c->get(UserRepositoryInterface::class),
        $c->get(MailerInterface::class)
    );
});

$container->set(UserController::class, function (SimpleContainer $c) {
    return new UserController($c->get(UserService::class));
});

Now your controllers and services can remain focused on their responsibilities. Changing how emails are sent or where users are stored becomes a matter of changing the container configuration, not the business logic.

Integrating with Routing

In micro-frameworks like Slim or custom setups, you often pass a callable as a route handler. The container can resolve controllers and their methods automatically:

$router->get('/users/{id}', function ($request, $response, $args) use ($container) {
    $controller = $container->get(UserController::class);
    return $controller->show((int) $args['id'], $response);
});

This pattern keeps your routing layer lean and delegates construction to the container.

Benefits of Dependency Injection Containers for PHP Developers

Beyond “it feels better”, using a dependency injection container in PHP brings measurable benefits across the software lifecycle.

1. Easier Testing and Mocking

When classes depend on interfaces instead of concrete implementations, you can swap in mock objects during tests. The container becomes your ally: configure different factories in test environments, or use a dedicated test container.

// In tests
$container->set(LoggerInterface::class, function () {
    return new InMemoryLogger(); // collects logs in memory for assertions
});

Your production code does not change; only the container configuration does.

2. Clear Separation of Concerns

The container draws a clean line between object construction and object usage. This separation makes it easier for teams to reason about the codebase: one developer can focus on business logic, another on infrastructure wiring.

3. Flexibility and Extensibility

Need to introduce caching, observability, or an AI-based recommendation engine into your PHP platform? With a DI container, you typically:

1. Create a new service (e.g., RecommendationService).
2. Register it in the container.
3. Inject it into existing classes via constructors.

No need to search for new RecommendationService() scattered all over the codebase.

4. Environment-Specific Configuration

Different environments (local, staging, production) often require different implementations or parameters. Using a container, you can load different configuration files or service providers per environment. For instance, you might inject a fake payment gateway in development and the real one in production.

Common Pitfalls When Starting with Dependency Injection Containers

Like any powerful tool, a dependency injection container in PHP can be misused. Here are some traps to avoid.

1. Treating the Container as a Global Service Locator

A classic mistake is to inject the entire container into many classes and call $container->get() inside methods. This effectively turns the container into a service locator, hiding dependencies and making the code harder to analyze and test.

// Anti-pattern: do NOT do this
class OrderService
{
    public function __construct(private ContainerInterface $container) {}

    public function checkout(int $orderId): void
    {
        $paymentGateway = $this->container->get(PaymentGatewayInterface::class);
        // ...
    }
}

Instead, declare dependencies explicitly in the constructor:

class OrderService
{
    public function __construct(private PaymentGatewayInterface $gateway) {}
}

Let the container do its job from the outside.

2. Over-Configuring for Tiny Projects

If you are building a small CLI script or a single-purpose tool, introducing a heavy container might be overkill. In such cases, simple manual wiring or a very small container (like the example we built earlier) is perfectly adequate.

3. Hidden Magic and Debugging Difficulty

Some containers offer features like annotations, auto-registration, or complex lifecycle hooks. Used carefully, these can save time. Used excessively, they can make it harder for new team members to understand where services come from.

When getting started, favor explicit configuration and a clear mental model over clever tricks.

Design Guidelines for Dependency Injection in PHP

To harness the full power of dependency injection containers in PHP, it helps to follow a few design guidelines.

Prefer Interfaces Over Concrete Classes

Whenever feasible, rely on interfaces instead of concrete types. This keeps your code open to change and easier to mock.

interface UserRepositoryInterface
{
    public function find(int $id): ?User;
}

class PdoUserRepository implements UserRepositoryInterface
{
    // implementation
}

class UserService
{
    public function __construct(private UserRepositoryInterface $users) {}
}

The container then decides whether to use PdoUserRepository, InMemoryUserRepository, or some other implementation.

Keep Constructors Focused

If a class constructor needs more than 4–5 dependencies, it might be doing too much. Consider splitting responsibilities into smaller services. This naturally leads to more modular code that the container can manage more easily.

Use Configuration Files or Service Providers

As your application grows, centralizing container configuration in a single script becomes unwieldy. Many containers support:

• Configuration files (PHP, YAML, XML, JSON) that declare services.
• Service providers or modules that register groups of services.

This mirrors how you structure your code and encourages reusability across projects.

Dependency Injection Containers and the Future of PHP Applications

PHP keeps evolving towards richer, more complex ecosystems: microservices, event-driven architectures, headless APIs, and AI-enhanced backends. The more moving parts you have, the more you benefit from a reliable mechanism to wire them together.

Imagine a stack that combines:

• A PHP API using a DI container for controllers and services.
• External microservices for billing, search, or recommendations.
• Background workers and queues.
• Optional AI-based modules for personalization or content generation.

In such an environment, the container becomes a sort of “control tower” for your PHP layer, coordinating how internal services interact and how they expose stable contracts to other parts of the architecture.

Teams that pair solid engineering practices like dependency injection with specialized support in automation or AI often move faster. For instance, when integrating AI-driven components into an existing PHP platform, a clear dependency structure makes it easier to inject new adapters, bridges, or orchestration layers without rewriting the core. In those cases, working alongside a partner that knows how to connect application code with data pipelines and models—such as providers focused on AI integration and implementation—can be a natural extension of the architectural work you already do around your containers.

Step-by-Step: Introducing a Container into an Existing PHP Project

If you are maintaining a legacy codebase, you might be wondering how to introduce a dependency injection container in PHP without breaking everything. The key is to do it incrementally.

Step 1: Start at the Edges

Begin where control naturally enters your application: front controllers, CLI entry points, or worker scripts. Replace direct new calls with container lookups, while leaving the internals unchanged for now.

Step 2: Refactor One Service at a Time

1. Pick a class that currently builds its own dependencies.
2. Extract those dependencies into constructor parameters.
3. Adjust any calling code (or the container) to provide the new dependencies.

Repeat until you reach a comfortable level of decoupling.

Step 3: Move Configuration into Modules

Group related services into configuration modules or service providers. For example, a DatabaseServiceProvider can configure PDO, repositories, and transaction managers. This will make maintenance easier as the project grows.

Step 4: Add Tests Around Critical Wiring

While containers are mostly infrastructure, you can still write integration tests to ensure that key services can be resolved and that object graphs are valid. For example, a test may simply call $container->get(UserController::class) and assert that it returns the expected type without throwing exceptions.

Conclusion: Think in Dependencies, Not in Constructors

Getting started with dependency injection containers in PHP is less about memorizing a specific library’s syntax and more about adopting a mindset:

• Every class has dependencies—make them explicit.
• Object creation is a first-class concern—centralize it.
• Containers are there to serve your architecture, not to dictate it.

Once you embrace this, containers stop being mysterious black boxes and become practical tools that make your PHP applications easier to test, extend, and reason about. Whether you are managing a compact REST API or a large monolith being gradually modularized, DI and containers give you the flexibility to evolve your codebase instead of rewriting it.