Build Compiler: Foundation Library of the CopeX Performance Suite¶

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¶

Build Compiler is a PHP library that converts PHP arrays and XML structures into OPcache-optimized PHP include files. It forms the technical foundation of the CopeX Performance Suite.

The generated files are not serialized or cached — PHP loads them directly from OPcache as pre-compiled code. That means no deserialization, no cache lookups, and no runtime inheritance logic.

The library works standalone in deploy scripts and CI pipelines — a full Magento installation is not required.

2 When to use¶

The library is not a standalone product that you activate directly. It is used automatically by copex/module-build-config.

Direct use makes sense when:

Deploy scripts need to pre-process configuration data without a Magento bootstrap
CI pipelines need to produce deterministic build artifacts from PHP arrays or XML
Custom CopeX-compatible builders are being developed

3 Requirements¶

PHP 8.1 or higher (compatible with 8.2, 8.3, 8.4, 8.5)
Composer for installation
No Magento installation required — the library works standalone

4 Installation¶

Add the CopeX package repository to your composer.json if not already present:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://packages.copex.io"
        }
    ]
}

Install the library:

composer require copex/build-compiler

In Magento projects set up via the CopeX repository, the repository is already configured.

5 Activation¶

Build Compiler is a library with no Magento module registration. There are no env.php flags and no master switch. The library is active as soon as it is installed via Composer.

6 Usage¶

The library is typically used via copex/module-build-config and does not need to be called directly.

For direct use in deploy scripts, three classes are available:

ArrayCompiler — converts a PHP array into an OPcache-friendly PHP file:

# Result: a .php file that returns the original array when required

XmlCompiler — processes an XML string or SimpleXMLElement, same output format as ArrayCompiler.

MagentoConfigAdapter — applies Magento's scope inheritance rules (default → website → store) and writes one file per scope to the output directory.

See section 8 for API details.

7 Troubleshooting¶

Since Build Compiler is a library, there is no runtime kill switch. When issues occur:

Verify the output directory is writable by the web server user
After a composer update, check whether generated files are still valid — if in doubt, regenerate them
If generated files are corrupted (e.g. due to a full disk): delete the files and re-run the build command

The parent module copex/module-build-config has its own kill switch — when troubleshooting, start there rather than in this library.

8 For Developers¶

Three classes are available for direct use:

Class	Method	Purpose
`ArrayCompiler`	`compile(array $data, string $outputPath): void`	Array → PHP include file
`XmlCompiler`	`compile(string\\|\SimpleXMLElement $input, string $outputPath): void`	XML → PHP include file
`MagentoConfigAdapter`	`compileScopes(array $rawConfig, string $outputDir): void`	Scope-resolved array → one file per scope

MagentoConfigAdapter is used internally by copex/module-build-config. For custom deploy scripts that need resolved configuration without a Magento bootstrap, it can be used directly — see the source for details.

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