Build Compiler: Hilfsbibliothek der 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 Was es macht¶

Build Compiler ist eine PHP-Bibliothek, die PHP-Arrays und XML-Strukturen in OPcache-optimierte PHP-Include-Dateien umwandelt. Sie bildet die technische Grundlage der CopeX Performance Suite.

Die generierten Dateien werden nicht serialisiert oder gecacht — PHP lädt sie direkt aus dem OPcache als vorkompilierten Code. Das bedeutet: keine Deserialisierung, keine Cache-Lookups, keine Laufzeit-Vererbungslogik.

Die Bibliothek funktioniert eigenständig in Deploy-Skripten und CI-Pipelines — eine vollständige Magento-Installation ist nicht erforderlich.

2 Wann sinnvoll¶

Die Bibliothek selbst ist kein eigenständiges Produkt, das direkt aktiviert wird. Sie wird automatisch von copex/module-build-config genutzt.

Eigene Nutzung sinnvoll wenn:

Deploy-Skripte Konfigurationsdaten ohne Magento-Bootstrap vorverarbeiten sollen
CI-Pipelines deterministische Build-Artefakte aus PHP-Arrays oder XML erzeugen müssen
Eigene CopeX-kompatible Builder entwickelt werden

3 Voraussetzungen¶

PHP 8.1 oder höher (kompatibel mit 8.2, 8.3, 8.4, 8.5)
Composer für die Installation
Keine Magento-Installation erforderlich — die Bibliothek funktioniert eigenständig

4 Installation¶

CopeX-Paket-Repository zur composer.json hinzufügen, falls noch nicht vorhanden:

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

Bibliothek installieren:

composer require copex/build-compiler

In Magento-Projekten, die über das CopeX-Repository eingerichtet wurden, ist das Repository bereits konfiguriert.

5 Aktivierung¶

Build Compiler ist eine Bibliothek ohne Magento-Modul-Registrierung. Es gibt keine env.php-Flags und keinen Hauptschalter. Die Bibliothek ist aktiv, sobald sie per Composer installiert ist.

6 Verwendung¶

Die Bibliothek wird in der Regel über copex/module-build-config genutzt und muss nicht direkt aufgerufen werden.

Für direkte Nutzung in Deploy-Skripten stehen drei Klassen bereit:

ArrayCompiler — wandelt ein PHP-Array in eine OPcache-freundliche PHP-Datei um:

# Ergebnis: eine .php-Datei, die bei require das ursprüngliche Array zurückgibt

XmlCompiler — verarbeitet XML-String oder SimpleXMLElement, intern dasselbe Ausgabeformat wie ArrayCompiler.

MagentoConfigAdapter — wendet Magentos Scope-Vererbungsregeln an (default → website → store) und schreibt eine Datei pro Scope ins Ausgabeverzeichnis.

Details zur API-Nutzung siehe Abschnitt 8.

7 Was tun bei Problemen¶

Da Build Compiler eine Bibliothek ist, gibt es keinen Laufzeit-Kill-Switch. Bei Problemen:

Sicherstellen, dass das Ausgabeverzeichnis für den Webserver-Benutzer beschreibbar ist
Nach einem composer update prüfen, ob generierte Dateien noch gültig sind — im Zweifel neu generieren
Bei korrumpierten generierten Dateien (z.B. durch volles Dateisystem): Dateien löschen und Build-Befehl erneut ausführen

Das übergeordnete Modul copex/module-build-config hat einen eigenen Kill-Switch — bei Problemen dort ansetzen, nicht in dieser Bibliothek.

8 Für Entwickler¶

Drei Klassen stehen zur direkten Nutzung bereit:

Klasse	Methode	Zweck
`ArrayCompiler`	`compile(array $data, string $outputPath): void`	Array → PHP-Include-Datei
`XmlCompiler`	`compile(string\\|\SimpleXMLElement $input, string $outputPath): void`	XML → PHP-Include-Datei
`MagentoConfigAdapter`	`compileScopes(array $rawConfig, string $outputDir): void`	Scope-aufgelöstes Array → eine Datei pro Scope

MagentoConfigAdapter wird intern von copex/module-build-config genutzt. Für eigene Deploy-Skripte, die eine aufgelöste Konfiguration ohne Magento-Bootstrap benötigen, kann er direkt verwendet werden — Details dazu im Quellcode.

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