Skip to content

fix: merge module config by source priority and correct config docs - #707

Merged
markshust merged 2 commits into
developfrom
feature/docs-fixes-691-693
Nov 14, 2026
Merged

markshust merged 2 commits into
developfrom
feature/docs-fixes-691-693

Conversation

@markshust

Copy link
Copy Markdown
Collaborator

Summary

Fixes module config override priority and corrects the config, event and job docs.

Module config merges by source priority (#706) — breaking

Module config merged in plain dependency load order, so a vendor module that loaded after an app module overrode the app module's config (e.g. vendor/marko/cache/config/cache.php beat app/my-app/config/cache.php when the app module didn't require marko/cache). Bindings and global middleware already rank by source; config now does too:

  1. vendor modules
  2. modules/ modules
  3. app/ modules
  4. project-root config/ (wins)

Load order decides only within a tier. The new Marko\Config\ConfigModuleOrder applies this using BindingRegistry::SOURCE_PRIORITY. module.php (live boot) and ConfigCacheContributor (discovery:cache) both use it, so live and cached boots merge the same way.

Breaking: an app module's config now overrides a vendor module's config regardless of dependency order. Apps that relied on a vendor config winning should move that value to the project-root config/.

Config docs (#692)

  • config.md and getting-started/configuration.md give the four-step order. app/config/, which was never a config location, is gone from the examples and error messages.
  • New "Which Config Location to Use" section: module config/ ships defaults with the code, while the project-root config/ holds installation settings. Includes a table of where each kind of value goes.
  • .claude/architecture.md, debugbar.md and coming-from-magento.md match the four-step order.

Readonly event and job examples (#691)

readonly class X extends Event|Job is a fatal error, because Event and Job aren't readonly. The examples in concepts/events.md, guides/queues.md and packages/queue.md now use readonly promoted properties instead.

String-based events claim (#693)

.claude/architecture.md now says events are classes extending Marko\Core\Event\Event, dispatched through EventDispatcherInterface::dispatch().

Test plan

  • New tests for ConfigModuleOrder, the cache contributor and the module.php binding
  • composer ci: 14445 passed, 439 skipped; lint, PHPStan and docs lint clean
  • Each original docs example fails against the real Event/Job; each fixed one runs

Closes #691
Closes #692
Closes #693
Closes #706

🤖 Generated with Claude Code

https://claude.ai/code/session_017KaHtX9QzJB5ZedzkiVS1X

markshust and others added 2 commits November 14, 2026 13:25
… and job docs

Module config now merges vendor, then modules/, then app/ modules
(load order within a tier), then the project-root config/. Previously it
followed plain dependency load order, so a vendor module loading after an
app module overrode the app module's config. ConfigModuleOrder applies the
ordering for both the live boot and the discovery cache.

Docs: document the four-step config order and drop the non-existent
app/config/ location; fix readonly Event/Job subclass examples that were a
fatal error; remove the string-based events claim from architecture.md.

Closes #691, #692, #693, #706

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017KaHtX9QzJB5ZedzkiVS1X
Add a "Which Config Location to Use" section to the configuration guide:
module config/ ships defaults with the code, the project-root config/
holds installation settings, with a table of where each kind of value
goes. Link it from config.md's Merge Priority and fix the vendor path
glob there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017KaHtX9QzJB5ZedzkiVS1X
@markshust markshust added breaking Introduces a breaking change bug Something isn't working documentation Improvements or additions to documentation labels Nov 14, 2026
@github-actions github-actions Bot added bug Something isn't working and removed bug Something isn't working documentation Improvements or additions to documentation labels Nov 14, 2026
@markshust
markshust merged commit 48ce73b into develop Nov 14, 2026
5 checks passed
@markshust
markshust deleted the feature/docs-fixes-691-693 branch November 14, 2026 18:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking Introduces a breaking change bug Something isn't working

Projects

None yet

1 participant