Refactor and improve Loader documentation and properties

[fadrian06]

This pull request refactors and improves the Loader class in flight/core/Loader.php for better type safety, clarity, and maintainability. The main changes include updating type annotations, improving method signatures, and enhancing the documentation for better understanding and IDE support.

Type and Documentation Improvements:

• Updated type annotations and PHPDoc comments throughout the Loader class for more precise types, especially for callable factories, constructor arguments, and callbacks. [1] [2]
• Replaced generic Exception usage with Throwable to allow for broader error handling.
• Improved docblocks for methods like register, unregister, load, and newInstance to clarify parameter and return types. [1] [2]

Code Quality and Logic Enhancements:

• Refactored the load method for better readability and to use more descriptive variable names, as well as clarifying the logic for shared vs. new instances and after-instantiation callbacks.
• Simplified the newInstance method to use variadic arguments and direct callable invocation with spread operator.
• Improved addDirectory to handle non-string and iterable inputs more robustly, and prevent duplicate directory entries.

Minor Cleanups:

• Condensed and clarified inline comments and docblocks for brevity and accuracy. [1] [2]
• Updated method and parameter descriptions for consistency and clarity. [1] [2] [3]

[Copilot]

Pull request overview

This PR refactors flight/core/Loader.php to improve type annotations and readability around class registration/instantiation and autoload directory handling, aiming for better static analysis and clearer intent in the core dependency loader.

Changes:

• Refined PHPDoc types for registered factories/callbacks and clarified method documentation.
• Refactored load() / newInstance() for clearer shared vs. new instance logic and simpler callable invocation.
• Hardened addDirectory() input handling (iterables vs. non-strings) and duplicate prevention.

Suppressed comments (1)

flight/core/Loader.php:197

• The PHPDoc for addDirectory() says $dir is string|string[], but the method accepts any iterable (arrays or Traversable) via is_iterable(). Align the annotation with the actual accepted input type.

     * @param string|string[] $dir Directory path.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.