quantum-php / quantum-php/framework
Refactor Framework to Package-Based Monorepo Structure
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 36
- Forks
- 22
- PR merge metrics
- No merged PRs in 30d
Description
Description
Currently, the framework is a monolithic library with a mix of "Libraries", "Modules", and core components in src/. This structure creates tight coupling and unclear boundaries (e.g., Config depending on Loader which depends on App).
We propose moving to a Monorepo Structure using a packages/ directory. This will allow for:
- Strict Decoupling: Each package has its own
srcand explicit dependencies. - Clearer Architecture: Separation of
Core(Kernel) fromApp(Adapters) andFeatures(Http, Database). - Future-Proofing: Easier to extract/publish standalone components.
Proposed Structure
The src/ directory will be dissolved into packages/.
/packages
├── Core/ (Bootstrap: App Kernel, Container, Config, Loader, Env, Hook)
├── App/ (Glue: Web/Console Adapters, Traits)
├── Http/ (Request, Response, Middleware)
├── Console/ (Commands, Output)
├── Pipeline/ (New Shared Pipe Builder)
├── Database/ (ORM, Migrations)
├── Security/ (Csrf, Encryption, Hasher)
├── ... (See full plan for Auth, Session, etc.)
Synergy with Issue #373 (App Bootstrapping)
This refactoring directly supports the goals of Issue #373:
- Boot Pipeline: The new
packages/Pipelinecomponent enables the "Boot Stages" logic. - Explicit Kernel: Moving
App,Container, andLoadertopackages/Corephysically defines the "Application Execution Boundary". - DI Ownership: Centralizing
ContainerinCoremakes it the clear owner of service lifetimes.
Critical Changes
- Split
App:src/App/App.phpmoves topackages/Core.src/App/Adaptersmoves topackages/App. This resolves the circular dependency between the Kernel and the Http layer. - Config in Core:
src/Configmoves topackages/Coreto resolve dependencies onLoaderandDi. - Security Grouping:
Csrf,Encryption, andHasherare grouped underpackages/Security.
Migration Checklist
- Create
packages/directory structure. - Phase 1: Core: Move
App,Di,Environment,Hook,Loader,Config,Tracertopackages/Core. - Phase 2: Features: Move
Auth,Database,Session,View,Validationtopackages/*. - Phase 3: Http/Console: Move
Http,Console,Routertopackages/*. - Phase 4: App Glue: Move
AdaptersandTraitstopackages/App. - Phase 5: Cleanup: Remove empty
src/directories. - Phase 6: Wiring: Update root
composer.jsonautoloading to mapQuantum\to these new paths. - Run tests to verify the move.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the current src/ layout, the proposed packages/ phases, and root composer.json autoloading. Work through the migration checklist from Core through App Glue, then run the test suite to verify the move. Done means the planned packages exist, src/ is removed, autoloading is updated, and tests pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- backend
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100