quantum-php / quantum-php/framework

Remove Loader as a top-level package and split its responsibilities across Config, Environment, and helper boot

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

Nobody has claimed this yet.

config
Dominant language
PHP
Stars
36
Forks
22
PR merge metrics
No merged PRs in 30d

Description

Summary

Refactor the current Loader package out of the top-level framework architecture.

Its responsibilities should be split into the places that actually own them:

  • hierarchical config file resolution should belong to Config
  • environment bootstrap file resolution should belong to Environment
  • helper loading should be handled separately and should not justify Loader remaining its own package

Why

Right now Loader acts like a standalone package, but the code shows it is mostly a shared utility for unrelated internal concerns.

Current usages include:

  • Config loading hierarchical config files
  • Environment loading env bootstrap config
  • UploadConfigProvider probing/loading optional uploads config
  • helper directory loading during boot

This is a weak package boundary.

The most obvious mismatch is Environment: environment bootstrap should not depend on a separate generic loader package just to resolve a small config file that determines which .env file to load.

Current Behavior to Preserve

For config loading, preserve the current hierarchical resolution behavior:

  • resolve the module-scoped file first
  • if the setup is hierarchical and the module file does not exist, fall back to the shared file

For config imports that currently means:

  • modules/<module>/config/<file>.php
  • then shared/config/<file>.php

Proposed Changes

  • remove Loader as a standalone top-level package concept
  • move hierarchical config file resolution into Config
  • move environment bootstrap file resolution into Environment
  • update UploadConfigProvider so its optional config lookup follows the new ownership boundaries
  • keep helper loading as a separate concern and do not let it define the long-term architecture of Loader

Acceptance Criteria

  • Loader is no longer treated as a standalone top-level package
  • Config owns hierarchical config file resolution
  • Environment no longer relies on Loader for its bootstrap config resolution
  • UploadConfigProvider no longer relies on a generic top-level loader abstraction if a more local ownership model is available
  • existing hierarchical config behavior remains compatible
  • tests and docs are updated as needed

Notes

Relevant code:

  • src/Loader/Loader.php
  • src/Loader/Setup.php
  • src/Config/Config.php
  • src/Environment/Environment.php
  • src/Storage/Uploads/UploadConfigProvider.php
  • src/App/Stages/LoadHelpersStage.php

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 tracing the responsibilities and usages across src/Loader/Loader.php, src/Loader/Setup.php, src/Config/Config.php, src/Environment/Environment.php, src/Storage/Uploads/UploadConfigProvider.php, and src/App/Stages/LoadHelpersStage.php. Verify the existing hierarchical resolution behavior and identify the tests and docs affected before separating ownership. Done means Loader is no longer a top-level package, the new owners preserve compatible behavior, and tests and docs are updated as needed.

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
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.