Composer: Tipps zur Verwendung

Installation

Composer ist eine ausführbare .phar-Datei, die Sie herunterladen und wie folgt installieren:

Windows

Verwenden Sie den offiziellen Installer Composer-Setup.exe.

Linux, macOS

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

Durch das Ablegen im Ordner, der im System-PATH enthalten ist, wird Composer global zugänglich:

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

Verwendung im Projekt

Um Composer in Ihrem Projekt verwenden zu können, benötigen Sie lediglich die Datei composer.json. Diese beschreibt die Abhängigkeiten Ihres Projekts und kann auch weitere Metadaten enthalten. Eine grundlegende composer.json kann also so aussehen:

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

Hier geben wir an, dass unsere Anwendung (oder Bibliothek) das Paket nette/database benötigt (der Paketname setzt sich aus dem Organisationsnamen und dem Projektnamen zusammen) und eine Version wünscht, die der Bedingung ^3.0 entspricht (d.h. die neueste Version 3).

Wir haben also im Projektstamm die Datei composer.json und starten die Installation mit:

composer update

Composer lädt Nette Database in den Ordner vendor/. Außerdem erstellt er die Datei composer.lock, die Informationen darüber enthält, welche Versionen der Bibliotheken genau installiert wurden.

Composer generiert die Datei vendor/autoload.php, die wir einfach einbinden können und sofort mit der Verwendung der Bibliotheken beginnen können, ohne weitere Arbeit:

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

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

Aktualisierung der Pakete auf die neuesten Versionen

Die Aktualisierung der verwendeten Bibliotheken auf die neuesten Versionen gemäß den in composer.json definierten Bedingungen übernimmt der Befehl composer update. Z.B. bei der Abhängigkeit "nette/database": "^3.0" installiert er die neueste Version 3.x.x, aber nicht mehr Version 4.

Um die Bedingungen in der Datei composer.json beispielsweise auf "nette/database": "^4.1" zu aktualisieren, 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 in der Befehlszeile auflisten, z.B.:

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

Was unpraktisch ist. Verwenden Sie stattdessen das einfache Skript Composer Frontline, das dies 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

Geben Sie als projektname den Namen des Verzeichnisses für Ihr Projekt ein und bestätigen Sie. Composer lädt das Repository nette/web-project von GitHub herunter, das bereits die Datei composer.json enthält, und gleich danach das Nette Framework. Es sollte nur noch notwendig sein, die Berechtigungen für das Schreiben in die Ordner temp/ und log/ festzulegen, und das Projekt sollte zum Leben erweckt werden.

Wenn Sie wissen, auf welcher PHP-Version das Projekt gehostet wird, vergessen Sie nicht, sie einzustellen.

PHP-Version

Composer installiert immer die Versionen von Paketen, die mit der PHP-Version kompatibel sind, die Sie gerade verwenden (genauer gesagt, mit der PHP-Version, die in der Befehlszeile beim Ausführen von Composer verwendet wird). Dies ist jedoch wahrscheinlich nicht die gleiche Version, die Ihr Hosting verwendet. Daher ist es sehr wichtig, der Datei composer.json Informationen über die PHP-Version auf dem Hosting hinzuzufügen. Danach werden nur noch Versionen von Paketen installiert, die mit dem Hosting kompatibel sind.

Dass das Projekt beispielsweise auf PHP 8.2.3 laufen wird, legen wir mit dem Befehl fest:

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 jedoch noch an einer anderen Stelle der Datei angegeben, und zwar im Abschnitt require. Während die erste Zahl angibt, für welche Version Pakete installiert werden, gibt die zweite Zahl an, für welche Version die Anwendung selbst geschrieben ist. Und danach stellt beispielsweise PhpStorm das PHP language level ein. (Natürlich macht es keinen Sinn, dass sich diese Versionen unterscheiden, daher ist die doppelte Angabe eine Ungeschicklichkeit.) Diese Version stellen Sie mit dem 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 möchten, beispielsweise zum Testen, wird Composer die Installation eines solchen Pakets verweigern. Die Lösung ist die Option --ignore-platform-req=php+, die bewirkt, dass Composer die Obergrenzen der erforderlichen PHP-Version ignoriert.

Falsche Meldungen

