quantum-php / quantum-php/framework

Refactor Framework to Package-Based Monorepo Structure

Open
#418 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
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:

  1. Strict Decoupling: Each package has its own src and explicit dependencies.
  2. Clearer Architecture: Separation of Core (Kernel) from App (Adapters) and Features (Http, Database).
  3. 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/Pipeline component enables the "Boot Stages" logic.
  • Explicit Kernel: Moving App, Container, and Loader to packages/Core physically defines the "Application Execution Boundary".
  • DI Ownership: Centralizing Container in Core makes it the clear owner of service lifetimes.

Critical Changes

  • Split App: src/App/App.php moves to packages/Core. src/App/Adapters moves to packages/App. This resolves the circular dependency between the Kernel and the Http layer.
  • Config in Core: src/Config moves to packages/Core to resolve dependencies on Loader and Di.
  • Security Grouping: Csrf, Encryption, and Hasher are grouped under packages/Security.

Migration Checklist

  • Create packages/ directory structure.
  • Phase 1: Core: Move App, Di, Environment, Hook, Loader, Config, Tracer to packages/Core.
  • Phase 2: Features: Move Auth, Database, Session, View, Validation to packages/*.
  • Phase 3: Http/Console: Move Http, Console, Router to packages/*.
  • Phase 4: App Glue: Move Adapters and Traits to packages/App.
  • Phase 5: Cleanup: Remove empty src/ directories.
  • Phase 6: Wiring: Update root composer.json autoloading to map Quantum\ to these new paths.
  • Run tests to verify the move.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.