> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/loader/overview.md). # Overview The Loader package is Quantum's small file-loading utility. Use it when you need to: * load a PHP resource file from a module or shared directory * check whether a module-specific file exists before falling back to shared resources * include helper directories during bootstrap Most applications use it indirectly through higher-level packages such as Config, Environment, and Storage uploads. Reach for it directly when you are building package-level resource loading of your own. ## Package shape The package has two runtime classes: * `Quantum\Loader\Setup` describes what file should be resolved * `Quantum\Loader\Loader` resolves the path, checks existence, and `require`s the file It also ships `LoaderException` for missing-file failures. ## What it loads `Loader::load()` always loads a PHP file and returns whatever that file returns. That makes it a good fit for resource files such as: * config arrays * package metadata arrays * small PHP bootstrap resources It is not a template renderer, JSON reader, or recursive filesystem scanner. ## Resolution model A `Setup` object controls lookup using: * `pathPrefix` such as `config` * `fileName` such as `database` * `module` such as `Blog` * `hierarchical` fallback flag With `new Setup('config', 'database')`, lookup order is: 1. `modules//config/database.php` when a current module is available 2. `/.php` as the primary non-module path (for this example: `config/database.php`) 3. `shared/config/database.php` when hierarchical fallback is enabled So without a module, Loader first checks the primary path (`config/database.php`) and only then falls back to `shared/config/database.php`. ## Important constraints * `Setup` defaults `hierarchical` to `true`, so shared fallback is on unless you disable it. * `Setup` defaults the module to `request()->getCurrentModule()`, so request context changes where Loader looks unless you set the module explicitly. * A `Setup` object cannot be reset back to `null` module state through `setModule()`. If you want to drop a module override and go back to non-module resolution, create a fresh `Setup`. * `loadDir()` only includes `*.php` files from the exact directory pattern you pass in. It does not recurse into subdirectories. * `loadDir()` uses `require_once`, while `load()` uses `require`. Repeated `load()` calls can re-run a file. * Missing files raise `LoaderException` only when you call `load()` or `getFilePath()`. Use `fileExists()` when absence is expected. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://quantumphp.gitbook.io/docs/packages/loader/overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.