Container.php

<?php

namespace FrameworkX;

use Psr\Container\ContainerInterface;
use Psr\Http\Message\ServerRequestInterface;

/**
 * @final
 */
class Container
{
    /** @var array<string,object|callable():(object|scalar|null)|scalar|null>|ContainerInterface */
    private $container;

    /** @var bool */
    private $useProcessEnv;

    /**
     * @param array<string,callable():(object|scalar|null) | object | scalar | null>|ContainerInterface $config
     * @throws \TypeError if given $config is invalid
     */
    public function __construct($config = [])
    {
        /** @var mixed $config explicit type check for mixed if user ignores parameter type */
        if (!\is_array($config) && !$config instanceof ContainerInterface) {
            throw new \TypeError(
                'Argument #1 ($config) must be of type array|Psr\Container\ContainerInterface, ' . $this->gettype($config) . ' given'
            );
        }

        foreach (($config instanceof ContainerInterface ? [] : $config) as $name => $value) {
            if (!$value instanceof $name && !$value instanceof \Closure && !\is_string($value) && \strpos($name, '\\') !== false) {
                throw new \TypeError(
                    'Argument #1 ($config) for key "' . $name . '" must be of type ' . $name . '|Closure|string, ' . $this->gettype($value) . ' given'
                );
            }
            if (!\is_object($value) && !\is_scalar($value) && $value !== null) {
                throw new \TypeError(
                    'Argument #1 ($config) for key "' . $name . '" must be of type object|string|int|float|bool|null|Closure, ' . $this->gettype($value) . ' given'
                );
            }
        }
        $this->container = $config;

        // prefer reading environment from `$_ENV` and `$_SERVER`, only fall back to `getenv()` in thread-safe environments
        $this->useProcessEnv = \ZEND_THREAD_SAFE === false || \in_array(\PHP_SAPI, ['cli', 'cli-server', 'cgi-fcgi', 'fpm-fcgi'], true);
    }

    /**
     * @return mixed returns whatever the $next handler returns
     * @throws \BadMethodCallException if used as a final request handler
     * @throws \Throwable if $next handler throws unexpected exception
     */
    public function __invoke(ServerRequestInterface $request, ?callable $next = null)
    {
        if ($next === null) {
            // You don't want to end up here. This only happens if you use the
            // container as a final request handler instead of as a middleware.
            // In this case, you should omit the container or add another final
            // request handler behind the container in the middleware chain.
            throw new \BadMethodCallException('Container should not be used as final request handler');
        }

        // If the container is used as a middleware, simply forward to the next
        // request handler. As an additional optimization, the container would
        // usually be filtered out from a middleware chain as this is a NO-OP.
        return $next($request);
    }

    /**
     * @param class-string $class
     * @return callable(ServerRequestInterface,?callable=null)
     * @throws void
     * @internal
     */
    public function callable(string $class): callable
    {
        return function (ServerRequestInterface $request, ?callable $next = null) use ($class) {
            try {
                if ($this->container instanceof ContainerInterface) {
                    $handler = $this->container->get($class);
                } else {
                    $handler = $this->loadObject($class);
                }
            } catch (\Throwable $e) {
                throw new \Error(
                    'Request handler class ' . $class . ' failed to load: ' . $e->getMessage(),
                    0,
                    $e
                );
            }

            // Check `$handler` references a class name that is callable, i.e. has an `__invoke()` method.
            // This initial version is intentionally limited to checking the method name only.
            // A follow-up version will likely use reflection to check request handler argument types.
            if (!\is_callable($handler)) {
                throw new \Error(
                    'Request handler ' . \explode("\0", $class)[0] . ' has no public __invoke() method'
                );
            }

            // invoke request handler as middleware handler or final controller
            if ($next === null) {
                return $handler($request);
            }
            return $handler($request, $next);
        };
    }

    /**
     * @throws \TypeError if container config or factory returns an unexpected type
     * @throws \Throwable if container factory function throws unexpected exception
     * @internal
     */
    public function getEnv(string $name): ?string
    {
        \assert(\preg_match('/^[A-Z][A-Z0-9_]+$/', $name) === 1);

        if ($this->container instanceof ContainerInterface && $this->container->has($name)) {
            $value = $this->container->get($name);
        } elseif ($this->hasVariable($name)) {
            $value = $this->loadVariable($name);
        } else {
            return null;
        }

        if (!\is_string($value) && $value !== null) {
            throw new \TypeError(
                'Return value of ' . __METHOD__ . '() for $' . $name . ' must be of type string|null, ' . $this->gettype($value) . ' returned'
            );
        }

        return $value;
    }

