Config Cache: Pre-compile Magento Configuration at Deploy Time¶
User Guide¶
CopeX GmbH
Web: https://copex.io
Email: office@copex.io
Inhaltsverzeichnis / Table of Contents¶
| Abschnitt / Section | Seite |
|---|---|
| 1 Was es macht / What it does | 3 |
| 2 Wann sinnvoll / When to use | 3 |
| 3 Voraussetzungen / Requirements | 4 |
| 4 Installation | 4 |
| 5 Aktivierung / Activation | 5 |
| 6 Verwendung / Usage | 5 |
| 7 Was tun bei Problemen / Troubleshooting | 7 |
1 What it does¶
Magento reads configuration values at runtime from a cache (Redis or file cache) — on every request, for every scope. This adds up noticeably on high-traffic pages.
Config Cache replaces this flow: at deploy time, all configuration values are read once from the database and stored as OPcache-optimized PHP files. On the next request, PHP delivers the values directly from memory — no cache lookup, no deserialization.
When an administrator saves a configuration change in the backend, the affected scope file is regenerated automatically — no deployment required.
2 When to use¶
- Shop is slow even though Redis is configured
- High Redis load from many configuration queries per page
- Deployment pipeline should complete all optimizations in one step
- Multiple store views with different configurations — each benefits separately
3 Requirements¶
- Magento 2.4.6 or higher
- PHP 8.1 or higher (compatible with 8.2, 8.3, 8.4, 8.5)
copex/module-performance-suite(installed automatically via Composer)copex/build-compiler(installed automatically via Composer)copex/module-core>1.1.0
4 Installation¶
composer require copex/module-build-config
bin/magento module:enable CopeX_BuildConfig
bin/magento setup:upgrade
Alternatively, install the complete suite:
composer require copex/performance-suite-bundle
5 Activation¶
The module is controlled via app/etc/env.php. Add the following block:
'copex' => [
'build' => [
'enabled' => true,
'config_enabled' => true,
],
],
| Flag | Default | Description |
|---|---|---|
copex/build/enabled |
false |
Master switch for all build-time compilation |
copex/build/config_enabled |
false |
Enables config compilation (requires master switch) |
copex/build/generated_path |
generated/copex/build-config/ |
Output directory for compiled files |
After setting the flags, run the build command (see section 6).
6 Usage¶
bin/magento copex:performance:build:config¶
Reads all configuration values for all scopes and writes one PHP file per scope:
bin/magento copex:performance:build:config
Recommended deployment sequence:
bin/magento setup:upgrade
bin/magento setup:static-content:deploy
bin/magento copex:performance:build:config
bin/magento cache:flush
Options for targeted rebuild:
| Option | Description |
|---|---|
--scope=default |
Recompile only the default scope |
--scope=website:1 |
Only website with ID 1 |
--scope=store:en |
Only store view with code en |
7 Troubleshooting¶
Kill switch — immediate disable:
'copex' => ['build' => ['enabled' => false]]
Set in env.php, flush cache. The module immediately falls back to native Magento ScopeConfig — no deployment, no server restart required.
Config values stale after admin save: check both flags are true, check write permissions on generated/copex/build-config/, then run bin/magento copex:performance:build:config.
Corrupted file: delete the affected file and recompile with --scope=store:en.
CopeX GmbH — Web: https://copex.io — Email: office@copex.io