Handling unresolvable parameters — primitives and defaults

<?php
declare(strict_types=1);

namespace Framework\Container;

use ReflectionParameter;
use ReflectionNamedType;
use Framework\Container\Exceptions\BindingResolutionException;

/**
 * Extended resolveParameter() that handles primitives, defaults,
 * and caller-supplied overrides via the $with stack.
 *
 * Drop these methods into the Container class from fw-02-005.
 */
trait ResolvesParameters
{
    /**
     * Stack of primitive overrides for the current resolution chain.
     * Each entry is an associative array: ['paramName' => value].
     *
     * @var array<int, array<string, mixed>>
     */
    protected array $with = [];

    /**
     * Resolve a class from the container, optionally injecting primitive overrides.
     *
     * Usage:
     *   $container->makeWith(Connection::class, ['dsn' => 'sqlite::memory:']);
     */
    public function makeWith(string $abstract, array $primitives = []): mixed
    {
        $this->with[] = $primitives;

        try {
            $result = $this->make($abstract);
        } finally {
            // Always pop — even if an exception is thrown.
            array_pop($this->with);
        }

        return $result;
    }

    /**
     * Resolve a single constructor parameter.
     *
     * Priority:
     *  1. Typed class/interface — recurse into make()
     *  2. Caller override ($with stack) — keyed by parameter name
     *  3. Default value declared in the class
     *  4. Throw BindingResolutionException
     */
    protected function resolveParameter(ReflectionParameter $parameter): mixed
    {
        $type = $parameter->getType();

        // 1. Class or interface type → recurse.
        if ($type instanceof ReflectionNamedType && ! $type->isBuiltin()) {
            return $this->resolveClass($parameter, $type->getName());
        }

        // 2. Check caller-supplied primitive overrides (top of stack first).
        $override = $this->getOverride($parameter->getName());
        if ($override !== null) {
            return $override;
        }

        // 3. Fall back to the parameter's own default value.
        if ($parameter->isDefaultValueAvailable()) {
            return $parameter->getDefaultValue();
        }

        // 4. Nothing works — tell the developer what to fix.
        $this->throwUnresolvable($parameter);
    }

    /**
     * Resolve a class-typed parameter.
     * Handles nullable types: if $type is nullable and resolution fails,
     * we return null rather than throwing.
     */
    protected function resolveClass(ReflectionParameter $parameter, string $className): mixed
    {
        try {
            return $this->make($className);
        } catch (BindingResolutionException $e) {
            // If the parameter is optional (nullable or has a default), swallow.
            if ($parameter->isOptional()) {
                return $parameter->isDefaultValueAvailable()
                    ? $parameter->getDefaultValue()
                    : null;
            }

            throw $e;
        }
    }

    /**
     * Look through the $with stack (newest first) for a primitive override
     * matching the given parameter name.
     */
    protected function getOverride(string $paramName): mixed
    {
        foreach (array_reverse($this->with) as $overrides) {
            if (array_key_exists($paramName, $overrides)) {
                return $overrides[$paramName];
            }
        }

        return null; // Sentinel: no override found.
    }

    /**
     * Throw a descriptive exception for an unresolvable primitive parameter.
     *
     * @throws BindingResolutionException
     */
    protected function throwUnresolvable(ReflectionParameter $parameter): never
    {
        $class = $parameter->getDeclaringClass()?->getName() ?? 'unknown';

        throw new BindingResolutionException(
            sprintf(
                "Unresolvable dependency resolving [\$%s] in class [%s]. " .
                "The parameter has no type-hint, no default value, and no override was supplied. " .
                "Use makeWith() to pass a value for this parameter.",
                $parameter->getName(),
                $class
            )
        );
    }
}

// -------------------------------------------------------------------------
// Example classes that demonstrate the three resolution paths
// -------------------------------------------------------------------------

class DatabaseConnection
{
    public function __construct(
        public readonly string $dsn,                      // primitive — needs override
        public readonly string $username    = 'root',     // primitive — has default
        public readonly string $password    = '',         // primitive — has default
        public readonly int    $timeout     = 30,         // primitive — has default
    ) {}
}

class QueryLogger {}

class Database
{
    public function __construct(
        public readonly DatabaseConnection $connection,   // class — auto-wired
        public readonly QueryLogger        $logger,       // class — auto-wired
    ) {}
}

<?php
// Resolution in action

$container = new Framework\Container\Container();

// Auto-wiring fails for DatabaseConnection because $dsn has no default.
// Use makeWith() to supply the primitive:
$connection = $container->makeWith(DatabaseConnection::class, [
    'dsn'      => 'mysql:host=localhost;dbname=myapp',
    'username' => 'myapp_user',
    'password' => 's3cret',
]);

// Now bind it so the container can inject it into Database.
$container->instance(DatabaseConnection::class, $connection);

// Database is fully auto-wired (DatabaseConnection now comes from instance()).
$database = $container->make(Database::class);