    /**
     * @throws \TypeError if container config or factory returns an unexpected type
     * @throws \Throwable if container factory function throws unexpected exception
     * @internal
     */
    public function getAccessLogHandler(): AccessLogHandler
    {
        if ($this->container instanceof ContainerInterface) {
            if ($this->container->has(AccessLogHandler::class)) {
                // @phpstan-ignore-next-line method return type will ensure correct type or throw `TypeError`
                return $this->container->get(AccessLogHandler::class);
            } else {
                return new AccessLogHandler();
            }
        }
        return $this->loadObject(AccessLogHandler::class);
    }

    /**
     * @throws \TypeError if container config or factory returns an unexpected type
     * @throws \Throwable if container factory function throws unexpected exception
     * @internal
     */
    public function getErrorHandler(): ErrorHandler
    {
        if ($this->container instanceof ContainerInterface) {
            if ($this->container->has(ErrorHandler::class)) {
                // @phpstan-ignore-next-line method return type will ensure correct type or throw `TypeError`
                return $this->container->get(ErrorHandler::class);
            } else {
                return new ErrorHandler();
            }
        }
        return $this->loadObject(ErrorHandler::class);
    }

    /**
     * @template T of object
     * @param class-string<T> $name
     * @return T
     * @throws \TypeError if container config or factory returns an unexpected type
     * @throws \Error if object of type $name can not be loaded
     * @throws \Throwable if container factory function throws unexpected exception
     */
    private function loadObject(string $name, int $depth = 64) /*: object (PHP 7.2+) */
    {
        \assert(\is_array($this->container));

        if (\array_key_exists($name, $this->container)) {
            if (\is_string($this->container[$name])) {
                if ($depth < 1) {
                    throw new \Error('Container config for ' . $name . ' is recursive');
                }

                // @phpstan-ignore-next-line because type of container value is explicitly checked after getting here
                $value = $this->loadObject($this->container[$name], $depth - 1);
                if (!$value instanceof $name) {
                    throw new \TypeError(
                        'Return value of ' . __METHOD__ . '() for ' . $name . ' must be of type ' . $name . ', ' . $this->gettype($value) . ' returned'
                    );
                }

                $this->container[$name] = $value;
            } elseif ($this->container[$name] instanceof \Closure) {
                // build list of factory parameters based on parameter types
                $closure = new \ReflectionFunction($this->container[$name]);
                $params = $this->loadFunctionParams($closure, $depth, true, \explode("\0", $name)[0]);

                // invoke factory with list of parameters
                $value = $params === [] ? ($this->container[$name])() : ($this->container[$name])(...$params);

                if (\is_string($value)) {
                    if ($depth < 1) {
                        throw new \Error('Container config for ' . $name . ' is recursive');
                    }

                    // @phpstan-ignore-next-line because type of container value is explicitly checked after getting here
                    $value = $this->loadObject($value, $depth - 1);
                }
                if (!$value instanceof $name) {
                    throw new \TypeError(
                        'Return value of ' . self::functionName($closure) . ' for ' . $name . ' must be of type ' . $name . ', ' . $this->gettype($value) . ' returned'
                    );
                }

                $this->container[$name] = $value;
            } elseif (!$this->container[$name] instanceof $name) {
                throw new \TypeError(
                    'Return value of ' . __METHOD__ . '() for ' . $name . ' must be of type ' . $name . ', ' . $this->gettype($this->container[$name]) . ' returned'
                );
            }

            \assert($this->container[$name] instanceof $name);

            return $this->container[$name];
        }

        // Check `$name` references a valid class name that can be autoloaded
        if (!\class_exists($name, true) && !\interface_exists($name, false) && !\trait_exists($name, false)) {
            throw new \Error('Class ' . $name . ' not found');
        }

        $class = new \ReflectionClass($name);
        if (!$class->isInstantiable()) {
            $modifier = 'class';
            if ($class->isInterface()) {
                $modifier = 'interface';
            } elseif ($class->isAbstract()) {
                $modifier = 'abstract class';
            } elseif ($class->isTrait()) {
                $modifier = 'trait';
            }
            throw new \Error('Cannot instantiate ' . $modifier . ' '. $name);
        }

        // build list of constructor parameters based on parameter types
        $ctor = $class->getConstructor();
        $params = $ctor === null ? [] : $this->loadFunctionParams($ctor, $depth, false, '');

        // instantiate with list of parameters
        // @phpstan-ignore-next-line because `$class->newInstance()` is known to return `T`
        return $this->container[$name] = $params === [] ? new $name() : $class->newInstance(...$params);
    }

