> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/advanced-features/dependency-injection.md).

# Dependency Injection

## Overview

Quantum PHP Framework uses a powerful Dependency Injection system to manage class dependencies, lifecycle, and automatic wiring, enabling loose coupling and easier testing.

The DI system centers around three main classes:

* `Di`: A static facade forwarding requests to the DI container in the app context.
* `DiContainer`: A container holding dependency registrations, resolved instances, and implementing the core logic.
* `DiRegistry`: Stores and validates dependency bindings.

## Core Concepts

* **Registration**: Bind interfaces or abstract names to concrete classes.
* **Resolution**: Retrieve shared or new instances, recursively resolving their constructor dependencies.
* **Autowiring**: Use reflection to automatically supply constructor or callable parameters.
* **Singleton Management**: Cached instances returned for shared dependencies.
* **Circular Dependency Detection**: Prevent infinite recursion in dependency graphs.

## Key API Methods

* `Di::register(string $concrete, ?string $abstract = null)`: Register a dependency.
* `Di::get(string $abstract, array $args = [])`: Retrieve shared instance.
* `Di::create(string $abstract, array $args = [])`: Create a new instance.
* `Di::autowire(callable $callable, array $args = [])`: Autowire parameters for a callable. This method returns an array of resolved arguments and does not invoke the callable.

Usage:

```php
$args = Di::autowire($callable, $inputArgs);
$callable(...$args);
```

* `Di::set(string $abstract, object $instance, bool $override = true)`: Manually set an instance, optionally preventing an override of existing registered instances by setting `$override` to `false`. If the dependency is already registered and `override` is `false`, the method throws an exception.

## Usage Example

```php
use Quantum\Di\Di;

// Register interface to class binding
Di::register(FooService::class, FooInterface::class);

// Get singleton instance
$foo = Di::get(FooInterface::class);

// Create new instance
$newFoo = Di::create(FooService::class);

// Autowire callable
Di::autowire(function(FooInterface $foo, BarService $bar) {
    // Use injected dependencies
});
```

## How It Works

* `DiContainer` stores mappings and instances.
* Upon `get` or `create`, it resolves dependencies recursively using reflection.
* Checks circular dependencies and throws exceptions if found.
* Uses `DiRegistry` to validate and fetch concrete implementations.

## Best Practices

* Register dependencies at application boot.
* Use interfaces for type-hinting to decouple code.
* Avoid circular references.
* Prefer autowiring with constructor injection.

## What to read next

After DI concepts, continue with:

* [Services](/docs/core-concepts/services.md)
* [Modules](/docs/core-concepts/modules.md)
* [Configuration](/docs/advanced-features/configuration.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/advanced-features/dependency-injection.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.