Composer: Tipps zur Verwendung

Installation

Composer ist eine ausführbare .phar-Datei, die Sie folgendermaßen herunterladen und installieren:

Windows

Verwenden Sie den offiziellen Installer Composer-Setup.exe.

Linux, macOS

Es genügen 4 Befehle, die Sie sich von dieser Seite kopieren können.

Wenn Sie die Datei außerdem in ein Verzeichnis legen, das im System-PATH liegt, wird Composer global verfügbar:

$ mv ./composer.phar ~/bin/composer # oder /usr/local/bin/composer

Verwendung im Projekt

Um Composer in Ihrem Projekt zu verwenden, brauchen Sie nur eine Datei composer.json. Sie beschreibt die Abhängigkeiten Ihres Projekts und kann außerdem weitere Metadaten enthalten. Die einfachste composer.json kann so aussehen:

{
	"require": {
		"nette/database": "^3.0"
	}
}

Wir sagen hier, dass unsere Anwendung (oder Bibliothek) das Paket nette/database benötigt (der Paketname besteht aus dem Namen der Organisation und dem Namen des Projekts) und eine Version verlangt, die der Bedingung ^3.0 entspricht (also die neueste Version 3).

Wir haben also im Wurzelverzeichnis des Projekts die Datei composer.json und starten:

composer update

Composer lädt Nette Database in das Verzeichnis vendor/ herunter. Außerdem erzeugt er die Datei composer.lock, die Informationen darüber enthält, welche Bibliotheksversionen genau installiert wurden.

Composer erzeugt die Datei vendor/autoload.php. Diese Datei können Sie einfach einbinden und die Klassen der Bibliotheken ohne jede weitere Arbeit verwenden:

require __DIR__ . '/vendor/autoload.php';

$db = new Nette\Database\Connection('sqlite::memory:');

Aktualisierung der Pakete auf die neuesten Versionen

Für die Aktualisierung der verwendeten Bibliotheken auf die neuesten Versionen gemäß den in composer.json definierten Bedingungen ist der Befehl composer update zuständig. Bei der Abhängigkeit "nette/database": "^3.0" installiert er zum Beispiel die neueste Version 3.x.x, aber nicht mehr Version 4.

Um die Bedingungen in der Datei composer.json zu aktualisieren, etwa auf "nette/database": "^4.1", damit die neueste Version installiert werden kann, verwenden Sie den Befehl composer require nette/database.

Um alle verwendeten Nette-Pakete zu aktualisieren, müssten Sie sie alle auf der Kommandozeile aufzählen, z. B.:

composer require nette/application nette/forms latte/latte tracy/tracy ...

Das ist unpraktisch. Verwenden Sie deshalb das einfache Skript Composer Frontline, das das für Sie erledigt:

php composer-frontline.php

Erstellung eines neuen Projekts

Ein neues Nette-Projekt erstellen Sie mit einem einzigen Befehl:

composer create-project nette/web-project projektname

Setzen Sie für projektname den Verzeichnisnamen Ihres Projekts ein und führen Sie den Befehl aus. Composer lädt das Repository nette/web-project von GitHub herunter, das bereits eine Datei composer.json enthält, und danach gleich das Nette Framework selbst. Es sollte nur noch nötig sein, die Verzeichnisrechte zu setzen für die Verzeichnisse temp/ und log/, und das Projekt sollte laufen.

Wenn Sie wissen, auf welcher PHP-Version Ihr Projekt gehostet wird, stellen Sie sie unbedingt ein.

PHP-Version

Composer installiert immer diejenigen Paketversionen, die mit der PHP-Version kompatibel sind, die Sie gerade verwenden (genauer gesagt mit der PHP-Version, die beim Ausführen von Composer auf der Kommandozeile benutzt wird). Das ist aber vermutlich nicht dieselbe Version, die Ihr Hosting verwendet. Deshalb ist es sehr wichtig, in die Datei composer.json die Information über die PHP-Version auf dem Hosting einzutragen. Danach werden nur noch Paketversionen installiert, die mit dem Hosting kompatibel sind.

Dass das Projekt zum Beispiel auf PHP 8.2.3 läuft, stellen wir mit diesem Befehl ein:

composer config platform.php 8.2.3

So wird die Version in die Datei composer.json geschrieben:

{
	"config": {
		"platform": {
			"php": "8.2.3"
		}
	}
}

Die PHP-Versionsnummer wird allerdings noch an einer anderen Stelle der Datei angegeben, nämlich im Abschnitt require. Während die erste Zahl bestimmt, für welche Version die Pakete installiert werden, sagt die zweite Zahl, für welche Version die Anwendung selbst geschrieben ist. Danach richtet zum Beispiel PhpStorm das PHP language level ein. (Natürlich ergibt es keinen Sinn, dass sich diese Versionen unterscheiden, die doppelte Angabe ist also ein Versäumnis.) Diese Version stellen Sie mit folgendem Befehl ein:

composer require php 8.2.3 --no-update

Oder direkt in der Datei composer.json:

{
	"require": {
		"php": "8.2.3"
	}
}

Ignorieren der PHP-Version

Pakete geben in der Regel sowohl die niedrigste PHP-Version an, mit der sie kompatibel sind, als auch die höchste, mit der sie getestet wurden. Wenn Sie eine noch neuere PHP-Version verwenden wollen, etwa zu Testzwecken, wird Composer die Installation eines solchen Pakets verweigern. Die Lösung ist die Option --ignore-platform-req=php+, die dafür sorgt, dass Composer die oberen Grenzen der geforderten PHP-Version ignoriert.

Falsche Meldungen