Beim Upgrade von Paketen oder Änderungen der Versionsnummern kommt es vor, dass ein Konflikt auftritt. Ein Paket hat Anforderungen, die im Widerspruch zu einem anderen stehen und ähnliches. Composer gibt jedoch manchmal falsche Meldungen aus. Er meldet einen Konflikt, der real nicht existiert. In diesem Fall 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 daraus entnehmen, was und wie Sie es anpassen müssen.

Packagist.org – zentrales Repository

Packagist ist das Haupt-Repository, in dem Composer versucht, Pakete zu finden, wenn wir ihm nichts anderes sagen. Wir können hier auch eigene Pakete veröffentlichen.

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

Wenn wir firmeninterne Anwendungen haben, die wir einfach nicht öffentlich hosten können, erstellen wir dafür ein Firmen-Repository.

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, das Sie durch Einbinden der Datei vendor/autoload.php starten.

Es ist jedoch auch möglich, Composer zum Laden weiterer Klassen auch außerhalb des Ordners vendor zu verwenden. Die erste Möglichkeit ist, Composer definierte Ordner und Unterordner durchsuchen zu lassen, alle Klassen zu finden und sie in den Autoloader aufzunehmen. Dies erreichen Sie durch die Einstellung autoload > classmap in composer.json:

{
	"autoload": {
		"classmap": [
			"src/",      #  beinhaltet den Ordner src/ und seine Unterordner
		]
	}
}

Anschließend muss bei jeder Änderung der Befehl composer dumpautoload ausgeführt und die Autoloading-Tabellen neu generiert werden. Das ist äußerst unpraktisch, und es ist viel besser, diese Aufgabe dem RobotLoader zu überlassen, der dieselbe Tätigkeit automatisch im Hintergrund und viel schneller erledigt.

Die zweite Möglichkeit ist, PSR-4 einzuhalten. Vereinfacht gesagt handelt es sich um ein System, bei dem Namensräume und Klassennamen der Verzeichnisstruktur und den Dateinamen entsprechen, d.h. z.B. App\Core\RouterFactory befindet sich in der Datei /path/to/App/Core/RouterFactory.php. Beispielkonfiguration:

{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # Der Namensraum App\ befindet sich im Verzeichnis app/
		}
	}
}

Wie genau das Verhalten konfiguriert wird, erfahren Sie in der Composer-Dokumentation.

Testen neuer Versionen

Sie möchten eine neue Entwicklungsversion eines Pakets testen. Wie gehen Sie vor? Fügen Sie zunächst dieses Optionspaar zur Datei composer.json hinzu, das die Installation von Entwicklungsversionen von Paketen erlaubt, aber nur darauf zurückgreift, wenn keine Kombination von stabilen Versionen existiert, die den Anforderungen entspricht:

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

Weiterhin empfehlen wir, die Datei composer.lock zu löschen, da Composer manchmal unverständlicherweise die Installation verweigert und dies das Problem löst.

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

composer require nette/utils:4.0.x-dev

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

composer require nette/utils:4.0.0-RC2

Wenn jedoch ein anderes Paket von der Bibliothek abhängt, das auf eine ältere Version gesperrt ist (z.B. ^3.1), ist es ideal, das Paket zu aktualisieren, damit es mit der neuen Version funktioniert. Wenn Sie jedoch die Einschränkung nur umgehen und Composer zwingen möchten, die Entwicklungsversion zu installieren und so zu tun, als wäre es 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 können eigene vorbereitete Befehle und Skripte aufgerufen werden, als wären es native Composer-Befehle. Bei Skripten, die sich im Ordner vendor/bin befinden, muss dieser Ordner nicht angegeben werden.

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

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

Die Tests starten wir dann mit composer tester. Den Befehl können wir auch aufrufen, wenn wir uns nicht im Stammverzeichnis des Projekts, sondern in einem Unterverzeichnis befinden.

Senden Sie ein Dankeschön

Wir zeigen Ihnen einen Trick, mit dem Sie die Autoren von Open Source erfreuen können. Geben Sie auf GitHub den Bibliotheken, die Ihr Projekt verwendet, auf einfache Weise einen Stern. Installieren Sie einfach die Bibliothek symfony/thanks:

composer global require symfony/thanks

Und führen Sie dann aus:

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, es nicht zu verwenden:

composer -g config preferred-install dist