Code-Generierung zur Buildzeit in PHP: Boilerplate erzeugen statt Reflection zur Laufzeit

1. Buildzeit-Codegenerierung versus Reflection zur Laufzeit

Code-Generierung zur Buildzeit bedeutet, fertigen PHP-Code zu erzeugen, bevor eine Anwendung überhaupt einen einzigen Request bearbeitet, statt Metadaten über Klassen bei jedem Aufruf erneut über die Reflection API auszulesen. Der Unterschied klingt zunächst technisch, hat aber erhebliche Auswirkungen auf die Performance: Reflection zur Laufzeit durchsucht bei jedem Request dieselben Metadaten-Strukturen, während zur Buildzeit generierter Code diese Arbeit genau einmal erledigt und das Ergebnis als direkt ausführbaren PHP-Code festschreibt.

Ein anschauliches Beispiel ist ein Dependency-Injection-Container. Ein Reflection-basierter Container liest bei jedem Neustart, manchmal sogar bei jedem Request, per Reflection aus, welche Konstruktor-Parameter eine Klasse erwartet, und löst diese Abhängigkeiten dynamisch auf. Ein zur Buildzeit generierter, kompilierter Container hingegen enthält bereits fertigen PHP-Code, der jede Abhängigkeit explizit per new instanziiert, ganz ohne einen einzigen Reflection-Aufruf zur Laufzeit.

Dieser Artikel zeigt, wie man einen eigenen, einfachen Codegenerator für PHP baut, wie man generierten Code sauber in eine Composer-basierte Build-Pipeline einhängt, und wie man Cache-Invalidierung so gestaltet, dass sich Änderungen am Quellcode zuverlässig im generierten Ergebnis widerspiegeln.

2. Wann sich Codegenerierung zur Buildzeit lohnt

Nicht jede Anwendung braucht Code-Generierung zur Buildzeit. Für kleine Projekte mit wenigen Klassen ist der Reflection-Overhead pro Request meist vernachlässigbar, und der zusätzliche Build-Schritt würde nur Komplexität ohne messbaren Nutzen hinzufügen. Interessant wird Buildzeit-Codegenerierung, sobald eine Anwendung hunderte oder tausende Klassen verwaltet, deren Metadaten bei jedem Request wiederholt ausgelesen werden, etwa in einem großen DI-Container, einem attributbasierten Router oder einem ORM mit vielen Entitäten.

Ein zweites Kriterium ist die Stabilität der Struktur zwischen Deployments. Codegenerierung zur Buildzeit lohnt sich besonders dann, wenn sich die relevante Struktur, etwa welche Klassen existieren und welche Attribute sie tragen, zwischen zwei Deployments nicht ändert. Ändert sich diese Struktur hingegen bei jedem Request, etwa weil Plugins zur Laufzeit nachgeladen werden, ist Reflection zur Laufzeit oft die praktikablere, wenn auch langsamere Wahl.

3. Ein einfacher Codegenerator: von Konfiguration zu Klasse

Der einfachste Einstieg in Codegenerierung zur Buildzeit ist ein Skript, das eine Konfiguration, etwa ein Array mit Service-Definitionen, in eine fertige PHP-Klasse übersetzt. Der Generator liest die Konfiguration einmalig ein, baut daraus einen String mit gültigem PHP-Code und schreibt diesen String in eine reguläre .php-Datei. Diese Datei wird danach wie jede andere Datei im Projekt von Composer autogeladen und von OPcache kompiliert.

Wichtig ist, den Generator selbst als eigenständiges, testbares PHP-Skript zu behandeln, nicht als Teil der eigentlichen Anwendungslogik. Der Generator läuft idealerweise nur während des Build- oder Deployment-Prozesses, niemals im Kontext eines echten HTTP-Requests, damit ein Fehler im Generator nicht die Produktionsanwendung beeinflusst, sondern schon vorher im CI auffällt.

<?php

declare(strict_types=1);

/**
 * Minimal build-time code generator: config array to a plain PHP class.
 */
final class ServiceMapGenerator
{
    /** @param array<string, class-string> $services */
    public function generate(array $services, string $outputFile): void
    {
        $entries = [];

        foreach ($services as $id => $className) {
            $entries[] = sprintf("        '%s' => %s::class,", $id, $className);
        }

        $code = sprintf(
            "<?php\n\ndeclare(strict_types=1);\n\n" .
            "// Auto-generated at build time, do not edit by hand\n" .
            "final class GeneratedServiceMap\n{\n" .
            "    public const MAP = [\n%s\n    ];\n}\n",
            implode("\n", $entries)
        );

        file_put_contents($outputFile, $code, LOCK_EX);
    }
}

