Refactor App Bootstrapping & DI Ownership Model

CHANGELOG.md

@@ -1,6 +1,25 @@
 ## [3.0.0] - TBD
 
 ### Changed
+- **BREAKING:** Refactored app bootstrapping and DI ownership model (#373):
+  - Introduced `AppContext` as the central execution state holder (mode, baseDir, DiContainer, Environment, Config, Request, Response, Routes)
+  - Split `Di` into a static facade delegating to an instance-based `DiContainer`, one container per application execution
+  - Added `Di::set()`, `Di::has()`, and `Di::isRegistered()` for explicit service management
+  - `Di::get()` now enforces a strict contract: throws if the dependency is not explicitly registered (no more implicit auto-registration)
+  - Introduced `BootPipeline` and `BootStageInterface` for explicit, ordered boot sequences
+  - Extracted boot stages: `LoadHelpersStage`, `LoadEnvironmentStage`, `LoadAppConfigStage`, `SetupErrorHandlerStage`, `InitHttpStage`, `InitDebuggerStage`
+  - Removed `AppTrait`; all adapter boot logic moved to pipeline stages and focused private methods in `WebAppTrait`/`ConsoleAppTrait`
+- **BREAKING:** Converted `Request` and `Response` from static facades to instance-based classes (#454):
+  - Merged `HttpRequest`/`HttpResponse` wrapper layer directly into `Request`/`Response`
+  - All request/response access now goes through `request()` and `response()` helper functions
+- **BREAKING:** Removed all static singleton patterns from core services (#381, #382):
+  - Migrated all 12 first-party factories (Auth, Archive, Cache, Captcha, Cryptor, FileSystem, Lang, Logger, Mailer, Renderer, Session, View) from static instance caches to DI-managed lifetimes
+  - Migrated service singletons to DI ownership: Cookie, Config, Environment, Server, AssetManager, Csrf, Database, MailTrap, Debugger, ViewCache, ErrorHandler, HookManager, ModuleLoader
+- **BREAKING:** `Environment` class is no longer a static singleton (#456):
+  - Uses `Dotenv::createArrayBacked()` for isolated, deterministic env loading
+  - New `environment()` helper function and shorthand check methods: `isProduction()`, `isTesting()`, `isStaging()`, `isDevelopment()`, `isLocal()`
+  - `env()` helper now delegates through `environment()->getValue()`
+
 - **BREAKING:** Minimum PHP version requirement raised from 7.3 to 7.4
 - Modernized codebase with PHP 7.4+ syntax using Rector:
   - Array destructuring: `list()` → `[]`
@@ -48,6 +67,11 @@
 - Fixed cURL error message assertions for cross-version compatibility
 
 ### Added
+- `AppContext` class representing the runtime identity of a single application execution
+- `DiContainer` instance-based dependency injection container, isolated per execution
+- `BootPipeline` and `BootStageInterface` for declarative, ordered boot sequences
+- `environment()` global helper and `Environment` shorthand methods (`isProduction()`, `isTesting()`, etc.)
+- Lazy registration guards (`Di::register()` + `Di::isRegistered()`) at all DI call sites for explicit dependency management
 - Rector as dev dependency for automated code refactoring
 - Additional PHP extensions required in CI: `bcmath`, `gd`, `zip`
 - PHPUnit strict testing flags: `--fail-on-warning`, `--fail-on-risky`
@@ -75,3 +99,9 @@
 ### Removed
 - Support for PHP 7.3 and earlier versions
 - Legacy routing static state and implicit controller resolution via `RouteController`
+- `AppTrait` — replaced by boot pipeline stages and adapter-specific traits
+- Static singleton patterns from all core services and factories
+- `Environment::getInstance()` static singleton accessor
+- `HttpRequest`/`HttpResponse` static facade wrapper classes (merged into `Request`/`Response`)
+- Implicit auto-registration in `Di::get()` — all dependencies must be explicitly registered
+- `RegisterCoreDependenciesStage` and `dependencies.php` — replaced by lazy registration at call sites

src/App/Adapters/AppAdapter.php

@@ -16,32 +16,19 @@
 
 namespace Quantum\App\Adapters;
 
-use Quantum\App\Exceptions\BaseException;
 use Quantum\App\Contracts\AppInterface;
-use Quantum\Di\Exceptions\DiException;
-use Quantum\App\Traits\AppTrait;
-use ReflectionException;
+use Quantum\App\AppContext;
 
 /**
  * Class AppAdapter
  * @package Quantum\App
  */
 abstract class AppAdapter implements AppInterface
 {
-    use AppTrait;
+    protected AppContext $context;
 
-    private static string $baseDir;
-
-    /**
-     * @throws BaseException
-     * @throws DiException
-     * @throws ReflectionException
-     */
-    public function __construct()
+    public function __construct(AppContext $context)
     {
-        $this->loadCoreDependencies();
-        $this->loadComponentHelperFunctions();
-        $this->loadAppHelperFunctions();
-        $this->loadModuleHelperFunctions();
+        $this->context = $context;
     }
 }

src/App/Adapters/ConsoleAppAdapter.php

@@ -18,15 +18,16 @@
 
 use Symfony\Component\Console\Output\ConsoleOutput;
 use Quantum\App\Exceptions\StopExecutionException;
-use Quantum\Environment\Exceptions\EnvException;
 use Symfony\Component\Console\Input\ArgvInput;
-use Quantum\Config\Exceptions\ConfigException;
+use Quantum\App\Stages\SetupErrorHandlerStage;
+use Quantum\App\Stages\LoadEnvironmentStage;
 use Symfony\Component\Console\Application;
-use Quantum\Lang\Exceptions\LangException;
-use Quantum\App\Exceptions\BaseException;
+use Quantum\App\Stages\LoadAppConfigStage;
+use Quantum\App\Stages\LoadHelpersStage;
 use Quantum\App\Traits\ConsoleAppTrait;
-use Quantum\Di\Exceptions\DiException;
-use ReflectionException;
+use Quantum\App\BootPipeline;
+use Quantum\App\AppContext;
+use Exception;
 
 if (!defined('DS')) {
     define('DS', DIRECTORY_SEPARATOR);
@@ -46,18 +47,30 @@ class ConsoleAppAdapter extends AppAdapter
 
     protected Application $application;
 
-    public function __construct()
+    public function __construct(AppContext $context)
     {
-        parent::__construct();
+        parent::__construct($context);
 
         $this->input = new ArgvInput();
         $this->output = new ConsoleOutput();
 
         $commandName = $this->input->getFirstArgument();
 
+        $stages = [
+            new LoadHelpersStage(),
+        ];
+
         if ($commandName !== 'core:env') {
-            $this->loadEnvironment();
-            $this->loadAppConfig();
+            $stages[] = new LoadEnvironmentStage();
+            $stages[] = new LoadAppConfigStage();
+            $stages[] = new SetupErrorHandlerStage();
+        }
+
+        $pipeline = new BootPipeline($stages);
+        $pipeline->run($this->context);
+
+        if ($commandName !== 'core:env') {
+            environment()->setMutable(true);
         }
 
         $this->application = $this->createApplication(
@@ -67,23 +80,14 @@ public function __construct()
     }
 
     /**
-     * @throws DiException
-     * @throws EnvException
-     * @throws BaseException
-     * @throws ConfigException
-     * @throws LangException
-     * @throws ReflectionException
-     */
+    * @throws Exception
+    */
     public function start(): ?int
     {
         try {
-            $this->loadLanguage();
-
             $this->registerCoreCommands();
             $this->registerAppCommands();
 
-            $this->setupErrorHandler();
-
             $this->validateCommand();
 
             $exitCode = $this->application->run($this->input, $this->output);

src/App/Adapters/WebAppAdapter.php

@@ -17,32 +17,27 @@
 namespace Quantum\App\Adapters;
 
 use Quantum\Middleware\Exceptions\MiddlewareException;
-use Quantum\Database\Exceptions\DatabaseException;
 use Quantum\App\Exceptions\StopExecutionException;
-use Quantum\Session\Exceptions\SessionException;
-use Quantum\Environment\Exceptions\EnvException;
+use Quantum\Loader\Exceptions\LoaderException;
 use Quantum\Module\Exceptions\ModuleException;
 use Quantum\Config\Exceptions\ConfigException;
+use Quantum\App\Stages\SetupErrorHandlerStage;
 use Quantum\Router\Exceptions\RouteException;
-use Quantum\Http\Exceptions\HttpException;
+use Quantum\App\Stages\LoadEnvironmentStage;
 use Quantum\Csrf\Exceptions\CsrfException;
 use Quantum\Lang\Exceptions\LangException;
-use Quantum\Middleware\MiddlewareManager;
+use Quantum\App\Stages\LoadAppConfigStage;
 use Quantum\App\Exceptions\BaseException;
+use Quantum\App\Stages\InitDebuggerStage;
+use Quantum\Middleware\MiddlewareManager;
+use Quantum\App\Stages\LoadHelpersStage;
+use Quantum\App\Stages\InitHttpStage;
 use Quantum\Di\Exceptions\DiException;
 use Quantum\App\Traits\WebAppTrait;
-use Quantum\Router\RouteCollection;
 use Quantum\Router\RouteDispatcher;
-use Quantum\Router\RouteBuilder;
-use Quantum\Module\ModuleLoader;
-use DebugBar\DebugBarException;
-use Quantum\Router\RouteFinder;
-use Quantum\Debugger\Debugger;
-use Quantum\Hook\HookManager;
-use Quantum\Http\Response;
-use Quantum\Http\Request;
+use Quantum\App\BootPipeline;
+use Quantum\App\AppContext;
 use ReflectionException;
-use Quantum\Di\Di;
 
 /**
  * Class WebAppAdapter
@@ -52,110 +47,51 @@ class WebAppAdapter extends AppAdapter
 {
     use WebAppTrait;
 
-    /**
-     * @var Request
-     */
-    private $request;
-
-    /**
-     * @var Response
-     */
-    private $response;
-
-    /**
-     * @throws BaseException
-     * @throws ConfigException
-     * @throws DiException
-     * @throws EnvException
-     * @throws ReflectionException
-     */
-    public function __construct()
+    public function __construct(AppContext $context)
     {
-        parent::__construct();
-
-        $this->loadEnvironment();
-        $this->loadAppConfig();
-
-        $this->request = Di::get(Request::class);
-        $this->response = Di::get(Response::class);
+        parent::__construct($context);
+
+        $pipeline = new BootPipeline([
+            new LoadHelpersStage(),
+            new LoadEnvironmentStage(),
+            new LoadAppConfigStage(),
+            new SetupErrorHandlerStage(),
+            new InitHttpStage(),
+            new InitDebuggerStage(),
+        ]);
+
+        $pipeline->run($this->context);
     }
 
     /**
      * Starts the web app
-     * @throws BaseException
-     * @throws ConfigException
-     * @throws CsrfException
-     * @throws DatabaseException
-     * @throws DebugBarException
-     * @throws DiException
-     * @throws HttpException
-     * @throws LangException
-     * @throws ModuleException
-     * @throws ReflectionException
-     * @throws RouteException
-     * @throws SessionException
-     * @throws MiddlewareException
+     * @throws ModuleException|MiddlewareException|LangException|RouteException|CsrfException|ConfigException|DiException|BaseException|LoaderException|ReflectionException
      */
     public function start(): ?int
     {
         try {
-            $this->initializeRequestResponse($this->request, $this->response);
-
-            if ($this->request->isMethod('OPTIONS')) {
+            if (request()->isMethod('OPTIONS')) {
                 stop();
             }
 
-            $this->setupErrorHandler();
-            $this->initializeDebugger();
+            $this->loadModules();
 
-            $moduleLoader = ModuleLoader::getInstance();
-
-            $builder = new RouteBuilder();
-
-            $collection = $builder->build(
-                $moduleLoader->loadModulesRoutes(),
-                $moduleLoader->getModuleConfigs()
-            );
-
-            Di::set(RouteCollection::class, $collection);
-
-            $routeFinder = new RouteFinder($collection);
-
-            $matchedRoute = $routeFinder->find($this->request);
-
-            if ($matchedRoute === null) {
-                page_not_found();
-                stop();
-            }
-
-            $this->request->setMatchedRoute($matchedRoute);
+            $matchedRoute = $this->resolveRoute();
 
             $this->loadLanguage();
 
-            $debugger = Debugger::getInstance();
-            if ($debugger->isEnabled()) {
-                $debugger->addToStoreCell(Debugger::HOOKS, 'info', HookManager::getInstance()->getRegistered());
-            }
-
-            $middlewareManager = new MiddlewareManager($matchedRoute);
-
-            [$this->request, $this->response] = $middlewareManager->applyMiddlewares(
-                $this->request,
-                $this->response
-            );
+            $this->logDebugInfo();
 
-            $viewCache = $this->setupViewCache();
+            [$request, $response] = (new MiddlewareManager($matchedRoute))->applyMiddlewares(request(), response());
 
-            if ($viewCache->serveCachedView(route_uri() ?? '', $this->response)) {
+            if ($this->setupViewCache()->serveCachedView(route_uri() ?? '', $response)) {
                 stop();
             }
 
-            $dispatcher = new RouteDispatcher();
-            $dispatcher->dispatch($matchedRoute, $this->request);
+            (new RouteDispatcher())->dispatch($matchedRoute, $request);
             stop();
         } catch (StopExecutionException $exception) {
-            $this->handleCors($this->response);
-            $this->response->send();
+            $this->sendResponse();
 
             return $exception->getCode();
         }

src/App/App.php

@@ -29,7 +29,7 @@
  */
 class App
 {
-    private static ?string $baseDir = null;
+    private static ?AppContext $context = null;
 
     private AppInterface $adapter;
 
@@ -38,18 +38,23 @@ public function __construct(AppInterface $adapter)
         $this->adapter = $adapter;
     }
 
-    public static function setBaseDir(string $baseDir): void
+    public static function setContext(AppContext $context): void
     {
-        self::$baseDir = $baseDir;
+        self::$context = $context;
     }
 
-    public static function getBaseDir(): string
+    public static function getContext(): AppContext
     {
-        if (self::$baseDir === null || self::$baseDir === '') {
-            throw new RuntimeException('Base directory is not initialized.');
+        if (self::$context === null) {
+            throw new RuntimeException('AppContext is not initialized.');
         }
 
-        return self::$baseDir;
+        return self::$context;
+    }
+
+    public static function getBaseDir(): string
+    {
+        return self::getContext()->getBaseDir();
     }
 
     public function getAdapter(): AppInterface