Performance Suite: Faster Magento Storefront¶

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
8 Für Entwickler / For Developers	8

1 What it does¶

Performance Suite is the foundation of CopeX performance optimization for Magento. It provides the shared infrastructure that all other CopeX performance modules build on: preloader management, build-time optimizations, diagnostic tools, and a three-level kill-switch system.

The module itself speeds up the shop through a request-scoped product cache: products that have been loaded once are not read from the database a second time within the same request.

Additionally, the module provides CLI commands for benchmarks, audits, and build-time optimizations — all under copex:performance:.

2 When to use¶

Shop is slow under load, cause unclear
Diagnostic tools are missing
Other CopeX performance modules are planned — Performance Suite is a prerequisite

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-core >1.1.0

4 Installation¶

composer require copex/module-performance-suite
bin/magento module:enable CopeX_PerformanceSuite
bin/magento setup:upgrade

Or install the complete suite at once:

composer require copex/performance-suite-bundle

5 Activation¶

'copex' => [
    'performance' => [
        'enabled' => true,
    ],
],

Flag	Default	Description
`performance/enabled`	`false`	Global master switch
`performance/disabled_domains`	`[]`	Hostnames where the suite is disabled
`performance/preloaders_enabled`	`true`	Disable preloading without affecting builders
`performance/min_batch_size`	`2`	Minimum product count to trigger preloading
`performance/chunk_size`	`500`	Max product IDs per preloader query

6 Usage¶

All CLI commands are registered under copex:performance:.

Command	What it does
`copex:performance:build`	Runs all registered builders (config, layout, ...)
`copex:performance:build:config`	Pre-compiles configuration into PHP files
`copex:performance:benchmark --url=/path`	Measures request speed with and without preloaders
`copex:performance:audit:layout-cache`	Reports layout cache hit rates and stale handles
`copex:performance:audit:redis`	Inspects Redis configuration and memory usage
`copex:performance:audit:modules`	Detects disabled or conflicting modules
`copex:performance:audit:indexers`	Reports indexer status and recommends configuration
`copex:performance:recommendations`	Summarizes all audit findings as a prioritized action list
`copex:performance:opcache:prime`	Warms OPcache after deployment

OPcache preload (optional): set opcache.preload in php.ini to vendor/copex/module-performance-suite/etc/preload.php, restart PHP-FPM after each deployment.

7 Troubleshooting¶

Kill switch — disable everything immediately:

'copex' => ['performance' => ['enabled' => false]]

Takes effect on the next request. No cache flush, no server restart.

Disable for specific domains only (e.g. staging):

'copex' => ['performance' => ['disabled_domains' => ['staging.example.com']]]

Automatic self-protection: If an error occurs inside a preloader, it is disabled for the rest of the request. The error is logged to var/log/copex-performance.log — the user sees no error.

Diagnostics: copex:performance:recommendations → prioritized issues; copex:performance:benchmark → measure improvement; var/log/copex-performance.log → disabled preloaders.

8 For Developers¶

ProductPreloadHelperInterface allows custom blocks to explicitly trigger preloading for known product IDs without waiting for collection events. Suitable for custom blocks that load products directly.

The RequestRegistry stores the page context (list, cart, wishlist, pdp) and preloaded data per request. With persistent PHP workers (FrankenPHP, RoadRunner), the registry is automatically reset between requests.

CopeX GmbH — Web: https://copex.io — Email: office@copex.io