mitmario.dev

composer.json

PHP Sandbox 4 Min Lesezeit 3 BeispieleLektion 2 von 7

Ein fremdes PHP-Projekt, und die ersten Fragen sind immer dieselben. Welche PHP-Version braucht es, welche Pakete, und wo liegt der eigene Code? Ohne eine feste Stelle dafür müsstest du Datei für Datei nach require-Zeilen suchen. Composer hat diese Stelle, die composer.json ganz oben im Projektordner.

Anlegen kannst du sie mit composer init, das der Reihe nach fragt, oder mit einem Texteditor, denn am Ende ist es JSON. In diesem Kurs nimmst du den Editor. Ein laufendes Programm bekommt im Terminal hier keine Tastatureingabe (help sagt es). composer init fragt dann gar nichts und überschreibt einfach die vorhandene Datei mit einer fast leeren, und deine Fassung kommt erst wieder zurück, wenn du sie im Editor änderst.

Sie ist eine ganz gewöhnliche Datei

Die Projektdatei, von PHP gelesen
<?php

declare(strict_types=1);

// Die composer.json ist ganz gewoehnliches JSON. Gelesen wird sie mit
// den Mitteln aus Lektion 8.3.

$projekt = json_decode(file_get_contents("composer.json"), true);

echo "Projekt: ", $projekt["name"], "\n";
echo "Zweck:   ", $projekt["description"], "\n";

echo "\nBraucht im Betrieb:\n";
foreach ($projekt["require"] as $paket => $bereich) {
    echo "  ", $paket, " ", $bereich, "\n";
}

echo "\nBraucht nur zum Entwickeln:\n";
foreach ($projekt["require-dev"] as $paket => $bereich) {
    echo "  ", $paket, " ", $bereich, "\n";
}

Im Beispiel wird die composer.json mit file_get_contents und json_decode gelesen, wie jede andere JSON-Datei in Abschnitt 8. Composer liest dieselbe Datei, nur gründlicher.

In einem PHP-Array darf hinter dem letzten Eintrag ein Komma stehen, in JSON nicht. Mit einem Komma hinter "^11" brechen composer validate und composer install im Terminal sofort ab. In der Meldung stehen untereinander "./composer.json" does not contain valid JSON, Parse error on line 9 und It appears you have an extra trailing comma. Composer hat also in Zeile 9 ein Komma zu viel gefunden und arbeitet mit der Datei erst wieder, wenn es weg ist.

Zwei Felder stehen im Beispiel nebeneinander:

  • require sind die Pakete, die dein Programm im Betrieb braucht. Ohne sie läuft es nicht.
  • require-dev sind die, die nur du beim Entwickeln brauchst. Ein Testwerkzeug gehört hierhin, ein Werkzeug zum Aufräumen von Code auch. Auf dem Server lässt man sie mit composer install --no-dev weg, und dann liegt auf der Maschine im Netz weniger fremder Code.

phpunit/phpunit steht deshalb unter require-dev. Dieses Paket kommt in Abschnitt 17 wieder.

Das Zeichen vor der Versionsnummer

Was die Zeichen vor der Version bedeuten
<?php

declare(strict_types=1);

// Composer entscheidet mit denselben Vergleichen, die PHP eingebaut
// hat. version_compare kennt die Zaehlweise von Versionsnummern.

$kandidaten = ["1.4.1", "1.4.2", "1.4.9", "1.5.0", "1.9.3", "2.0.0"];

printf("%-8s %-8s %-8s %s\n", "Version", "^1.4.2", "~1.4.2", "1.4.*");

foreach ($kandidaten as $version) {
    $caret = version_compare($version, "1.4.2", ">=")
        && version_compare($version, "2.0.0", "<");

    $tilde = version_compare($version, "1.4.2", ">=")
        && version_compare($version, "1.5.0", "<");

    $stern = version_compare($version, "1.4.0", ">=")
        && version_compare($version, "1.5.0", "<");

    printf(
        "%-8s %-8s %-8s %s\n",
        $version,
        $caret ? "ja" : "nein",
        $tilde ? "ja" : "nein",
        $stern ? "ja" : "nein"
    );
}

"^4" heißt nicht „genau Version 4“. Es ist ein Bereich, und welcher, das regelt die semantische Versionierung (englisch semantic versioning). Das ist eine Absprache unter Paketautoren. Eine Version besteht aus drei Zahlen, HAUPT.NEBEN.FEHLER (englisch major, minor, patch).

  • Die Fehlernummer steigt bei einer reinen Fehlerbehebung.
  • Die Nebennummer steigt, wenn etwas dazukommt, das Bestehende aber weiter funktioniert.
  • Die Hauptnummer steigt, wenn etwas kaputtgeht, das vorher funktioniert hat.

