feat: Implement delegate method for custom instantiation #13

Author: tlmcclatchey

README.md

@@ -98,6 +98,37 @@ $injector->valueFinder->onLookup(function (string $name, string $typeName, bool
 });
 ```
 
+### 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
+<?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](https://github.com/commonphp/di/wiki).

examples/delegate.php

@@ -0,0 +1,44 @@
+<?php
+
+require_once '../vendor/autoload.php';
+
+use CommonPHP\DependencyInjection\DependencyInjector;
+
+// Assuming SpecificClass requires custom instantiation logic
+class SpecificClass
+{
+    private string $customArg1;
+    private string $customArg2;
+    public function __construct(string $customArg1, string $customArg2)
+    {
+        $this->customArg1 = $customArg1;
+        $this->customArg2 = $customArg2;
+        // Custom construction logic here
+    }
+}
+
+class InitiatedClass
+{
+    private SpecificClass $specificClass;
+    public function __construct(SpecificClass $specificClass)
+    {
+        $this->specificClass = $specificClass;
+    }
+}
+
+$injector = new DependencyInjector();
+
+// Delegate the instantiation of SpecificClass to a custom callback
+$injector->delegate(SpecificClass::class, function($injector, $name, $typeName) {
+    // Example of using custom arguments
+    $customArg1 = 'value1';
+    $customArg2 = 'value2';
+
+    return new SpecificClass($customArg1, $customArg2);
+});
+
+// Instantiate SpecificClass using the custom delegate logic
+$instance = $injector->instantiate(InitiatedClass::class, []);
+
+// Demonstrates that the $instance is indeed an object of SpecificClass
+var_dump($instance);

src/DependencyInjector.php

@@ -25,6 +25,7 @@
 use CommonPHP\DependencyInjection\Exceptions\MethodNotDefinedException;
 use CommonPHP\DependencyInjection\Exceptions\MethodNotPublicException;
 use CommonPHP\DependencyInjection\Exceptions\ParameterDiscoveryFailedException;
+use CommonPHP\DependencyInjection\Exceptions\ParameterTypeRequiredException;
 use CommonPHP\DependencyInjection\Exceptions\UnsupportedReflectionTypeException;
 use CommonPHP\DependencyInjection\Support\ValueFinder;
 use CommonPHP\DependencyInjection\Support\InstantiationStack;
@@ -50,6 +51,32 @@ public function __construct()
         $this->valueFinder = new ValueFinder();
     }
 
+    /**
+     * Assigns a custom callback for instantiating a specified class.
+     *
+     * Enables defining a custom instantiation logic for a specific class through a callback,
+     * thereby overriding the default instantiation mechanism. This feature is particularly useful
+     * for setting up complex objects or integrating classes requiring specific construction patterns,
+     * enhancing flexibility in object creation within the dependency injection system.
+     *
+     * @param string   $className The fully qualified name of the class for custom instantiation.
+     * @param callable $callback  A user-defined function that instantiates the class. The callback
+     *                            is provided with the DependencyInjector instance, class name,
+     *                            and type name, facilitating context-aware instantiation.
+     * @return void
+     */
+    public function delegate(string $className, callable $callback): void
+    {
+        $this->valueFinder->onLookup(function ($name, $typeName, &$found) use ($className, $callback) {
+            var_dump($typeName, $className);
+            if ($typeName === $className) {
+                $found = true;
+                return $callback($this, $name, $typeName);
+            }
+            return null;
+        });
+    }
+
     /**
      * Instantiates a class with the given parameters, resolving dependencies automatically.
      *
@@ -63,6 +90,7 @@ public function __construct()
      * @throws UnsupportedReflectionTypeException
      * @throws InstantiateCircularReferenceException
      * @throws InstantiationFailedException
+     * @throws ParameterTypeRequiredException
      */
     public function instantiate(string $className, array $parameters): object
     {