> 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/core-concepts/modules.md). # Modules ## Overview Modules are one of the core organizational ideas in the Quantum PHP Framework. Instead of placing everything in one flat application structure, Quantum is designed so that related routes, controllers, views, services, and configuration can live together inside a module. ## Core idea A module is a self-contained feature area. Depending on the kind of module, it can contain things like: * routes * controllers * views * middlewares * services * models * DTOs * transformers * config * assets * resources So instead of thinking only in terms of one global controller folder and one global view folder, Quantum encourages grouping related application parts together. ## Why modules matter in Quantum Modules are part of the application startup flow, not just a project-organization preference. ## Module loading process The framework's module loader manages application startup in two phases: 1. **Dependency Registration**: During initialization, the loader scans modules listed in `shared/config/modules.php` and loads dependencies from `modules//config/dependencies.php` **only for modules marked as enabled**. 2. **Route Loading**: After dependencies are registered, the loader loads route definitions from `modules//routes/routes.php` **only for modules marked as enabled**. Modules directly affect both bootstrap behavior and route availability. ## Where module configuration lives The framework expects module configuration in: ``` shared/config/modules.php ``` This file controls module-level options such as whether a module is enabled. ## Where module routes live For each module, route definitions are expected at: ``` modules//routes/routes.php ``` Each module contributes its own routes instead of relying on one global route file. ## Where module dependencies can live A module can also provide its own dependency definitions through: ``` modules//config/dependencies.php ``` This is where module-specific service bindings are declared. ## What a module can contain The templates make the module shape clear. ### Default API module template Includes areas such as: * `Controllers/` * `config/` * `routes/` ### Default Web module template Includes areas such as: * `Controllers/` * `Views/` * `routes/` * `assets/` ### Demo module templates Demo templates also include: * `DTOs/` * `Enums/` * `Middlewares/` * `Models/` * `Services/` * `Transformers/` * `resources/` Modules can scale from small routing units to full feature packages. ## Fresh skeleton vs active modules A fresh project skeleton may not show populated module directories immediately, but module generation and module-driven routing are built in. In fact, Quantum includes a CLI command for generating modules: ```bash php qt module:generate ``` This command uses built-in templates such as: * `DefaultWeb` * `DefaultApi` * other templates available in the framework * an empty or lightly populated fresh project * a modular application after modules are generated and enabled ## Modules and route prefixes Module configuration can also contribute route prefix behavior. The route builder reads module configuration and keeps module and prefix information attached to routes. This helps the framework organize routes in a module-aware way rather than as unrelated URL entries. ## Modules and testing Project tests also reinforce the module model. There are feature tests under paths like: ``` tests/Feature/modules/Api/ ``` This confirms modules are treated as an application boundary in practice. ## When to use modules Modules are especially useful when: * a feature has its own routes and controllers * a feature needs its own views or API endpoints * you want clearer separation between application areas * the application is growing and one shared code area is no longer enough ## Practical view A good short way to think about Quantum modules is: * a module groups related feature code together * routes often start from modules * controllers and views often live inside modules * the framework loads modules during startup * modules help keep larger applications organized ## What to read next After this overview, continue with: * [Middleware](/docs/core-concepts/middleware.md) * [Request Handling](/docs/core-concepts/request.md) * [Services](/docs/core-concepts/services.md) * [Configuration](/docs/advanced-features/configuration.md) * [First App](/docs/getting-started/first-app.md) --- # 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/core-concepts/modules.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.