$generator = new ServiceMapGenerator();
$generator->generate(
    ['payment_gateway' => StripePaymentGateway::class, 'mailer' => SmtpMailer::class],
    __DIR__ . '/generated/GeneratedServiceMap.php'
);

4. Templates statt String-Konkatenation

Reine String-Konkatenation wie im vorherigen Beispiel wird schnell unübersichtlich, sobald generierter Code komplexer wird, etwa mehrere Methoden oder verschachtelte Strukturen enthält. Robuster ist ein Template-Ansatz, bei dem eine PHP-Vorlage mit klar erkennbaren Platzhaltern existiert, und der Generator diese Platzhalter gezielt durch echten Code ersetzt. Das trennt die Struktur des generierten Codes optisch von der Generierungslogik und macht Templates auch für Entwickler lesbar, die den Generator selbst nicht im Detail kennen.

Eine bewährte Konvention ist, Platzhalter in einer Form zu wählen, die niemals in echtem PHP-Code vorkommt, etwa __PLACEHOLDER_NAME__. Das verhindert, dass ein Platzhalter versehentlich mit echtem generiertem Code kollidiert. Für komplexere Templates lohnt sich der Umstieg auf eine dedizierte Template-Engine, für die in diesem Artikel gezeigten, überschaubaren Anwendungsfälle reicht str_replace() vollkommen aus.

<?php

declare(strict_types=1);

final class TemplateBasedGenerator
{
    private const TEMPLATE = <<<'PHP'
<?php

declare(strict_types=1);

// Auto-generated at build time, do not edit by hand
final class __CLASS_NAME__
{
    public function __construct(
__CONSTRUCTOR_PARAMS__
    ) {
    }
}

PHP;

    /** @param array<string, class-string> $dependencies */
    public function generate(string $className, array $dependencies): string
    {
        $params = [];

        foreach ($dependencies as $name => $type) {
            $params[] = sprintf('        private readonly %s $%s,', $type, $name);
        }

        return str_replace(
            ['__CLASS_NAME__', '__CONSTRUCTOR_PARAMS__'],
            [$className, implode("\n", $params)],
            self::TEMPLATE
        );
    }
}

$generator = new TemplateBasedGenerator();
$code = $generator->generate('GeneratedOrderService', ['gateway' => 'PaymentGateway', 'mailer' => 'Mailer']);

5. Generierten Code in die Composer-Pipeline einhängen

Damit Code-Generierung zur Buildzeit nicht zur manuellen Zusatzaufgabe wird, gehört der Generierungsschritt in die reguläre Composer-Pipeline. Composer unterstützt dafür eigene Lifecycle-Hooks in der composer.json, etwa post-autoload-dump, der nach jedem composer install oder composer dump-autoload automatisch ein PHP-Skript ausführt. Dieses Skript ruft den eigenen Codegenerator auf und schreibt die generierten Dateien in ein Verzeichnis, das ebenfalls über die Composer-Autoload-Konfiguration eingebunden ist.

Diese Kopplung an den Composer-Lifecycle stellt sicher, dass generierter Code nie veraltet im Repository liegt, ohne dass ein Entwickler manuell an den Build-Schritt denken muss. Wichtig ist, das generierte Verzeichnis konsequent aus der Versionskontrolle auszuschließen, etwa über .gitignore, damit niemals versehentlich veralteter, generierter Code eingecheckt wird, der beim nächsten Build ohnehin überschrieben würde.

<?php

declare(strict_types=1);

/**
 * Composer script handler, referenced from composer.json as:
 * "scripts": { "post-autoload-dump": ["Mironsoft\\Build\\Generator::run"] }
 */
final class Generator
{
    public static function run(): void
    {
        $config = require __DIR__ . '/../config/services.php';

        $generator = new ServiceMapGenerator();
        $generator->generate($config, __DIR__ . '/../generated/GeneratedServiceMap.php');

        echo '[build] Generated service map with ' . count($config) . ' entries' . PHP_EOL;
    }
}

6. Praxisbeispiel: ein kompilierter DI-Container

Das prominenteste Anwendungsbeispiel für Codegenerierung zur Buildzeit in PHP ist der kompilierte Dependency-Injection-Container, wie ihn Symfony seit Jahren produktiv einsetzt. Statt bei jedem Request per Reflection herauszufinden, welche Abhängigkeiten ein Service benötigt, generiert Symfony beim Container-Build eine einzige PHP-Klasse, die für jeden registrierten Service eine eigene, direkte Factory-Methode enthält. Diese Methode instanziiert die Abhängigkeit mit einem einfachen new-Aufruf, komplett ohne Reflection zur Laufzeit.

