# Overview
Ray.Di is a dependency injection (DI) framework for PHP. It automatically resolves object dependencies and enables flexible object graph construction according to the context.
## Core Features
### Dependency Resolution at Compile Time
- Resolves dependencies by describing overall rules rather than individual object assembly (autowiring)
- Detects dependency issues before execution
- Minimizes runtime overhead through code generation
### Flexible Object Graph Construction
- Enables various contexts through the combination of independent modules
- Allows dependency resolution according to the injected object; for example, changing dependencies based on the target method's attributes or the object's state (CDI: Contexts and Dependency Injection)
- Injects different implementations of the same interface using `Qualifier`
- Supports injection of lazily instantiated objects
### Explicit Dependency Description
- Describes dependency generation using raw PHP code
- Utilizes attributes for self-documented dependency definitions
- Separates cross-cutting concerns through integration with AOP
## Stability and Reliability
Since the release of version 2.0 in 2015, Ray.Di has expanded its features along with the evolution of PHP while maintaining backward compatibility by following semantic versioning.
## Google Guice and Ray.Di
Ray.Di is a PHP DI framework inspired by [Google Guice](https://github.com/google/guice). Based on the proven API design of Google Guice, it aims for PHP-like evolution. Most of the documents on this site are also quoted from Google Guice.
---
Using dependency injection offers many benefits, but doing it manually requires writing a lot of boilerplate code. Ray.Di is a framework that allows you to use dependency injection without writing such cumbersome code. For more details, please see the [Motivation](motivation.html) page.
In short, Ray.Di eliminates the need to use factories or `new` in your PHP code. While you may still need to write factories, your code does not directly depend on them. Your code becomes easier to modify, unit test, and reuse in other contexts.
# Ray.Di Tutorial 1
In this tutorial, you will learn the basics of the DI pattern and how to start a Ray.Di project. We will change from a non-di code to a manual DI code, then to a code using Ray.Di to add functionality.
## Preparation
Create a project for the tutorial.
```
mkdir ray-tutorial
cd ray-tutorial
composer self-update
composer init --name=ray/tutorial --require=ray/di:^2 --autoload=src -n
composer update
```
Create `src/Greeter.php`.
A program that greets `$users` one after another.
```php
sayHello();
```
Let's run it.
```php
php bin/run.php
Hello DI!
Hello AOP!
Hello REST!
```
## Dependency pull
Consider making `$users` variable.
For example, a global variable?
```diff
- $users = ['DI', 'AOP', 'REST'];
+ $users = $GLOBALS['users'];
```
Too wild. Let's consider other ways.
```php
define("USERS", ['DI', 'AOP', 'REST']);
$users = USERS;
```
```php
class User
{
public const NAMES = ['DI', 'AOP', 'REST'];
};
$users = User::NAMES;
```
```php
$users = Config::get('users')
```
It is getting the necessary dependencies from the outside, It's "dependency pull" and in the end it is the same global as the `$GLOBALS` variable. It makes the coupling between objects tight and difficult to test.
## Dependency Injection
The DI pattern is one in which dependencies are injected from other sources, rather than being obtained from the code itself.
```php
class Greeter
{
public function __construct(
private readonly Users $users
) {}
public function sayHello(): void
{
foreach ($this->users as $user) {
echo 'Hello ' . $user . '!' . PHP_EOL;
}
}
}
```
Inject not only the data you need, but also the output as a separate service.
```diff
public function __construct(
- private readonly Users $users
+ private readonly Users $users,
+ private readonly PrinterInterface $printer
) {}
public function sayHello()
{
foreach ($this->users as $user) {
- echo 'Hello ' . $user . '!' . PHP_EOL;
+ ($this->printer)($user);
}
}
```
Create the following classes
`src/Users.php`
```php
users as $user) {
($this->printer)($user);
}
}
}
```
## Manual DI
Create and run a script `bin/run_di.php` to do this.
```php
sayHello();
```
While the number of files may seem to increase in number and overall complexity, the individual scripts are so simple that it is difficult to make them any simpler. Each class has only one responsibility [^srp], relies on abstractions rather than implementations [^dip], and is easy to test, extend, and reuse.
[^srp]: [Single Responsibility Principle (SRP)](https://en.wikipedia.org/wiki/Single_responsibility_principle)
[^dip]: [Dependency Inversion Principle (DIP)](https://en.wikipedia.org/wiki/Dependency_inversion_principle)
### Compile Time and Runtime
Code under `bin/` constitutes a dependency at **compile time**, while code under `src/` is executed at **run time**. PHP is a scripting language, but this distinction between compile time and run time can be considered.
### Constructor Injection
DI code passes dependencies externally and receives them in the constructor.
```php
$instance = new A(
new B,
new C(
new D(
new E, new F, new G
)
)
);
```
B and C needed to generate A are passed to the constructor from outside A (without being obtained from inside A); D to generate C, E,F,G to generate D... and dependencies require other dependencies, and objects generate an object graph [^og] containing dependent objects.
As the size of the project grows, manual DI using such factory code becomes a reality with problems such as deep nested dependency resolution, instance management such as singletons, reusability, and maintainability. Ray.Di solves that dependency problem.
[^og]: "In computer science, object-oriented applications have a complex network of interrelated objects. Objects are connected to each other either by being owned by one object or by containing other objects (or their references). This object net is called an object graph." [Object Graph](https://en.wikipedia.org/wiki/Object_graph)
### Module
A module is a set of bindings. There are several types of binding, but here we will use the most basic, link binding, which binds an interface to a class, and instance binding, which binds to an actual instance, such as a value object.
Create `src/AppModule.php`.
```php
bind(Users::class)->toInstance(new Users(['DI', 'AOP', 'REST']));
$this->bind(PrinterInterface::class)->to(Printer::class);
$this->bind(GreeterInterface::class)->to(CleanGreeter::class);
}
}
```
Create and run `bin/run_di.php` to run.
```php
getInstance(GreeterInterface::class);
$greeter->sayHello();
```
Did it work? If something is wrong, please compare it with [tutorial1](https://github.com/ray-di/tutorial1/tree/master/src).
## Dependency Replacement
Sometimes you want to change the bindings depending on the context of execution, such as only for unit testing, only for development, and so on.
For example, suppose you have a test-only binding `src/TestModule.php`.
```php
bind(Users::class)->toInstance(new Users(['TEST1', 'TEST2']));
}
}
```
Modify the `bin/run_di.php` script to override this binding.
```diff
use Ray\Tutorial\AppModule;
+use Ray\Tutorial\TestModule;
use Ray\Tutorial\GreeterInterface;
require dirname(__DIR__) . '/vendor/autoload.php';
$module = new AppModule();
+$module->override(new TestModule());
```
Let's run it.
```
Hello TEST1!
Hello TEST2!
```
## Dependency on Dependency
Next, the greeting message, which is now fixed and retained in the Printer, is also changed to be injected to support multiple languages.
Create `src/IntlPrinter.php`.
```php
message, $user);
}
}
```
The constructor takes a message string for the greeting, but to identify this bundle [attribute bundle](https://ray-di.github.io/manuals/1.0/ja/binding_attributes.html) for the `#[Message]`attribute, `src/Message.php`.
```php
bind(Users::class)->toInstance(new Users(['DI', 'AOP', 'REST']));
- $this->bind(PrinterInterface::class)->to(Printer::class);
+ $this->bind(PrinterInterface::class)->to(IntlPrinter::class);
+ $this->bind()->annotatedWith(Message::class)->toInstance('Hello %s!' . PHP_EOL);
$this->bind(GreeterInterface::class)->to(CleanGreeter::class);
}
}
```
Run it to make sure it does not change.
Then try the error. Comment out the `Message::class` binding in the `configure()` method.
```diff
- $this->bind()->annotatedWith(Message::class)->toInstance('Hello %s!' . PHP_EOL);
+ // $this->bind()->annotatedWith(Message::class)->toInstance('Hello %s!' . PHP_EOL);
```
This means that Ray.Di does not know what to inject into the dependencies attributed as `#[Message]`.
When I run it, I get the following error
```
PHP Fatal error: Uncaught exception 'Ray\Di\Exception\Unbound' with message '-Ray\Tutorial\Message'
- dependency '' with name 'Ray\Tutorial\Message' used in /tmp/tutorial/src/IntlPrinter.php:8 ($message)
- dependency 'Ray\Tutorial\PrinterInterface' with name '' /tmp/tutorial/src/CleanGreeter.php:6 ($printer)
```
This is an error that `$message` in `IntlPrinter.php:8` cannot resolve its dependency, so `$printer` in `CleanGreeter.php:6` which depends on it also cannot resolve its dependency and the injection failed. Thus, when a dependency of a dependency cannot be resolved, the nesting of that dependency is also displayed.
Finally, let's create the following bundle as `src/SpanishModule.php` and overwrite it in the same way as TestModule.
```php
bind()->annotatedWith(Message::class)->toInstance('¡Hola %s!' . PHP_EOL);
}
}
```
```diff
use Ray\Tutorial\AppModule;
-use Ray\Tutorial\TestModule;
+use Ray\Tutorial\SpanishModule;
use Ray\Tutorial\GreeterInterface;
require dirname(__DIR__) . '/vendor/autoload.php';
$module = new AppModule();
-$module->override(new TestModule());
+$module->override(new SpanishModule());
```
Have you changed to the Spanish greeting as follows?
```
¡Hola DI!
¡Hola AOP!
¡Hola REST!
```
## Summary
We have seen the basics of the DI pattern and Ray.Di.
Dependencies are injected recursively from the outside rather than obtained by user code from within, and an object graph is generated.
At compile time, the relationship building between objects through dependency binding is complete, and at the runtime, the running code depends only on the interface. By following the DI pattern, the SRP principle [^srp] and the DIP principle [^dip] can be followed by nature.
The responsibility of securing dependencies has been removed from the code, making it loosely coupled and simple. The code is stable yet flexible, open to extensions but closed to modifications. [^ocp]
[^ocp]: [OCP](https://en.wikipedia.org/wiki/Open%E2%80%93closed_principle)
---
# Ray.Di Mental Model
_Learn about `Key`, `Provider` and how Ray.Di is just a map_
When you are reading about "Dependency Injection", you often see many buzzwords ("Inversion of
control", "Hollywood principle") that make it sound confusing. But
underneath the jargon of dependency injection, the concepts aren't very
complicated. In fact, you might have written something very similar already!
This page walks through a simplified model of Ray.Di implementation, which
should make it easier to think about how it works.
## Ray.Di is a map
Fundamentally, Ray.Di helps you create and retrieve objects for your application
to use. These objects that your application needs are called **dependencies**.
You can think of Ray.Di as being a map[^Ray.Di-map]. Your application code
declares the dependencies it needs, and Ray.Di fetches them for you from its map.
Each entry in the "Ray.Di map" has two parts:
* **Ray.Di key**: a key in the map which is used to fetch a particular value
from the map.
* **Provider**: a value in the map which is used to create objects for your
application.
Ray.Di keys and Providers are explained below.
[^Ray.Di-map]: The actual implementation of Ray.Di is far more complicated, but a
map is a reasonable approximation for how Ray.Di behaves.
### Ray.Di keys
Ray.Di uses `Key` to identify a dependency that can be resolved using the
"Ray.Di map".
The `Greeter` class used in the [Getting Started](#gettingstarted) declares two
dependencies in its constructor and those dependencies are represented as `Key`
in Ray.Di:
* `#[Message] string` --> `$map[$messageKey]`
* `#[Count] int` --> `$map[$countKey]`
The simplest form of a `Key` represents a type in php:
```php
// Identifies a dependency that is an instance of string.
/** @var string $databaseKey */
$databaseKey = $map[$key];
```
However, applications often have dependencies that are of the same type:
```php
class Message
{
public function __construct(
public readonly string $text
){}
}
class MultilingualGreeter
{
public function __construct(
private readonly Message $englishGreeting,
private readonly Message $spanishGreeting
) {}
}
```
Ray.Di uses [binding attributes](#bindingattributes) to distinguish dependencies
that are of the same type, that is to make the type more specific:
```php
class MultilingualGreeter
{
public function __construct(
#[English] private readonly Message $englishGreeting,
#[Spanish] private readonly Message $spanishGreeting
) {}
}
```
`Key` with binding attribute can be created as:
```php
$englishGreetingKey = $map[Message::class . English::class];
$spanishGreetingKey = $map[Message::class . Spanish::class];
```
When an application calls `$injector->getInstance(MultilingualGreeter::class)` to
create an instance of `MultilingualGreeter`. This is the equivalent of doing:
```php
// Ray.Di internally does this for you so you don't have to wire up those
// dependencies manually.
$english = $injector->getInstance(Message::class, English::class));
$spanish = $injector->getInstance(Message::class, Spanish::class));
$greeter = new MultilingualGreeter($english, $spanish);
```
To summarize: **Ray.Di `Key` is a type combined with an optional binding
attribute used to identify dependencies.**
### Ray.Di `Provider`s
Ray.Di uses
[`Provider`](https://google.github.io/Ray.Di/api-docs/latest/javadoc/com/google/inject/Provider.html)
to represent factories in the "Ray.Di map" that are capable of creating objects
to satisfy dependencies.
`Provider` is an interface with a single method:
```php
interface Provider
{
/** Provides an instance */
public function get();
}
```
Each class that implements `Provider` is a bit of code that knows how to give
you an instance of `T`. It could call `new T()`, it could construct `T` in some
other way, or it could return you a precomputed instance from a cache.
Most applications do not implement `Provider` interface directly, they use
`Module` to configure Ray.Di injector and Ray.Di injector internally creates
`Provider`s for all the object it knows how to create.
For example, the following Ray.Di module creates two `Provider`s:
```php
class CountProvider implements ProviderInterface
{
public function get(): int
{
return 3;
}
}
class MessageProvider implements ProviderInterface
{
public function get(): Message
{
return new Message('hello world');
}
}
class DemoModule extends AbstractModule
{
protected function configure(): void
{
$this->bind()->annotatedWith(Count::class)->toProvider(CountProvider::class);
$this->bind()->annotatedWith(Message::class)->toProvider(MessageProvider::class);
}
}
```
* `MessageProvider` that calls the `get()` method and returns "hello
world"
* `CountProvider` that calls the `get()` method and returns `3`
## Using Ray.Di
There are two parts to using Ray.Di:
1. **Configuration**: your application adds things into the "Ray.Di map".
1. **Injection**: your application asks Ray.Di to create and retrieve objects
from the map.
Configuration and injection are explained below.
### Configuration
Ray.Di maps are configured using Ray.Di modules. A **Ray.Di module** is a unit of
configuration logic that adds things into the Ray.Di map. There are two ways to
do this:
* Using the Ray.Di Domain Specific Language (DSL).
Conceptually, these APIs simply provide ways to manipulate the Ray.Di map. The
manipulations they do are pretty straightforward. Here are some example
translations, shown using PHP syntax for brevity and clarity:
| Ray.Di DSL syntax | Mental model |
| ---------------------------------- | ---------------------------------------------------------------------------------- |
| `bind($key)->toInstance($value)` | `$map[$key] = $value;` | BEAR\\Resource\\ResourceInterface |
| BEAR\\Resource\\FactoryInterface |