From 8523025cb5d3170a374bb2b66eac300aa01ae533 Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 15:09:42 -0400
Subject: [PATCH 01/18] rewrap loader description

---
 flight/core/Loader.php | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 92deceb6..71af47ee 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -8,10 +8,9 @@
 use Exception;
 
 /**
- * The Loader class is responsible for loading objects. It maintains
- * a list of reusable class instances and can generate a new class
- * instances with custom initialization parameters. It also performs
- * class autoloading.
+ * Responsible for loading objects. It maintains a list of reusable class
+ * instances and can generate a new class instances with custom initialization
+ * parameters. It also performs class autoloading.
  *
  * @license MIT, http://flightphp.com/license
  * @copyright Copyright (c) 2011, Mike Cao <mike@mikecao.com>

From 30193dedac0074d27261e06821c1dd90968cbaee Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 15:10:59 -0400
Subject: [PATCH 02/18] compact loader properties docblocks

---
 flight/core/Loader.php | 22 ++++------------------
 1 file changed, 4 insertions(+), 18 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 71af47ee..72e15259 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -17,30 +17,16 @@
  */
 class Loader
 {
-    /**
-     * Registered classes.
-     *
-     * @var array<string, array{class-string|Closure(): object, array<int, mixed>, ?callable}> $classes
-     */
+    /** @var array<string, array{class-string|Closure(): object, array<int, mixed>, ?callable}> Registered classes */
     protected array $classes = [];
 
-    /**
-     * If this is disabled, classes can load with underscores
-     */
+    /** If this is disabled, classes can load with underscores */
     protected static bool $v2ClassLoading = true;
 
-    /**
-     * Class instances.
-     *
-     * @var array<string, object>
-     */
+    /** @var array<string, object> Class instances */
     protected array $instances = [];
 
-    /**
-     * Autoload directories.
-     *
-     * @var array<int, string>
-     */
+    /** @var array<int, string> Autoload directories */
     protected static array $dirs = [];
 
     /**

From 7f1b976ca1b1b4a790edc144cbf4e2d2f6589d2f Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 15:11:56 -0400
Subject: [PATCH 03/18] simplify loader properties typehints

---
 flight/core/Loader.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 72e15259..a9eb3616 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -17,7 +17,7 @@
  */
 class Loader
 {
-    /** @var array<string, array{class-string|Closure(): object, array<int, mixed>, ?callable}> Registered classes */
+    /** @var array<string, array{class-string<object>|callable(): object, mixed[], ?callable}> Registered classes */
     protected array $classes = [];
 
     /** If this is disabled, classes can load with underscores */
@@ -26,7 +26,7 @@ class Loader
     /** @var array<string, object> Class instances */
     protected array $instances = [];
 
-    /** @var array<int, string> Autoload directories */
+    /** @var string[] Autoload directories */
     protected static array $dirs = [];
 
     /**

From 85f5431a4020b3838b37a096dd51899266f16f88 Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 15:18:30 -0400
Subject: [PATCH 04/18] reduce loader classes property docblock line length

---
 flight/core/Loader.php | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index a9eb3616..9690d87f 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -17,7 +17,15 @@
  */
 class Loader
 {
-    /** @var array<string, array{class-string<object>|callable(): object, mixed[], ?callable}> Registered classes */
+    /**
+     * Registered classes.
+     *
+     * @var array<string, array{
+     *   class-string<object>|callable(): object,
+     *   mixed[],
+     *   ?callable(object $instance): void,
+     * }>
+     */
     protected array $classes = [];
 
     /** If this is disabled, classes can load with underscores */

From d196cc09e1f335156ea2b276be4ce46d8a218b59 Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 15:19:52 -0400
Subject: [PATCH 05/18] format Loader@register and Loader@unregister docblocks

---
 flight/core/Loader.php | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 9690d87f..2f952f09 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -40,12 +40,11 @@ class Loader
     /**
      * Registers a class.
      *
-     * @param string                                         $name     Registry name
-     * @param class-string<T>|(Closure(): T)                 $class    Class name or function to instantiate class
-     * @param array<int, mixed>                              $params   Class initialization parameters
-     * @param null|(Closure(T $instance): void)              $callback Function to call after object instantiation
-     *
      * @template T of object
+     * @param string $name Registry name.
+     * @param class-string<T>|callable(): T $class Class name or function to instantiate class.
+     * @param mixed[] $params Class initialization parameters.
+     * @param null|callable(T $instance): void $callback Function to call after object instantiation.
      */
     public function register(string $name, $class, array $params = [], ?callable $callback = null): void
     {
@@ -57,7 +56,7 @@ public function register(string $name, $class, array $params = [], ?callable $ca
     /**
      * Unregisters a class.
      *
-     * @param string $name Registry name
+     * @param string $name Registry name.
      */
     public function unregister(string $name): void
     {

From 6acbdb20829e8998147211c8f3f8ce0a1d612a9d Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 15:27:58 -0400
Subject: [PATCH 06/18] refactor Loader@load

---
 flight/core/Loader.php | 41 +++++++++++++++++++----------------------
 1 file changed, 19 insertions(+), 22 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 2f952f09..c81102c0 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -6,6 +6,7 @@
 
 use Closure;
 use Exception;
+use Throwable;
 
 /**
  * Responsible for loading objects. It maintains a list of reusable class
@@ -66,38 +67,34 @@ public function unregister(string $name): void
     /**
      * Loads a registered class.
      *
-     * @param string $name   Method name
-     * @param bool   $shared Shared instance
-     *
-     * @throws Exception
-     *
+     * @param string $name Method name.
+     * @param bool $shared Shared instance.
      * @return ?object Class instance
+     * @throws Throwable
      */
     public function load(string $name, bool $shared = true): ?object
     {
         $obj = null;
 
-        if (isset($this->classes[$name])) {
-            [0 => $class, 1 => $params, 2 => $callback] = $this->classes[$name];
+        if (!isset($this->classes[$name])) {
+            return null;
+        }
 
-            $exists = isset($this->instances[$name]);
+        [$class, $params, $callback] = $this->classes[$name];
+        $exists = isset($this->instances[$name]);
 
-            if ($shared) {
-                $obj = ($exists) ?
-                    $this->getInstance($name) :
-                    $this->newInstance($class, $params);
+        if ($shared) {
+            $obj = $exists
+                ? $this->getInstance($name)
+                : $this->newInstance($class, $params);
 
-                if (!$exists) {
-                    $this->instances[$name] = $obj;
-                }
-            } else {
-                $obj = $this->newInstance($class, $params);
-            }
+            $this->instances[$name] ??= $obj;
+        } else {
+            $obj = $this->newInstance($class, $params);
+        }
 
-            if ($callback && (!$shared || !$exists)) {
-                $ref = [&$obj];
-                \call_user_func_array($callback, $ref);
-            }
+        if ($callback && (!$shared || !$exists)) {
+            $callback($obj);
         }
 
         return $obj;

From d9b01781e6482e08651fa347344e29e5be8004c8 Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 15:53:28 -0400
Subject: [PATCH 07/18] rewrite Loader docblock

---
 flight/core/Loader.php | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index c81102c0..9ac5ac66 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -9,9 +9,9 @@
 use Throwable;
 
 /**
- * Responsible for loading objects. It maintains a list of reusable class
- * instances and can generate a new class instances with custom initialization
- * parameters. It also performs class autoloading.
+ * Responsible for instantiating classes. It maintains a list of reusable
+ * instances and can generate new instances with custom constructor arguments.
+ * It also performs automatic class loading.
  *
  * @license MIT, http://flightphp.com/license
  * @copyright Copyright (c) 2011, Mike Cao <mike@mikecao.com>

From ff5e90c592aaf1c2d24894d8ff1b74099e87486d Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 16:42:25 -0400
Subject: [PATCH 08/18] define class factory callable arguments typehint

---
 flight/core/Loader.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 9ac5ac66..2091be85 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -22,7 +22,7 @@ class Loader
      * Registered classes.
      *
      * @var array<string, array{
-     *   class-string<object>|callable(): object,
+     *   class-string<object>|callable(mixed ...$constructorArguments): object,
      *   mixed[],
      *   ?callable(object $instance): void,
      * }>

From d9406bbf24be40126ed2daddd031e62aefc82cf7 Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 16:43:12 -0400
Subject: [PATCH 09/18] improve Loader@register docblocks

---
 flight/core/Loader.php | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 2091be85..50b4023c 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -42,15 +42,14 @@ class Loader
      * Registers a class.
      *
      * @template T of object
-     * @param string $name Registry name.
-     * @param class-string<T>|callable(): T $class Class name or function to instantiate class.
-     * @param mixed[] $params Class initialization parameters.
-     * @param null|callable(T $instance): void $callback Function to call after object instantiation.
+     * @param string $name Class alias.
+     * @param class-string<T>|callable(mixed ...$constructorArguments): T $class Class factory.
+     * @param mixed[] $params Class constructor arguments.
+     * @param ?callable(T $instance): void $callback After instantiation callable.
      */
     public function register(string $name, $class, array $params = [], ?callable $callback = null): void
     {
         unset($this->instances[$name]);
-
         $this->classes[$name] = [$class, $params, $callback];
     }
 

From 1519e0cf3075de4f3818fbd6b5b52bf50552d3bd Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 16:43:35 -0400
Subject: [PATCH 10/18] improve Loader@unregister $name param docblock

---
 flight/core/Loader.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 50b4023c..4b048b7c 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -56,7 +56,7 @@ public function register(string $name, $class, array $params = [], ?callable $ca
     /**
      * Unregisters a class.
      *
-     * @param string $name Registry name.
+     * @param string $name Class alias.
      */
     public function unregister(string $name): void
     {

From 712792006fdeed036ff5f4a38b373d9f3e874d14 Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 16:44:07 -0400
Subject: [PATCH 11/18] refactor Loader@load with better names and docblock

---
 flight/core/Loader.php | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 4b048b7c..ce71f1d1 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -64,39 +64,39 @@ public function unregister(string $name): void
     }
 
     /**
-     * Loads a registered class.
+     * Gets an instance of a registered class.
      *
-     * @param string $name Method name.
-     * @param bool $shared Shared instance.
-     * @return ?object Class instance
+     * @param string $name Class alias.
+     * @param bool $shared Whether to return a shared instance or create a new one.
+     * @return ?object
      * @throws Throwable
      */
     public function load(string $name, bool $shared = true): ?object
     {
-        $obj = null;
+        $instance = null;
 
         if (!isset($this->classes[$name])) {
             return null;
         }
 
-        [$class, $params, $callback] = $this->classes[$name];
+        [$factory, $constructorArguments, $onAfterInstantiating] = $this->classes[$name];
         $exists = isset($this->instances[$name]);
 
         if ($shared) {
-            $obj = $exists
+            $instance = $exists
                 ? $this->getInstance($name)
-                : $this->newInstance($class, $params);
+                : $this->newInstance($factory, $constructorArguments);
 
-            $this->instances[$name] ??= $obj;
+            $this->instances[$name] ??= $instance;
         } else {
-            $obj = $this->newInstance($class, $params);
+            $instance = $this->newInstance($factory, $constructorArguments);
         }
 
-        if ($callback && (!$shared || !$exists)) {
-            $callback($obj);
+        if ($onAfterInstantiating && (!$shared || !$exists)) {
+            $onAfterInstantiating($instance);
         }
 
-        return $obj;
+        return $instance;
     }
 
     /**

From 5a83743cc7d01a9c4e4a12cd0a49eb19cdc59626 Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 16:44:27 -0400
Subject: [PATCH 12/18] simplify Loader@getInstance docblock

---
 flight/core/Loader.php | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index ce71f1d1..f85e7a7b 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -100,11 +100,10 @@ public function load(string $name, bool $shared = true): ?object
     }
 
     /**
-     * Gets a single instance of a class.
+     * Gets a single instance.
      *
-     * @param string $name Instance name
-     *
-     * @return ?object Class instance
+     * @param string $name Class alias.
+     * @return ?object
      */
     public function getInstance(string $name): ?object
     {

From 09e222c0fa9c00cc230bc278d4a6523683299572 Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 16:44:46 -0400
Subject: [PATCH 13/18] simplify Loader@newInstance

---
 flight/core/Loader.php | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index f85e7a7b..9499755f 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -113,19 +113,16 @@ public function getInstance(string $name): ?object
     /**
      * Gets a new instance of a class.
      *
-     * @param class-string<T>|Closure(): class-string<T> $class  Class name or callback function to instantiate class
-     * @param array<int, string>           $params Class initialization parameters
-     *
-     * @template T of object
-     *
-     * @throws Exception
-     *
-     * @return T Class instance
+     * @template T of object = object
+     * @param class-string<T>|callable(mixed ...$constructorArguments): T $class Class factory.
+     * @param string[] $params Class constructor arguments.
+     * @return T
+     * @throws Throwable
      */
-    public function newInstance($class, array $params = [])
+    public function newInstance($class, array $params = []): object
     {
-        if (\is_callable($class)) {
-            return \call_user_func_array($class, $params);
+        if (is_callable($class)) {
+            return $class(...$params);
         }
 
         return new $class(...$params);

From 89a9decc0bbfcfeb91b720768cc28c56cb3a74bb Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 16:46:11 -0400
Subject: [PATCH 14/18] improve Loader@get docblock

---
 flight/core/Loader.php | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 9499755f..fdf6acb5 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -129,11 +129,14 @@ public function newInstance($class, array $params = []): object
     }
 
     /**
-     * Gets a registered callable
+     * Gets a registered class factory, constructor arguments and after instantiation callable.
      *
-     * @param string $name Registry name
-     *
-     * @return mixed Class information or null if not registered
+     * @param string $name Class alias.
+     * @return ?array{
+     *   class-string<object>|callable(mixed ...$constructorArguments): object,
+     *   mixed[],
+     *   ?callable(object $instance): void,
+     * }
      */
     public function get(string $name)
     {

From 77e68ea77bd93f5d420896c17e0a8fe4bef8b92a Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 16:46:25 -0400
Subject: [PATCH 15/18] improve Loader@reset docblock

---
 flight/core/Loader.php | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index fdf6acb5..90ae96c1 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -143,9 +143,7 @@ public function get(string $name)
         return $this->classes[$name] ?? null;
     }
 
-    /**
-     * Resets the object to the initial state.
-     */
+    /** Resets the Loader by clearing registered classes and instances */
     public function reset(): void
     {
         $this->classes = [];

From 2fac34fbb7d20c3b4f7b9d12e8e6cdba3c51d999 Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 16:57:39 -0400
Subject: [PATCH 16/18] refactor Loader@autoload, Loader@addDirectory and
 Loader@setV2ClassLoading

---
 flight/core/Loader.php | 32 ++++++++++++++++++--------------
 1 file changed, 18 insertions(+), 14 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 90ae96c1..87ab8f00 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -4,8 +4,6 @@
 
 namespace flight\core;
 
-use Closure;
-use Exception;
 use Throwable;
 
 /**
@@ -155,8 +153,8 @@ public function reset(): void
     /**
      * Starts/stops autoloader.
      *
-     * @param bool  $enabled Enable/disable autoloading
-     * @param string|iterable<int, string> $dirs    Autoload directories
+     * @param bool $enabled Enable/disable autoloading.
+     * @param string|string[] $dirs Autoload directories.
      */
     public static function autoload(bool $enabled = true, $dirs = []): void
     {
@@ -196,7 +194,7 @@ public static function loadClass(string $class): void
     /**
      * Adds a directory for autoloading classes.
      *
-     * @param string|iterable<int, string> $dir Directory path
+     * @param string|string[] $dir Directory path.
      */
     public static function addDirectory($dir): void
     {
@@ -204,22 +202,28 @@ public static function addDirectory($dir): void
             foreach ($dir as $value) {
                 self::addDirectory($value);
             }
-        } elseif (is_string($dir)) {
-            $dir = str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $dir);
 
-            if (!in_array($dir, self::$dirs, true)) {
-                self::$dirs[] = $dir;
-            }
+            return;
+        }
+
+        if (!is_string($dir)) {
+            return;
+        }
+
+        $dir = str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $dir);
+
+        if (in_array($dir, self::$dirs)) {
+            return;
         }
+
+        self::$dirs[] = $dir;
     }
 
 
     /**
-     * Sets the value for V2 class loading.
-     *
-     * @param bool $value The value to set for V2 class loading.
+     * Sets whether to allow class loading with underscores in class names.
      *
-     * @return void
+     * @param bool $value
      */
     public static function setV2ClassLoading(bool $value): void
     {

From 89c378cc94fb1e5ebb695f092138d6e18532fd71 Mon Sep 17 00:00:00 2001
From: fadrian06 <franyeradriansanchez@gmail.com>
Date: Sun, 23 Aug 2026 17:10:13 -0400
Subject: [PATCH 17/18] fix constructor arguments typehint

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 flight/core/Loader.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index 87ab8f00..f57ac806 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -113,7 +113,7 @@ public function getInstance(string $name): ?object
      *
      * @template T of object = object
      * @param class-string<T>|callable(mixed ...$constructorArguments): T $class Class factory.
-     * @param string[] $params Class constructor arguments.
+     * @param mixed[] $params Class constructor arguments.
      * @return T
      * @throws Throwable
      */

From 6a127b1f0f0814a188d2c573b223db9d97b850cb Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 23 Aug 2026 21:11:38 +0000
Subject: [PATCH 18/18] Clarify setV2ClassLoading() docblock to explain
 true/false behaviour

Co-authored-by: fadrian06 <109766973+fadrian06@users.noreply.github.com>
---
 flight/core/Loader.php | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/flight/core/Loader.php b/flight/core/Loader.php
index f57ac806..057e103f 100644
--- a/flight/core/Loader.php
+++ b/flight/core/Loader.php
@@ -221,9 +221,13 @@ public static function addDirectory($dir): void
 
 
     /**
-     * Sets whether to allow class loading with underscores in class names.
+     * Sets v2 class loading mode.
      *
-     * @param bool $value
+     * When true (default), underscores in class names are converted to directory
+     * separators (e.g. "Foo_Bar" loads "Foo/Bar.php"). Set to false to disable
+     * this conversion and treat underscores as literal characters in the filename.
+     *
+     * @param bool $value True to convert underscores to directory separators (v2 behaviour); false to disable.
      */
     public static function setV2ClassLoading(bool $value): void
     {