Mit dem Zeichen davor sagst du Composer, wie mutig es beim Aktualisieren sein darf. Im Beispiel rechnet version_compare() es vor, und die Tabelle liest du am besten von links nach rechts:

  • Das Dach ^1.4.2 erlaubt alles bis unter die nächste Hauptnummer. 1.9.3 ist dabei, 2.0.0 nicht. Das ist die übliche Angabe, und mit ihr bekommst du Fehlerbehebungen ohne Zutun.
  • Die Tilde ~1.4.2 erlaubt nur bis unter die nächste Nebennummer. 1.4.9 ist dabei, 1.5.0 nicht. Vorsichtiger, und manchmal genau richtig. Mit nur zwei Zahlen rutscht die Grenze eine Stelle nach vorn, und ~8.2 erlaubt wie ^8.2 alles bis unter 9.0.
  • 1.4.* ist dasselbe wie ~1.4.0, nur anders geschrieben.
  • 1.4.2 ohne Zeichen erlaubt nur diese eine Version.

Die Absprache hält, weil Paketautoren sie ernst nehmen. Nur hält sie eben nicht immer, und deshalb gibt es neben der composer.json eine zweite Datei.

Die ganze Datei auf einen Blick

Eine composer.json von vorn bis hinten
{
    "name": "hofladen/kasse",
    "description": "Kleine Kasse für den Hofladen",
    "type": "project",
    "license": "MIT",

    "require": {
        "php": "^8.2",
        "ramsey/uuid": "^4"
    },

    "require-dev": {
        "phpunit/phpunit": "^11"
    },

    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },

    "scripts": {
        "test": "phpunit",
        "kasse": "php bin/kasse.php"
    }
}

Das ist eine vollständige composer.json, wie sie in einem kleinen Projekt aussieht. Laufen tut sie nicht, sie ist zum Lesen da. Die Felder der Reihe nach:

  • name hat immer zwei Teile, Hersteller und Projekt, getrennt durch einen Schrägstrich und alles klein. Pflicht ist er nur, wenn du das Projekt als Paket veröffentlichst. Ich trage ihn trotzdem immer ein, dann sieht jeder, wem das Projekt gehört.
  • description, type und license sind Angaben über dein Projekt. Wer nichts veröffentlicht, kann sie knapp halten.
  • require und require-dev kennst du jetzt.
  • autoload sagt, wo dein eigener Code liegt und unter welchem Namen er zu finden ist. Darum geht es in der Lektion über Autoloading, und dort wird auch klar, was psr-4 bedeutet und warum hinter App zwei Backslashes stehen.
  • scripts sind Abkürzungen für Befehle. composer test führt dann aus, was hinter test steht. Praktisch, sobald ein Befehl länger wird als deine Geduld.

Die Datei composer.lock

Sobald du zum ersten Mal etwas installierst, legt Composer eine composer.lock an. Darin steht auf die Ziffer genau, welche Version tatsächlich geholt wurde, dazu die Stelle im Git des Pakets, aus der sie stammt, und alles, was die Pakete selbst noch mitgebracht haben.

Beide Dateien gehören in die Versionsverwaltung. In der composer.json steht, was erlaubt wäre. In der composer.lock steht, was bei dir wirklich läuft, und nach ihr installiert der Server exakt dasselbe. Ohne sie läuft dort vielleicht 1.9.3 und bei dir 1.4.2. Auffallen tut das dann an einem Freitagabend.

In der Aufgabe fehlen der composer.json des Hofladens noch drei Angaben.

Zum Mitnehmen

In der composer.json stehen Name, Pakete und der Ort des eigenen Codes, und schon ein Komma zu viel macht sie für Composer unlesbar. Mit einem Dach vor der Version darf Composer alles nehmen, was unter der nächsten Hauptnummer liegt, mit einer Tilde nur, was unter der nächsten Nebennummer liegt.

Jetzt du

Basis Konto, kostenlos

Zu dieser Lektion gehört eine Aufgabe. Du schreibst den Code selbst, und nach jedem Lauf sagt dir eine Prüfliste, was schon stimmt.

Dafür brauchst du das Basis Konto. Es kostet nichts, und ein Passwort gibt es auch nicht.

In diesem Kurs läuft dein Code auf einem Server. Dafür hat das Basis Konto 1 Stunde im Monat, mehr Zeit gibt es mit dem Premium Konto.

Was in dieser Lektion steckt

  • Artikel mit 3 Beispielen zum Ausprobieren

    Steht hier, ohne Konto lesbar.

  • Aufgabe, auf dem Server geprüft

    Öffnet sich mit dem Basis Konto.