Beim Upgrade von Paketen oder beim Ändern von Versionsnummern kommt es manchmal zu Konflikten. Ein Paket hat Anforderungen, die im Widerspruch zu einem anderen stehen, und so weiter. Composer gibt aber gelegentlich falsche Meldungen aus. Er meldet einen Konflikt, der in Wirklichkeit gar nicht existiert. In solchen Fällen hilft es, die Datei composer.lock zu löschen und es erneut zu versuchen.

Wenn die Fehlermeldung bestehen bleibt, ist sie ernst gemeint, und Sie müssen ihr entnehmen, was und wie zu ändern ist.

Packagist.org – zentrales Repository

Packagist ist das Haupt-Repository, in dem Composer standardmäßig nach Paketen sucht. Sie können hier auch eigene Pakete veröffentlichen.

Was, wenn wir kein zentrales Repository verwenden möchten?

Wenn wir firmeninterne Anwendungen oder Bibliotheken haben, die wir schlicht nicht öffentlich hosten können, legen wir uns für sie eigene Repositories an.

Mehr zum Thema Repositories finden Sie in der offiziellen Dokumentation.

Autoloading

Eine wesentliche Eigenschaft von Composer ist, dass er Autoloading für alle von ihm installierten Klassen bereitstellt. Sie starten es, indem Sie die Datei vendor/autoload.php einbinden.

Sie können Composer aber auch zum Laden weiterer Klassen außerhalb des Verzeichnisses vendor/ verwenden. Die erste Möglichkeit besteht darin, Composer definierte Verzeichnisse und Unterverzeichnisse durchsuchen, alle Klassen finden und in den Autoloader aufnehmen zu lassen. Das erreichen Sie mit der Einstellung autoload > classmap in composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      # schließt das Verzeichnis src/ und seine Unterverzeichnisse ein
		]
	}
}

Anschließend müssen Sie nach jeder Änderung den Befehl composer dumpautoload ausführen und die Autoloading-Tabellen neu erzeugen lassen. Das ist außerordentlich unbequem. Weitaus besser ist es, diese Aufgabe dem RobotLoader anzuvertrauen, der dieselbe Tätigkeit automatisch im Hintergrund und viel schneller erledigt.

Die zweite Möglichkeit ist, sich an PSR-4 zu halten. Vereinfacht gesagt handelt es sich um ein System, bei dem Namespaces und Klassennamen der Verzeichnisstruktur und den Dateinamen entsprechen, also z. B. App\Core\RouterFactory liegt in der Datei /path/to/App/Core/RouterFactory.php. Beispielkonfiguration:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # der Namespace App\ liegt im Verzeichnis app/
		}
	}
}

Wie genau Sie dieses Verhalten konfigurieren, erfahren Sie in der Composer-Dokumentation.

Testen neuer Versionen

Sie wollen eine neue Entwicklungsversion eines Pakets testen? So geht es. Fügen Sie zuerst dieses Optionspaar in Ihre Datei composer.json ein. Es erlaubt die Installation von Entwicklungsversionen, Composer greift aber nur dann darauf zurück, wenn keine Kombination stabiler Versionen die Anforderungen erfüllt:

{
	"minimum-stability": "dev",
	"prefer-stable": true,
}

Außerdem empfehlen wir, die Datei composer.lock zu löschen, denn manchmal verweigert Composer die Installation auf unerklärliche Weise, und das löst das Problem.

Nehmen wir an, es handelt sich um das Paket nette/utils und die neue Version trägt die Nummer 4.0. Sie installieren sie mit dem Befehl:

composer require nette/utils:4.0.x-dev

Oder Sie können eine konkrete Version installieren, zum Beispiel 4.0.0-RC2:

composer require nette/utils:4.0.0-RC2

Wenn aber ein anderes Paket von der Bibliothek abhängt und auf eine ältere Version festgelegt ist (z. B. ^3.1), ist die ideale Lösung, dieses Paket zu aktualisieren, damit es mit der neuen Version funktioniert. Wenn Sie die Einschränkung jedoch nur umgehen und Composer zwingen wollen, die Entwicklungsversion zu installieren und vorzugeben, es handle sich um eine ältere Version (z. B. 3.1.6), können Sie das Schlüsselwort as verwenden:

composer require nette/utils "4.0.x-dev as 3.1.6"

Aufruf von Befehlen

Über Composer lassen sich eigene, vorbereitete Befehle und Skripte aufrufen, als wären es native Composer-Befehle. Bei Skripten, die im Verzeichnis vendor/bin liegen, müssen Sie diesen Pfad nicht angeben.

Als Beispiel definieren wir in der Datei composer.json ein Skript, das mit Nette Tester die Tests startet:

{
	"scripts": {
		"tester": "tester tests -s"
	}
}

Die Tests starten wir dann mit composer tester. Den Befehl können Sie auch dann aufrufen, wenn Sie sich nicht im Wurzelverzeichnis des Projekts befinden, sondern in einem seiner Unterverzeichnisse.

Senden Sie ein Dankeschön

Wir zeigen Ihnen einen Trick, mit dem Sie Open-Source-Autoren eine Freude machen. Sie geben auf einfache Weise den Bibliotheken, die Ihr Projekt verwendet, einen Stern auf GitHub. Es genügt, die Bibliothek symfony/thanks zu installieren:

composer global require symfony/thanks

Und dann auszuführen:

composer thanks

Probieren Sie es aus!

Konfiguration

Composer ist eng mit dem Versionierungswerkzeug Git verbunden. Wenn Sie es nicht installiert haben, müssen Sie Composer mitteilen, dass er es nicht verwenden soll:

composer -g config preferred-install dist