Introduce DependencyResolver interface

Useful for outer libraries to rely on the interface rather than on the concrete implementation itself, leaving the door open for user-land customizations.

Author: e1himself

src/Contracts/DependencyResolver.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Technically\DependencyResolver\Contracts;
+
+use ArgumentCountError;
+use InvalidArgumentException;
+use Psr\Container\ContainerExceptionInterface;
+use Technically\DependencyResolver\Exceptions\CannotAutowireArgument;
+use Technically\DependencyResolver\Exceptions\CannotAutowireDependencyArgument;
+use Technically\DependencyResolver\Exceptions\ClassCannotBeInstantiated;
+
+interface DependencyResolver
+{
+    /**
+     * Resolve the given class instance from the container.
+     *
+     * It can be either found in the container or constructed on the fly,
+     * recursively auto-resolving the required parameters.
+     *
+     * @param class-string $className
+     * @return mixed
+     *
+     * @throws InvalidArgumentException If the class does not exist.
+     * @throws ContainerExceptionInterface If an error occurs while retrieving the existing entry from the container.
+     * @throws ClassCannotBeInstantiated If the class cannot be instantiated.
+     * @throws CannotAutowireDependencyArgument If a dependency (of any nesting level) cannot be resolved.
+     */
+    public function resolve(string $className): mixed;
+
+    /**
+     * Force-construct the given class instance using container state for auto-wiring dependencies.
+     *
+     * Even if the container already has the instance bound,
+     * it will still be instantiated.
+     *
+     * @param class-string        $className
+     * @param array<string,mixed> $bindings
+     * @return mixed
+     *
+     * @throws ClassCannotBeInstantiated
+     * @throws CannotAutowireDependencyArgument
+     */
+    public function construct(string $className, array $bindings = []): mixed;
+
+    /**
+     * Call the given callable with its arguments automatically wired using the container state.
+     *
+     * @template T
+     * @param callable():T        $callable
+     * @param array<string,mixed> $bindings
+     * @return T
+     *
+     * @throws ArgumentCountError
+     * @throws CannotAutowireArgument
+     */
+    public function call(callable $callable, array $bindings = []): mixed;
+}

src/DependencyResolver.php

@@ -8,13 +8,14 @@
 use Psr\Container\ContainerInterface;
 use Technically\CallableReflection\CallableReflection;
 use Technically\CallableReflection\Parameters\ParameterReflection;
+use Technically\DependencyResolver\Contracts\DependencyResolver as DependencyResolverInterface;
 use Technically\DependencyResolver\Exceptions\CannotAutowireArgument;
 use Technically\DependencyResolver\Exceptions\CannotAutowireDependencyArgument;
 use Technically\DependencyResolver\Exceptions\ClassCannotBeInstantiated;
 use Technically\DependencyResolver\Exceptions\DependencyResolutionException;
 use Technically\NullContainer\NullContainer;
 
-final class DependencyResolver
+final class DependencyResolver implements DependencyResolverInterface
 {
     private ContainerInterface $container;
 
@@ -24,7 +25,7 @@ public function __construct(?ContainerInterface $container = null)
     }
 
     /**
-     * @param string $className
+     * @param class-string $className
      * @return mixed
      *
      * @throws InvalidArgumentException If class does not exist.
@@ -46,8 +47,8 @@ public function resolve(string $className): mixed
     }
 
     /**
-     * @param string $className
-     * @param array $bindings
+     * @param class-string $className
+     * @param array<string,mixed> $bindings
      * @return mixed
      *
      * @throws ClassCannotBeInstantiated
@@ -75,9 +76,10 @@ public function construct(string $className, array $bindings = []): mixed
     }
 
     /**
-     * @param callable $callable
-     * @param array $bindings
-     * @return mixed
+     * @template T
+     * @param callable():T        $callable
+     * @param array<string,mixed> $bindings
+     * @return T
      *
      * @throws ArgumentCountError
      * @throws CannotAutowireArgument
@@ -93,7 +95,7 @@ public function call(callable $callable, array $bindings = []): mixed
 
     /**
      * @param ParameterReflection[] $parameters
-     * @param array $bindings
+     * @param array<string,mixed>   $bindings
      * @return array
      *
      * @throws CannotAutowireArgument