    /**
     * @return list<mixed>
     * @throws \TypeError if container config or factory returns an unexpected type
     * @throws \Error if either parameter can not be loaded
     * @throws \Throwable if container factory function throws unexpected exception
     */
    private function loadFunctionParams(\ReflectionFunctionAbstract $function, int $depth, bool $allowVariables, string $for): array
    {
        $params = [];
        foreach ($function->getParameters() as $parameter) {
            $params[] = $this->loadParameter($parameter, $depth, $allowVariables, $for);
        }

        return $params;
    }

    /**
     * @return mixed
     * @throws \TypeError if container config or factory returns an unexpected type
     * @throws \Error if $parameter can not be loaded
     * @throws \Throwable if container factory function throws unexpected exception
     */
    private function loadParameter(\ReflectionParameter $parameter, int $depth, bool $allowVariables, string $for) /*: mixed (PHP 8.0+) */
    {
        // abort for unreasonably deep nesting or recursive types
        if ($depth < 1) {
            throw new \Error(self::parameterError($parameter, $for) . ' is recursive');
        }

        \assert(\is_array($this->container));
        $type = $parameter->getType();

        // abort for union types (PHP 8.0+) and intersection types (PHP 8.1+)
        // @phpstan-ignore-next-line for PHP < 8
        if ($type instanceof \ReflectionUnionType || $type instanceof \ReflectionIntersectionType) { // @codeCoverageIgnoreStart
            if ($parameter->isDefaultValueAvailable()) {
                return $parameter->getDefaultValue();
            }

            throw new \Error(
                self::parameterError($parameter, $for) . ' expects unsupported type ' . $type
            );
        } // @codeCoverageIgnoreEnd

        // load container variables if parameter name is known
        \assert($type === null || $type instanceof \ReflectionNamedType);
        if ($allowVariables && $this->hasVariable($parameter->getName())) {
            $value = $this->loadVariable($parameter->getName(), $depth);

            // skip type checks and allow all values if expected type is undefined or mixed (PHP 8+)
            // allow null values if parameter is marked nullable or untyped or mixed
            if ($type === null || ($value === null && $parameter->allowsNull()) || $type->getName() === 'mixed' || $this->validateType($value, $type)) {
                return $value;
            }

            throw new \TypeError(
                self::parameterError($parameter, $for) . ' must be of type ' . self::typeName($type) . ', ' . $this->gettype($value) . ' given'
            );
        }

        // use default argument if not loadable as container variable or by type
        if (
            $parameter->isDefaultValueAvailable() &&
            (!$type instanceof \ReflectionNamedType || $type->isBuiltin() || !\array_key_exists($type->getName(), $this->container))
        ) {
            return $parameter->getDefaultValue();
        }

        // abort if required container variable is not defined or for any other primitive types (array etc.)
        if (!$type instanceof \ReflectionNamedType || $type->isBuiltin()) {
            throw new \Error(
                self::parameterError($parameter, $for) . ' requires container config' . ($type !== null ? ' with type ' . self::typeName($type) : '') . ', none given'
            );
        }

        // @phpstan-ignore-next-line because `$type->getName()` is a `class-string` by definition
        return $this->loadObject($type->getName(), $depth - 1);
    }

    private function hasVariable(string $name): bool
    {
        return (\is_array($this->container) && \array_key_exists($name, $this->container)) || (isset($_ENV[$name]) || (\is_string($_SERVER[$name] ?? null) || ($this->useProcessEnv && \getenv($name) !== false)) && \preg_match('/^[A-Z][A-Z0-9_]+$/', $name));
    }

