symfony CLI 5.3 App in ein PHAR packen

Für dieses Tutorial benutzen wir eine neue Konsolen-Applikation namens my-cli, ganz frisch erzeugt. Wir benutzen dazu symfony 5.3, die aktuelle Version als dieses Tutorial geschrieben wurde:

composer create-project symfony/skeleton my-cli "5.3.*"
cd my-cli
bin/console -V

Voila, eine neue CLI! Nichts besonderes bisher. Bitte versuche nicht, deine vorhandene CLI in ein PHAR zu packen, bevor du nicht zumindest einmal erfolgreich eine neue, unveränderte CLI in ein PHAR gepackt hast. Sei gewarnt: andere symfony-Versionen haben andere Hürden, die man überwinden muss. Und die Probleme, die du beim Schreiben deiner vorhandenen CLI selbst geschaffen hast, kommen da noch oben drauf!

Wir müssen ein paar Änderungen an der CLI App vornehmen, bevor wir daraus ein PHAR erstellen können. Und damit wir das PHAR nicht von Hand machen müssen, benutzen wir ein paar Tools dafür.

Wenn man mit composer require –dev einen PHAR-Builder hinzufügt, kommt man in eine Zwickmühle. Entweder man hat alle Entwicklungsabhängigkeiten mit im PHAR, oder man hat nach einem composer install –no-dev den PHAR-Builder nicht zur Verfügung. Packt man den Builder in die –no-dev-Abhängigkeiten, landet der Builder mit im PHAR. Wir müssen also die Entwicklungstools so von den Laufzeitabhängigkeiten trennen, dass composer zwar alles verwalten kann, aber am Ende nicht alles vermischt ist. Glücklicherweise müssen wir uns das nicht selbst ausdenken: bamarni/composer-bin-plugin kann genau das. Der Hauptzweck dieses Plugins ist es, die Laufzeit-Abhängigkeiten des Projektes von denen der Entwicklungstools zu trennen (was grundsätzlich eine gute Sache ist). Und zu diesem Zweck speichert das Plugin nicht nur die Dateien in einem anderen Verzeichnis, sondern hält auch die Entwicklungstools aus dem Autoloader des Projektes heraus. Perfekt!

composer require --dev bamarni/composer-bin-plugin

OK, fast perfekt. Das Plugin selbst wird Teil des PHARs sein. Da es aber selbst sehr klein ist, im Verhältnis zu PHAR-Builder und anderen Entwicklertools, kann man damit gut leben. Nun können wir den Entwickler-Kram ausserhalb der Projekt-/composer.json einbinden und die Dateien landen in einem Extra-Verzeichnis /vendor-bin/. Das Konzept des Plugins erlaubt es, für verschiedene Tools verschiedene benannte „Umgebungen” zu erstellen. Bevor wir das tun, erleichtern wir uns die künftige Handhabung mit ein paar Automatismen für Installation und Update. Das Verlinken der Tools nach /vendor/bin stellen wir dabei auch ab, da es sehr oft Konflikte erzeugt. Ersetze die Sektion „scripts” in der generierten /composer.json durch die folgende und füge den Eintrag zu „extra” hinzu:

    "scripts": {
        "auto-scripts": [
        ],
        "post-install-cmd": [
            "@cache:drop",
            "@composer bin all install --ansi"
        ],
        "post-update-cmd": [
            "@cache:drop",
            "@composer bin all update --ansi"
        ],
        "cache:drop": [
            "[ ! -d var ] || rm -rf var"
        ]
    },
    "extra": {
        "bamarni-bin": {
            "bin-links": false
        }
    },

Es ist Absicht, dass die „auto-scripts” leer sind. Ohne den Eintrag läuft symfony/flex nicht mehr und verhindert die composer-Benutzung. Mit den dort möglichen Kommando-Referenzen kann dann aber wiederum der PHAR-Builder nicht erfolgreich ausgeführt werden. So wie oben geht nun alles wie benötigt.

box ist einer der am Meisten verwendeten PHAR-Builder. Das Tool hat zahlreiche Optionen zum Optimieren des PHAR und des Erstellungsprozesses. Die ausführliche Anleitung hilft dir beim Einsatz für deine bestehende CLI. Das Tool in die isolierte composer-Umgebung „box” installieren:

composer bin box config minimum-stability dev
composer bin box require --dev humbug/box '^3.13.0'

Das neu erzeugte /vendor-bin/-Verzeichnis enthält ein paar Dateien, die man aufheben sollte, und die nicht zum Aufheben gedachten Abhängigkeiten der Tools. Ergänze die /.gitignore im Projekt-Root, um die Abhängigkeiten nicht in git zu versionieren, die nötigen /vendor-bin/**/composer.* aber schon. Und für das Arbeitsverzeichnis des PHAR-Builders fügen wir auch gleich einen Eintrag hinzu:

