Magento 2 Configuration Pitfall: When env.php Module Overrides Revert to config.php
Understanding a Critical Magento 2 Configuration Bug: env.php Overrides and config.php Rewrites
As e-commerce migration experts at Shopping Mover, we often encounter intricate Magento 2 configuration challenges. A recent GitHub issue (#41280) sheds light on a significant bug affecting how Magento 2 handles module states defined in app/etc/env.php, particularly when interacting with app/etc/config.php.
The Core Problem: Environment-Specific Overrides Becoming Permanent
The issue, reported by SamJUK, details a scenario where module states explicitly disabled or enabled in the environment-specific app/etc/env.php file are inadvertently written back into the version-controlled app/etc/config.php. This happens after executing common Magento CLI commands such as bin/magento setup:upgrade, bin/magento module:enable, or bin/magento module:disable.
For instance, if you disable Magento_Csp in your env.php using 'modules' => ['Magento_Csp' => 0], running setup:upgrade would incorrectly update config.php to reflect this change. This behavior undermines the intended separation of environment-specific configurations from the core application configuration, leading to unwanted commits of environment-dependent changes to your version control system.
Root Cause and Broader Impact
The issue's author meticulously identified the root cause: the Installer::createModulesConfig() method calls Reader::load() without a specific file key. This action merges the contents of both config.php and env.php, and then writes this combined result back into config.php. This effectively promotes an environment-specific override into a global, committed change.
The implications extend beyond just setup:upgrade. Any command that rewrites the module list, like enabling or disabling unrelated modules, will also pull in and commit these env.php overrides to config.php. Furthermore, this bug causes bin/magento setup:module:config:status to perpetually report an 'outdated' configuration, as it compares the original config.php against the merged configuration, which always includes the env.php overrides.
Common Scenarios and Workarounds
This bug is particularly problematic for developers and merchants who rely on env.php to manage environment-specific module states, especially for integration modules like ERP or CRM systems that might only be active in certain environments. The current workaround involves manually restoring app/etc/config.php after every execution of setup:upgrade, module:enable, or module:disable – a cumbersome and error-prone process.
Community Insight and Resolution
While the GitHub comments are minimal, primarily consisting of bot responses for issue processing, the issue itself is marked with 'Progress: done' and 'Issue: ready for confirmation'. A release note is also provided, stating: "Fixed an issue where module state set in app/etc/env.php was written back into app/etc/config.php." This indicates that a fix has been implemented or is in the final stages of review, which is excellent news for the Magento community.
This detailed bug report and its subsequent resolution highlight the importance of understanding Magento's configuration hierarchy, especially when managing complex multi-environment deployments or migrating existing stores. Keeping env.php and config.php distinct is crucial for maintaining a clean and manageable codebase.