    /**
     * @return object|string|int|float|bool|null
     * @throws \TypeError if container factory returns an unexpected type
     * @throws \Error if $name can not be loaded
     * @throws \Throwable if container factory function throws unexpected exception
     */
    private function loadVariable(string $name, int $depth = 64) /*: object|string|int|float|bool|null (PHP 8.0+) */
    {
        \assert($this->hasVariable($name));
        \assert(\is_array($this->container) || !$this->container->has($name));

        if (\is_array($this->container) && ($this->container[$name] ?? null) instanceof \Closure) {
            // build list of factory parameters based on parameter types
            $factory = $this->container[$name];
            \assert($factory instanceof \Closure);
            $closure = new \ReflectionFunction($factory);
            $params = $this->loadFunctionParams($closure, $depth - 1, true, '$' . $name);

            // invoke factory with list of parameters
            $value = $params === [] ? $factory() : $factory(...$params);

            if (!\is_object($value) && !\is_scalar($value) && $value !== null) {
                throw new \TypeError(
                    'Return value of ' . self::functionName($closure) . ' for $' . $name . ' must be of type object|string|int|float|bool|null, ' . $this->gettype($value) . ' returned'
                );
            }

            $this->container[$name] = $value;
        } elseif (\is_array($this->container) && \array_key_exists($name, $this->container)) {
            $value = $this->container[$name];
        } elseif (isset($_ENV[$name])) {
            \assert(\is_string($_ENV[$name]));
            $value = $_ENV[$name];
        } elseif (isset($_SERVER[$name])) {
            \assert(\is_string($_SERVER[$name]));
            $value = $_SERVER[$name];
        } else {
            $value = \getenv($name);
            \assert($this->useProcessEnv && $value !== false);
        }

        \assert(\is_object($value) || \is_scalar($value) || $value === null);
        return $value;
    }

    /**
     * @param object|string|int|float|bool|null $value
     * @param \ReflectionNamedType $type
     * @throws void
     */
    private function validateType($value, \ReflectionNamedType $type): bool
    {
        $type = $type->getName();
        return (
            (\is_object($value) && $value instanceof $type) ||
            (\is_string($value) && $type === 'string') ||
            (\is_int($value) && $type === 'int') ||
            (\is_float($value) && $type === 'float') ||
            (\is_bool($value) && $type === 'bool')
        );
    }

    /** @throws void */
    private static function functionName(\ReflectionFunctionAbstract $function): string
    {
        $name = $function->getShortName();
        if ($name[0] === '{') { // $function->isAnonymous() (PHP 8.2+)
            // use PHP 8.4+ format including closure file and line on all PHP versions: https://3v4l.org/tAs7s
            $name = '{closure:' . $function->getFileName() . ':' . $function->getStartLine() . '}';
        } elseif ($function instanceof \ReflectionMethod && ($class = $function->getDeclaringClass()) !== null) {
            $name = \explode("\0", $class->getName())[0] . '::' . $name;
        }
        return $name . '()';
    }

    /** @throws void */
    private static function parameterError(\ReflectionParameter $parameter, string $for): string
    {
        return 'Argument #' . ($parameter->getPosition() + 1) . ' ($' . $parameter->getName() . ') of ' . self::functionName($parameter->getDeclaringFunction()) . ($for !== '' ? ' for ' . $for : '');
    }

    /**
     * @param \ReflectionNamedType $type
     * @return string
     * @throws void
     * @see https://www.php.net/manual/en/reflectiontype.tostring.php (PHP 8+)
     */
    private static function typeName(\ReflectionNamedType $type): string
    {
        return ($type->allowsNull() && $type->getName() !== 'mixed' ? '?' : '') . $type->getName();
    }

    /**
     * @param mixed $value
     * @return string
     * @throws void
     * @see https://www.php.net/manual/en/function.get-debug-type.php (PHP 8+)
     */
    private function gettype($value): string
    {
        if (\is_int($value)) {
            return 'int';
        } elseif (\is_float($value)) {
            return 'float';
        } elseif (\is_bool($value)) {
            return \var_export($value, true);
        } elseif ($value === null) {
            return 'null';
        }
        return \is_object($value) ? \explode("\0", \get_class($value))[0] : \gettype($value);
    }
}