https://github.com/commonphp/di
Lightweight and easy-to-use dependency injection library for PHP to simplify object management and promote loose coupling.
https://github.com/commonphp/di
commonphp dependency-injection design-patterns di di-container loose-coupling object-management object-oriented-programming php php8 service-container
Last synced: 3 months ago
JSON representation
Lightweight and easy-to-use dependency injection library for PHP to simplify object management and promote loose coupling.
- Host: GitHub
- URL: https://github.com/commonphp/di
- Owner: commonphp
- License: other
- Created: 2023-06-29T03:08:13.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2024-08-04T03:28:20.000Z (11 months ago)
- Last Synced: 2025-03-20T19:14:52.193Z (3 months ago)
- Topics: commonphp, dependency-injection, design-patterns, di, di-container, loose-coupling, object-management, object-oriented-programming, php, php8, service-container
- Language: PHP
- Homepage:
- Size: 64.5 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# CommonPHP Dependency Injection
`CommonPHP\DependencyInjection` is a simple yet powerful dependency injection (DI) container for PHP applications, enabling the means to dynamically create new objects, invoke methods, call functions and populate properties without having to know the structure of the target directly.
## Features
- Constructor and method injection: Instantiate classes and invoke methods with automatic resolution of dependencies.
- Value finder: A support class for the DI process that assists in discovering and managing parameter values during instantiation.
- Handling of circular dependencies: An instantiation stack to prevent issues caused by recursive dependency chains.
- Customizable parameter lookup: Enhance the default lookup process by adding custom lookup hooks.
- Populating object properties: Assign values to an object's properties, handling a variety of visibility and type scenarios.
- Exception handling: A series of specific exceptions to help troubleshoot issues related to DI and instantiation.
## Requirements
The CommonPHP framework requires PHP 8.3 or newer. This library specifically has the following dependencies:
- PHP's built-in Reflection classes, which are used extensively for instantiating classes, invoking methods, and reading type information.
## Installation
You can install `CommonPHP\DependencyInjection` using [Composer](https://getcomposer.org/):
```bash
composer require comphp/di
```
## Basic Usage
### Instantiating Classes
The main component is the `DependencyInjector` class, which is responsible for injecting the passed parameters into a constructor, method or function.
```php
instantiate(ExampleClass::class);
// Invoke a method
$result = $injector->invoke($exampleClass, 'exampleMethod');
// Call a function or closure
$result = $injector->call('exampleFunction');
```
### Populating Object Properties
The `DependencyInjector` can also populate the properties of an object:
```php
'value1', 'property2' => 'value2'];
// populate public properties only
$injector->populate($object, $values);
// populate all properties
$injector->populate($object, $values, false);
```
### Custom Lookup Hooks
The `ValueFinder` class allows you to add custom lookup hooks:
```php
valueFinder->onLookup(function (string $name, string $typeName, bool &$found): mixed {
if ($typeName == MyClassType::class) {
$found = true;
return new MyClassType();
} else if ($name == 'specificStringVariable') {
$found = true;
return 'specificStringValue';
}
return null;
});
```
### Delegating Class Instantiation
For classes requiring specific instantiation logic, the `DependencyInjector` offers a `delegate` method. This method allows you to specify a custom callback for creating instances of a specific class, providing greater control over the object creation process.
```php
delegate(SpecificClass::class, function($injector, $name, $typeName) {
return new SpecificClass('value1', 'value2');
});
// Automatically use the delegate when SpecificClass is needed
$instance = $injector->instantiate(InitiatedClass::class);
```
## Documentation
For more in-depth documentation, check out [the Wiki](https://github.com/commonphp/di/wiki).
### API Reference
This is a high-level overview of the API. For detailed information about classes, methods, and properties, please refer to the source code and accompanying PHPDoc comments.
- **`CommonPHP\DependencyInjection\DependencyInjector`**: The main class in the library. Provides methods for instantiating classes, invoking methods, calling functions, and populating properties with automatic dependency resolution.
- **`instantiate(string $class, array $params = []): object`**: Instantiates a class with the provided parameters.
- **`invoke($object, string $method, array $params = [], bool $publicOnly = true): mixed`**: Invokes a method on a given object with the provided parameters.
- **`call(callable $callable, array $params = []): mixed`**: Calls a function or closure with the provided parameters.
- **`populate(object $object, array $values, bool $publicOnly = true): void`**: Populates the properties of an object with the given values.
- **`CommonPHP\DependencyInjection\Support\ValueFinder`**: A supporting class that assists in discovering and managing parameter values during instantiation.
- **`onLookup(callable $callback): void`**: Registers a callback function to be used during the lookup process.
### Examples
Here are some examples of using CommonPHP\DependencyInjection. You can find the full source code for these examples in the `examples` directory of this repository.
- [**Instantiate**](https://github.com/commonphp/di/blob/master/examples/instantiate.php): This example shows how to instantiate a class using `DependencyInjector::instantiate()`.
- [**Invoke**](https://github.com/commonphp/di/blob/master/examples/invoke.php): This example shows how to invoke a method using `DependencyInjector::invoke()`.
- [**Call**](https://github.com/commonphp/di/blob/master/examples/call.php): This example shows how to call a function or closure using `DependencyInjector::call()`.
- [**Populate**](https://github.com/commonphp/di/blob/master/examples/populate.php): This example shows how to populate the properties of an object using `DependencyInjector::populate()`.
- [**Lookup Hooks**](https://github.com/commonphp/di/blob/master/examples/lookup-hooks.php): This example shows how to use a custom lookup hook with `ValueFinder::onLookup()`.
## Contributing
Contributions are always welcome! Please read the [contribution guidelines](CONTRIBUTING.md) first.
## Testing
This project uses PHPUnit for unit testing. Follow the instructions below to run the tests:
1. Ensure you have PHPUnit installed. If not, you can install it with Composer:
```bash
composer require --dev phpunit/phpunit
```
2. Navigate to the project's root directory.
3. Run the tests using the following command:
```bash
./vendor/bin/phpunit tests
```
4. If the tests are successful, you will see output similar to:
```
PHPUnit 9.6.9 by Sebastian Bergmann and contributors.
...................... 22 / 22 (100%)
Time: 00:00.228, Memory: 4.00 MB
OK (22 tests, 36 assertions)
```
We recommend regularly running these tests during development to help catch any potential issues early. We also strive for a high level of test coverage, and additions to the codebase should ideally include corresponding tests.
For more detailed output or for integration into continuous integration (CI) systems, PHPUnit can generate a log file in a variety of formats. Check the [PHPUnit documentation](https://phpunit.de/documentation.html) for more information.
## License
This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.