Skip to content

Deprecate the hierarchy flag of Config Setup #618

Open

Description

@armanist

Summary

Deprecate the hierarchical flag of Quantum\Config\Setup in 3.1.2, with no change in behavior. It is removed in 3.2.0.

Why

  • The flag controls one thing: when a config file is not found in the module's folder, Config::resolveFilePath() falls back to shared/<prefix>/<file>.php. That is a fallback or override rule, not a hierarchy. The name suggests the "hierarchical" in HMVC, which means nested sub-requests between MVC triads and has nothing to do with config lookup.
  • The flag defaults to true, and nothing in src turns it off: every new Setup('config', '<name>') call uses the default. Only SetupTest calls getHierarchy() and setHierarchy().
  • Turning it off is a trap. A global config such as new Setup('config', 'app') has no module, so its first path is <base>/config/app.php, which does not exist in a project. The files live in shared/config, and only the fallback finds them.

Proposed change

  • Mark Setup::setHierarchy(), Setup::getHierarchy() and the $hierarchical constructor parameter @deprecated, saying that the shared fallback is always on from 3.2.0.
  • Raise E_USER_DEPRECATED when the setter is called or when the constructor receives the third argument (func_num_args() > 2), with a message that names the removal in 3.2.0. The error handler already logs deprecations as warnings, so nothing stops. The default true does not raise anything.
  • Behavior stays exactly as it is.
  • Describe the lookup in the docs as the "shared fallback" or "lookup order", not as a "hierarchy" (advanced-features/configuration.md). That is a change in the docs repository.

Out of scope

  • Removing the flag: it is planned for 3.2.0, tracked in the removal ticket.

Breaking changes

  • None.

Acceptance criteria

  • the two methods and the constructor parameter are marked @deprecated
  • calling setHierarchy() or passing the third constructor argument raises E_USER_DEPRECATED, and the default call does not; a test covers both
  • the lookup result is unchanged for true and false, and the existing tests still pass
  • composer test, composer cs:check, composer phpstan and composer rector:check pass on every PHP version in the CI matrix
  • the changelog lists the deprecation

Activity

  1. added this to the 3.1.2 milestone on Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    configConfiguration package and loadingrefactoringtech debtTechnical debt reduction

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions