mitmario.dev

Ein Paket installieren

PHP Sandbox 4 Min Lesezeit 3 BeispieleLektion 3 von 7

Ein Paket von Hand zu holen heißt herunterladen, auspacken und in einen Ordner legen. Beim nächsten Update fängt das von vorn an, und welche Version gerade drinliegt, steht nirgends. Composer erledigt das mit einem Befehl, composer require ramsey/uuid. Hinter require steht der Name des Pakets, wie er auf Packagist steht.

In diesem Kurs tippst du den Befehl nicht selbst. Die Pakete für eine Lektion liegen schon fertig in der Maschine und werden ausgepackt, bevor dein Code startet, egal ob du auf Prüfen drückst, die Sandbox startest oder als Erstes etwas ins Terminal tippst. Ins Netz geht dabei nichts. Tippst du composer require trotzdem, bricht Composer nach rund einer Sekunde mit Network disabled, request canceled ab und lässt alles, wie es war. Die Maschine hat keine Verbindung nach draußen, und Composer ist in der Sandbox darauf eingestellt. Auf deinem eigenen Rechner ist es dieser eine Befehl, und der Rest dieser Lektion gilt dort genauso. Wie Composer selbst dorthin kommt, steht in der Lektion „PHP und Composer auf deinem Rechner“ am Ende dieses Abschnitts.

Was dabei passiert

Vier Dinge, in dieser Reihenfolge:

  1. Composer trägt den Wunsch in die composer.json ein.
  2. Es sucht auf Packagist die neueste Version, die zu deiner Angabe passt, samt allem, was das Paket mitbringt, und prüft dabei auch deine PHP-Version.
  3. Es schreibt das Ergebnis in die composer.lock.
  4. Erst jetzt lädt es die Pakete nach vendor/ und erzeugt vendor/autoload.php.

Geht Schritt 2 schief, nimmt es den Eintrag aus Schritt 1 wieder zurück. Für deinen Code zählt von allem nur vendor/autoload.php, und das ist die halbe Lektion.

Eine Zeile bindet alles ein

Die eine Zeile, die alles einbindet
<?php

declare(strict_types=1);

// Diese eine Zeile macht jedes installierte Paket benutzbar.
// __DIR__ ist der Ordner, in dem diese Datei liegt.
require __DIR__ . "/vendor/autoload.php";

use Ramsey\Uuid\Uuid;

echo "Erste Kennung:  ", Uuid::uuid4(), "\n";
echo "Zweite Kennung: ", Uuid::uuid4(), "\n";

$kennung = Uuid::uuid4();
echo "\nVersion der dritten: ", $kennung->getVersion(), "\n";
echo "Länge als Text:     ", strlen($kennung->toString()), "\n";

require __DIR__ . "/vendor/autoload.php"; steht ganz oben in der Datei, die als erste läuft, und zwar genau einmal im ganzen Projekt. Danach kannst du jede Klasse aus jedem installierten Paket benutzen, ohne eine weitere Zeile.

Was das Auspacken hinterlassen hat, siehst du im Terminal. ls zeigt neben deinen zwei Dateien einen Ordner vendor und eine composer.lock, die du beide nie angelegt hast. composer show listet, was installiert ist, je Paket eine Zeile mit Name, Version und Beschreibung. Es sind drei Zeilen für einen Wunsch. Warum das so ist, kommt in der nächsten Lektion.

Das ist der Unterschied zwischen Einbinden und Autoloading. ramsey/uuid besteht aus über hundert Dateien, find vendor/ramsey/uuid -name '*.php' | wc -l zählt 114. Ohne Autoloading müsstest du wissen, in welcher davon die Klasse Uuid steht. Die müsstest du einzeln einbinden und dazu jede Datei, die die wiederum braucht. Mit Autoloading merkt PHP beim ersten Uuid::uuid4(), dass es diese Klasse noch nicht kennt. Dann fragt es den Autoloader, und der weiß, welche Datei dazugehört. Geladen wird nur, was wirklich benutzt wird.

Das use Ramsey\Uuid\Uuid; darunter lädt übrigens gar nichts. Es ist eine Abkürzung, damit du unten Uuid::uuid4() schreiben kannst statt Ramsey\Uuid\Uuid::uuid4(). Warum Klassen aus Paketen so lange Namen haben, steht in der Lektion über Autoloading.

Wenn die Zeile fehlt

Wenn die Zeile fehlt
<?php

declare(strict_types=1);

// Das Paket ist installiert, es liegt in vendor/. Nur weiss PHP
// nichts davon, weil die require-Zeile fehlt.

echo "Diese Zeile läuft noch.\n";

echo Ramsey\Uuid\Uuid::uuid4(), "\n";

echo "Und hierher kommt das Programm nie.\n";

Vergessen ist die Zeile schnell, und die Meldung danach führt in die Irre, wenn man sie nicht kennt. Auf dem Fehlerkanal steht PHP Fatal error: Uncaught Error: Class "Ramsey\Uuid\Uuid" not found.

„Class not found“ liest sich wie „das Paket ist nicht installiert“. Dabei ist das Paket installiert. Es liegt in vendor/. PHP weiß nur nichts davon, weil niemand den Autoloader angemeldet hat. Bei dieser Meldung sehe ich zuerst nach, ob die require-Zeile oben in der Datei steht und auf den richtigen Ordner zeigt.

Im Terminal steht die erste Zeile noch da, der Absturz kommt erst danach. An der letzten Zeile der Ausgabe siehst du, wie weit das Programm gekommen ist.

Wunsch und Tatsache

Was in composer.lock steht
<?php

declare(strict_types=1);

// Wunsch und Tatsache nebeneinander. Beide Dateien sind JSON und
// werden mit den Mitteln aus Lektion 8.3 gelesen.

$wunsch = json_decode(file_get_contents("composer.json"), true);
$tatsache = json_decode(file_get_contents("composer.lock"), true);

echo "In der composer.json steht der Wunsch:\n";
foreach ($wunsch["require"] as $paket => $bereich) {
    echo "  ", $paket, " ", $bereich, "\n";
}

echo "\nIn der composer.lock steht, was daraus geworden ist:\n";
foreach ($tatsache["packages"] as $paket) {
    echo "  ", $paket["name"], " ", $paket["version"], "\n";
}

In der composer.json steht ^4. In der composer.lock steht eine Version auf die Ziffer genau. Die Versionen sind darin festgeschrieben, deshalb heißt so eine Datei Lockfile (englisch lock file). Im Beispiel liegen beide nebeneinander, und dieser Unterschied ist der ganze Grund, warum es zwei Dateien gibt. Lang ist das Lockfile auch, wc -l composer.lock zählt über zweihundert Zeilen für drei Pakete. head -20 composer.lock zeigt den Anfang, mit der Prüfsumme über deine composer.json (content-hash) und dem ersten Paket samt der Stelle im Git, aus der es stammt.

Daraus folgen zwei Befehle, die man leicht verwechselt:

  • composer install liest die composer.lock und stellt den Stand her, der dort festgehalten ist. Gibt es kein Lockfile, verhält es sich wie composer update und legt eins an.
  • composer update übergeht das Lockfile, fragt Packagist neu, holt die neuesten Versionen im erlaubten Bereich und schreibt das Lockfile neu.

Auf einem Server willst du immer composer install. Es liefert denselben Stand, den du getestet hast, ohne nach neueren Versionen zu suchen. composer update gehört auf den eigenen Rechner, mit Absicht und mit den Tests danach.

Den Unterschied siehst du hier gut, gerade weil die Maschine kein Netz hat. composer install im Terminal liest das Lockfile, sieht, dass alles schon da ist, und meldet Nothing to install, update or remove. In den zwei Zeilen davor steht, dass eine Liste von Packagist nicht zu holen war, und das ist dasselbe fehlende Netz. composer update dagegen scheitert sofort mit derselben Meldung wie composer require, weil es Packagist fragen will und ohne Antwort nichts tut.

In der Aufgabe bekommen die Bestellungen des Hofladens ihre Kennungen aus dem Paket.

Zum Mitnehmen

Den Wunsch schreibt composer require in die composer.json, den festen Stand in das Lockfile composer.lock. Benutzbar wird ein Paket erst über die Zeile mit vendor/autoload.php, ohne sie meldet PHP Class not found, obwohl es daliegt. Auf dem Server läuft composer install, denn es stellt den Stand aus dem Lockfile wieder her.

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, dein Code läuft auf einem Server

    Öffnet sich mit dem Basis Konto.