...

###> Isolated dev tools ###
/vendor-bin/**/vendor
###< Isolated dev tools ###
###> Box PHAR generator ###
/.box_dump/
###< Box PHAR generator ###

Erstelle nun noch eine /box.json in deinem Projekt-Root, um dem PHAR-Builder eine zur symfony CLI passende Grundkonfiguration zu geben:

{
    "directories": [
        "config",
        "src",
        "var/cache/prod"
    ],
    "files": [
        ".env.local.php"
    ],
    "finder": [
        {
            "name": "*.php",
            "exclude": ["Tests"],
            "in": "vendor"
        }
    ],
    "git-version": "application_version",
    "main": "bin/console",
    "output": "build/console",
    "dump-autoload": false
}

Damit eine symfony CLI aus einem PHAR laufen kann, muss man ein paar Änderungen vornehmen. box gibt dazu ein paar Hinweise, aber wie zuvor gesagt: Mit jeder Version von symfony ändern sich die nötigen Anpassungen. Für die neue CLI steht alles hier im Tutorial. Vor allem darf man für symfony 5.3 nicht die /composer.json anpassen, wie box das angibt. composer dump-autoload geht nicht. Stattdessen wärmen wir den Cache für die prod-Umgebung vor und kopieren den Cache mit in das PHAR (die nötigen Schritte folgen später). Und nochmal zur Erinnerung: es gibt unendliche Möglichkeiten, warum deine bereits vorhandene CLI sich nicht ungeändert in ein PHAR packen lässt… In src/Kernel.php schalten wir die automatische Ermittlung des Projekt-Root-Verzeichnisses aus. Die Erkennung kommt nicht damit zurecht, dass die Dateien nun in einem phar://-Stream liegen. Zum Glück können wir die Erkennung einfach ersetzen, in dem wir die geerbte Methode getProjectDir() überschreiben:

...
class Kernel extends BaseKernel
{
    use MicroKernelTrait;

    // In PHAR, Kernel cannot auto-detect this path
    public function getProjectDir(): string
    {
        return \dirname(__DIR__);
    }

    protected function configureContainer(ContainerConfigurator $container): void
...

Die mit symfony 5.3 neu eingeführte runtime-Komponente macht ebenfalls Probleme. Hier versucht symfony, mit $_SERVER[‚SCRIPT_FILENAME‘] zu arbeiten. Diese Variable enthält das aufgerufene Skript, also die PHAR-Datei selbst. symfony benötigt dort aber den Pfad der aufgerufenen PHP-Datei, um diese zu includieren. Das reparieren wir in bin/console:

....

// In PHAR, $_SERVER['SCRIPT_FILENAME'] is the PHAR itself. symfony runtime
// needs it to point to current file to include it:
$_SERVER['SCRIPT_FILENAME'] = __FILE__;
require_once dirname(__DIR__).'/vendor/autoload_runtime.php';

return function (array $context) {
...

Überprüfe nun, ob my-cli nach den Änderungen noch funktioniert:

bin/console -V

box benötigt ein git tag oder einen Commit, da damit immer eine Ersetzung der aktuellen Version im PHAR versucht wird. Wir müssen also einen Commit machen, bevor wir das PHAR erstellen können:

git init --initial-branch=main
git add .
git commit -m "Base commit"

Im PHAR muss symfony im prod-Modus laufen. Und es kann den nötigen Cache für die Dependency-Injection nicht im PHAR selbst erzeugen. Wir müssen das also vorab machen, damit wir alles mit ins PHAR reinpacken können:

composer dump-env prod
bin/console cache:clear

Damit haben wir nun das prod-Environment vorkompiliert in die Datei /env.local.php und den Cache vorgewärmt in /var/cache/prod. Beide Pfade sind in der /box.json zum Einfügen ins PHAR konfiguriert. OK, erstellen wir das PHAR und stellen symfony zurück in den dev-Modus:

vendor-bin/box/vendor/bin/box compile
rm .env.local.php
build/console -V

Hurra! Die CLI wurde zum ersten Mal aus dem PHAR ausgeführt! Damit du die Build-Befehle nicht ständig wiederholen musst, füge sie als Skript build:phar in die /composer.json ein:

 "scripts": {
        "build:phar": [
            "@composer dump-env prod",
            "bin/console cache:clear",
            "vendor-bin/box/vendor/bin/box compile",
            "rm .env.local.php"
        ]
    }

Ab jetzt kannst die eine neue PHAR-Version mit nur einem Kommando erstellen:

composer build:phar
build/console -V

Und wo wir gerade von „Version“ reden, als Vorbereitung für den nächsten Teil:

git add .
git commit -m "PHARize CLI app"
git tag 0.0.1 -m '0.0.1'