ConfigListener reports configuration load failure after deployment – Zend Framework 2 ModuleManager

Question

Diagnosing a stale configuration cache in Zend Framework 2 deployments
Goal: Determine whether a failed deployment is caused by an outdated configuration cache after a code update, using only application logs.
Constraints: The Zend Framework 2 ModuleManager’s ConfigListener logs warnings about missing or unparsable configuration files, but it does not explicitly state whether the cache is stale or if an opcode cache is serving stale bytecode. Additionally, clearing the configuration cache on a production system may temporarily increase load, and the interaction with OPcache must be considered.
Uncertainty: It is unclear which log patterns definitively indicate a stale Zend configuration cache versus other configuration errors, and whether verifying timestamp mismatches alone is sufficient to confirm the root cause.
Specific questions:

What exact log messages from Zend\ModuleManager\Listener\ConfigListener signal a stale configuration cache after deployment?
How can one verify that clearing the Zend configuration cache resolves the deployment failure without needing to restart the opcode cache?
Is comparing the modification timestamps of cached configuration files with their source module/config files a reliable method to confirm cache staleness in a production environment?

Tasadduq Burney · Answer

Exact log messages indicating a stale configuration cache
According to the Zend Framework 2 ModuleManager ConfigListener, the following warnings appear in the application log when the cached configuration is missing, unreadable, or outdated after a deployment:

Unable to load configuration file "module/config/module.config.php"; skipping
Configuration file "module/config/module.config.php" is not a valid PHP array; falling back to source
Configuration file "module/config/module.config.php" was not found in cache; reloading from source

These messages are logged at the WARNING level and are emitted directly by Zend\ModuleManager\Listener\ConfigListener.

Likely explanation vs confirmed facts
Confirmed facts: The warnings above are produced when ConfigListener cannot read a valid cached configuration file and falls back to loading the source file directly. If the source file has been changed after the cache was written, the cache will be stale and the listener will log one of the messages while reloading from source.
Likely explanation: A deployment that updates module configuration files without clearing the data/cache directory leaves an outdated module.config.php cache. Subsequent requests trigger ConfigListener to detect the mismatch and log the warnings, which may manifest as missing configuration or runtime errors.

Steps to verify and resolve without restarting OPcache

Locate the application log (e.g., data/logs/php.log or wherever your logger writes) and search for the exact warning strings listed above that appear after the deployment timestamp.
If the warnings are present, clear the Zend configuration cache by removing the cached file:
rm -f data/cache/module.config.php

Alternatively, invoke the ModuleManager method from a script or console:
php -r "require 'init_autoloader.php'; $app = require 'config/application.config.php'; $listener = new Zend\ModuleManager\Listener\ConfigListener(); $listener->clearConfigCache();"

(Adjust the bootstrap path to match your application.)
After deletion, make a request to the affected page and check the log again. The warning should no longer appear and the page should load correctly.
To further confirm staleness, compare the modification timestamps of the source config file and the (now removed) cached copy. A stale cache will have an older mtime than the source:
stat -c %Y module/config/module.config.php   # source
stat -c %Y data/cache/module.config.php       # cache (if still present)

If the cache file’s timestamp is older, the cache was stale.

Missing diagnostic detail
If the log messages you observe do not match any of the three patterns above, please provide the exact warning text from your logs (including the module name and any surrounding context). This will allow confirmation that the issue is indeed related to ConfigListener’s cache handling for your specific ZF2 version.

ConfigListener reports configuration load failure after deployment – Zend Framework 2 ModuleManager

Diagnosing a stale configuration cache in Zend Framework 2 deployments

1 answer

Exact log messages indicating a stale configuration cache

Likely explanation vs confirmed facts

Steps to verify and resolve without restarting OPcache

Missing diagnostic detail

Your perspective belongs here.

0 question comments