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:

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

require_once 'vendor/autoload.php';

use CommonPHP\DependencyInjection\DependencyInjector;

$injector = new DependencyInjector();

// Instantiate a class
$exampleClass = $injector->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

require_once 'vendor/autoload.php';

use CommonPHP\DependencyInjection\DependencyInjector;

$injector = new DependencyInjector();
$object = new stdClass();
$values = ['property1' => '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

require_once 'vendor/autoload.php';

use CommonPHP\DependencyInjection\DependencyInjector;

$injector = new DependencyInjector();

$injector->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

require_once 'vendor/autoload.php';

use CommonPHP\DependencyInjection\DependencyInjector;

class SpecificClass {
    private string $customArg1;
    private string $customArg2;

    public function __construct(string $customArg1, string $customArg2) {
        // Custom construction logic here
    }
}

$injector = new DependencyInjector();

// Delegate instantiation of SpecificClass to a custom callback
$injector->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.

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: This example shows how to instantiate a class using DependencyInjector::instantiate().

• Invoke: This example shows how to invoke a method using DependencyInjector::invoke().

• Call: This example shows how to call a function or closure using DependencyInjector::call().

• Populate: This example shows how to populate the properties of an object using DependencyInjector::populate().

• Lookup Hooks: This example shows how to use a custom lookup hook with ValueFinder::onLookup().

Contributing

Contributions are always welcome! Please read the contribution guidelines 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:

   composer require --dev phpunit/phpunit

2. Navigate to the project's root directory.

3. Run the tests using the following command:

   ./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 for more information.

License

This project is licensed under the MIT License. See the LICENSE.md file for details.