Module configuration merging in Zend Framework: ensuring consistent values during zero‑downtime deploys

Stabilizing Zend Framework Config Merging for Zero-Downtime Deploys

Zend Framework (now Laminas) merges module configurations using a deep recursive replace strategy. While string keys are overwritten by later-loaded modules, numeric keys are silently discarded. This behavior, combined with non-deterministic module loading order, creates instability during rolling deployments where different code branches may be active simultaneously.

Root Cause: Non-Deterministic Merge Order

The framework determines configuration precedence based solely on the order of modules listed in application.config.php. Without explicit ordering, any change in this list—such as during a deployment with mixed module versions—will produce different merged configurations. This can silently alter critical settings like database adapters, cache pools, or service configurations, leading to inconsistent behavior across application instances.

Solution: Explicit Ordering and Global Overrides

To ensure consistent configuration across all deployment nodes, implement the following:

1. Explicit Module Ordering: Ensure the modules array in application.config.php is strictly ordered and remains identical across all deployment artifacts. If modules are loaded dynamically, implement deterministic sorting based on version metadata.
2. Global Configuration Overrides: Place critical settings in config/autoload/*.php files, which are merged after all module configurations. This provides a final "source of truth" independent of module load order.
3. Immutable Build Artifacts: Generate the fully merged configuration during the build phase and cache it as a static PHP file. Loading this pre-computed configuration ensures identical values across all nodes in a rolling deployment.

Detecting Duplicate Configuration Keys

The framework provides no built-in mechanism to report duplicate keys. However, you can implement a pre-deployment validation script:

// Conceptual duplicate detection logic
$moduleManager = new ModuleManager($application);
$modules = $moduleManager->getModules();
$seenKeys = [];

foreach ($modules as $name => $module) {
    $config = $module->getConfig();
    foreach (array_keys($config) as $key) {
        if (isset($seenKeys[$key])) {
            throw new RuntimeException(
              "Duplicate config key '$key' found in $name and {$seenKeys[$key]}"
            );
        }
        $seenKeys[$key] = $name;
    }
}

Assumptions and Uncertainty

This analysis assumes standard ModuleManager behavior. If your project uses custom ConfigListener implementations, the merge precedence rules may differ. Additionally, numeric keys in module configurations are silently discarded during merging, which can cause unexpected data loss if your configuration relies on indexed arrays.

Verification Steps

Before deployment, verify the merged configuration by logging or printing the final configuration array. Confirm that expected keys contain the intended values and that the module order matches your deployment requirements.