Das Ergebnis ist ein Container, dessen Auflösungslogik für OPcache genauso aussieht wie handgeschriebener Code, weil es tatsächlich generierter, aber vollkommen regulärer PHP-Code ist. Der Geschwindigkeitsgewinn gegenüber einem rein Reflection-basierten Container ist in Benchmarks von Symfony deutlich messbar, gerade bei Anwendungen mit hunderten registrierten Services, die bei jedem Request instanziiert werden müssen.

7. Generierten Code validieren und in CI prüfen

Generierter Code ist nur so vertrauenswürdig wie der Generator, der ihn erzeugt hat, und Fehler im Generator selbst können zu syntaktisch ungültigem oder logisch fehlerhaftem PHP-Code führen. Deshalb gehört eine Syntaxprüfung des generierten Codes, etwa mit php -l, in jede CI-Pipeline, die den Generator ausführt. Ein fehlgeschlagener Syntax-Check sollte den Build sofort abbrechen, bevor fehlerhafter generierter Code überhaupt in ein Deployment gelangt.

Über die reine Syntaxprüfung hinaus lohnt sich, den generierten Code testweise durch PHPStan laufen zu lassen. Da generierter Code oft repetitive, vorhersehbare Strukturen hat, findet PHPStan hier häufig echte Fehler im Generator selbst, etwa falsch zusammengesetzte Typdeklarationen, bevor diese in einer Produktionsumgebung zu Laufzeitfehlern führen.

8. Cache-Invalidierung bei Quelländerungen

Ein zentrales Risiko bei Code-Generierung zur Buildzeit ist veralteter generierter Code, der nicht mehr zur aktuellen Konfiguration oder zum aktuellen Quellcode passt. Die zuverlässigste Gegenmaßnahme ist ein Hash über die relevanten Quelldateien, etwa die Service-Konfiguration, der bei jedem Generierungslauf berechnet und neben dem generierten Code in einer Manifest-Datei gespeichert wird. Vor der Nutzung des generierten Codes vergleicht die Anwendung den aktuellen Hash mit dem gespeicherten Hash und generiert bei Abweichung neu, oder bricht in Produktion mit einer klaren Fehlermeldung ab.

In Produktionsumgebungen ist ein automatisches Neugenerieren zur Laufzeit meist unerwünscht, weil es genau den Performance-Vorteil zunichtemacht, den Buildzeit-Codegenerierung eigentlich bringen soll. Dort sollte eine Hash-Abweichung stattdessen einen sichtbaren Fehler auslösen, der auf einen fehlerhaften Deployment-Prozess hinweist, statt stillschweigend veralteten Code weiterzuverwenden.

9. Buildzeit- versus Laufzeit-Generierung im Vergleich

Beide Techniken haben ihre Berechtigung, je nach Projektgröße und Deployment-Prozess. Die folgende Tabelle stellt die wichtigsten Unterschiede gegenüber.

Die Tabelle zeigt: Buildzeit-Codegenerierung gewinnt bei Performance und Debugging-Klarheit in Produktion, kostet aber zusätzliche Build-Komplexität. Für kleine Anwendungen mit wenigen Services überwiegt oft die Einfachheit von Reflection zur Laufzeit, für große, produktionskritische Systeme mit vielen Services überwiegt fast immer der Performance-Vorteil der Buildzeit-Variante.

10. Zusammenfassung

Code-Generierung zur Buildzeit ersetzt wiederholte Reflection-Aufrufe zur Laufzeit durch einmalig erzeugten, direkt ausführbaren PHP-Code. Ein einfacher Generator liest Konfiguration ein und schreibt daraus reguläre Klassen, idealerweise über Templates mit klaren Platzhaltern statt fragiler String-Konkatenation. Composer-Lifecycle-Hooks wie post-autoload-dump integrieren den Generierungsschritt sauber in die bestehende Build-Pipeline, ohne manuellen Zusatzaufwand für Entwickler.

Der kompilierte DI-Container ist das prominenteste Praxisbeispiel: statt Abhängigkeiten bei jedem Request per Reflection aufzulösen, generiert die Buildzeit-Variante direkten Factory-Code. Syntaxprüfung und PHPStan in der CI-Pipeline fangen Fehler im Generator ab, bevor sie Produktion erreichen, und ein Hash über die Quellkonfiguration verhindert, dass veralteter generierter Code unbemerkt weiterverwendet wird.

11. FAQ: Code-Generierung zur Buildzeit in PHP