Tipps zur Verwendung von Composer
*********************************

<div class=perex>

Composer ist ein Werkzeug zur Verwaltung von Abhängigkeiten in PHP. Es erlaubt Ihnen, die Bibliotheken, von denen Ihr Projekt abhängt, zu deklarieren, und es wird sie für Sie installieren und aktualisieren. Wir werden lernen:

- wie man Composer installiert
- wie man ihn in einem neuen oder bestehenden Projekt verwendet

</div>


Einrichtung .[#toc-installation]
================================

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


Windows .[#toc-windows]
-----------------------

Verwenden Sie das offizielle Installationsprogramm [Composer-Setup.exe |https://getcomposer.org/Composer-Setup.exe].


Linux, macOS .[#toc-linux-macos]
--------------------------------

Alles was Sie brauchen sind 4 Befehle, die Sie von [dieser Seite |https://getcomposer.org/download/] kopieren können.

Außerdem wird Composer durch Kopieren in einen Ordner im `PATH` global zugänglich:

```shell
$ mv ./composer.phar ~/bin/composer # or /usr/local/bin/composer
```


Verwendung im Projekt .[#toc-use-in-project]
============================================

Um Composer in Ihrem Projekt verwenden zu können, benötigen Sie lediglich eine `composer.json` Datei. Diese Datei beschreibt die Abhängigkeiten Ihres Projekts und kann auch andere Metadaten enthalten. Die einfachste `composer.json` kann wie folgt aussehen:

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

Wir sagen hier, dass unsere Anwendung (oder Bibliothek) von dem Paket `nette/database` abhängt (der Name des Pakets besteht aus dem Namen des Herstellers und dem Namen des Projekts) und die Version benötigt, die der Versionsbeschränkung `^3.0` entspricht.

Wenn wir also die Datei `composer.json` im Projektstamm haben und sie ausführen:

```shell
composer update
```

Der Composer lädt die Nette-Datenbank in das Verzeichnis `vendor` herunter. Außerdem wird eine Datei `composer.lock` erstellt, die Informationen darüber enthält, welche Bibliotheksversionen genau installiert wurden.

Composer erzeugt eine `vendor/autoload.php` Datei. Sie können diese Datei einfach einbinden und die Klassen, die diese Bibliotheken bereitstellen, ohne zusätzliche Arbeit verwenden:

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

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


Pakete auf die neuesten Versionen aktualisieren .[#toc-update-packages-to-the-latest-versions]
==============================================================================================

Um alle verwendeten Pakete auf die neueste Version gemäß den in `composer.json` definierten Versionsbeschränkungen zu aktualisieren, verwenden Sie den Befehl `composer update`. Zum Beispiel wird für die Abhängigkeit `"nette/database": "^3.0"` die neueste Version 3.x.x installiert, aber nicht Version 4.

Um die Versionseinschränkungen in der Datei `composer.json` z.B. 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üssen Sie diese in der Befehlszeile auflisten, z. B:

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

Das ist unpraktisch. Verwenden Sie daher ein einfaches Skript "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff, das diese Aufgabe für Sie übernimmt:

```shell
php composer-frontline.php
```


Neues Projekt erstellen .[#toc-creating-new-project]
====================================================

Ein neues Nette-Projekt kann durch Ausführen eines einfachen Befehls erstellt werden:

```shell
composer create-project nette/web-project name-of-the-project
```

Anstelle von `name-of-the-project` sollten Sie den Namen des Verzeichnisses für Ihr Projekt angeben und den Befehl ausführen. Composer wird das Repository `nette/web-project` von GitHub holen, das bereits die Datei `composer.json` enthält, und gleich danach das Nette Framework selbst installieren. Nun müssen nur noch die [Schreibrechte |nette:troubleshooting#setting-directory-permissions] für die Verzeichnisse `temp/` und `log/` [überprüft |nette:troubleshooting#setting-directory-permissions] werden und schon kann es losgehen.

Wenn Sie wissen, mit welcher PHP-Version das Projekt gehostet werden soll, sollten Sie [diese |#PHP Version] unbedingt einrichten.


PHP-Version .[#toc-php-version]
===============================

Composer installiert immer die Versionen der Pakete, die mit der PHP-Version kompatibel sind, die Sie gerade verwenden (oder besser gesagt, die PHP-Version, die auf der Kommandozeile verwendet wird, wenn Sie Composer starten). Das ist wahrscheinlich nicht die Version, die Ihr Webhost verwendet. Deshalb ist es sehr wichtig, dass Sie Informationen über die PHP-Version Ihres Hosts in Ihre Datei `composer.json` aufnehmen. Danach werden nur noch die Versionen der Pakete installiert, die mit dem Host kompatibel sind.

Um zum Beispiel das Projekt auf PHP 8.2.3 einzustellen, verwenden Sie den Befehl:

```shell
composer config platform.php 8.2.3
```

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

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

Die PHP-Versionsnummer wird jedoch auch an anderer Stelle in der Datei aufgeführt, im Abschnitt `require`. Während die erste Zahl die Version angibt, für die Pakete installiert werden, sagt die zweite Zahl, für welche Version die Anwendung selbst geschrieben wurde.
(Natürlich macht es keinen Sinn, dass diese Versionen unterschiedlich sind, daher ist die doppelte Angabe eine Redundanz). Sie setzen diese Version mit dem Befehl:

```shell
composer require php 8.2.3 --no-update
```

Oder direkt in der Datei "Composer.json":

```js
{
	"require": {
		"php": "8.2.3"
	}
}
```


PHP-Version ignorieren .[#toc-ignoring-php-version]
===================================================

Pakete geben normalerweise sowohl die niedrigste Version von PHP an, mit der sie kompatibel sind, als auch die höchste Version, mit der sie getestet wurden. Wenn Sie vorhaben, eine noch neuere Version von PHP zu verwenden, etwa zu Testzwecken, wird Composer die Installation eines solchen Pakets verweigern. Die Lösung besteht darin, die Option `--ignore-platform-req=php+` zu verwenden, die Composer veranlasst, die Obergrenzen der erforderlichen PHP-Version zu ignorieren.


False Berichte .[#toc-false-reports]
====================================

Bei der Aktualisierung von Paketen oder der Änderung von Versionsnummern kommt es zu Konflikten. Ein Paket hat Anforderungen, die mit einem anderen in Konflikt stehen, und so weiter. Composer gibt jedoch gelegentlich eine falsche Meldung aus. Er meldet einen Konflikt, der nicht wirklich existiert. In diesem Fall hilft es, die Datei `composer.lock` zu löschen und es erneut zu versuchen.

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


Packagist.org - Globales Repository .[#toc-packagist-org-global-repository]
===========================================================================

[Packagist |https://packagist.org] ist das Hauptpaket-Repository, in dem Composer versucht, Pakete zu suchen, wenn nicht anders angegeben. Sie können hier auch Ihre eigenen Pakete veröffentlichen.


Was, wenn wir das zentrale Repository nicht wollen? .[#toc-what-if-we-don-t-want-the-central-repository]
--------------------------------------------------------------------------------------------------------

Wenn wir interne Anwendungen oder Bibliotheken in unserem Unternehmen haben, die nicht öffentlich auf Packagist gehostet werden können, können wir unsere eigenen Repositories für diese Projekte erstellen.

Mehr über Repositories finden Sie in der [offiziellen Dokumentation |https://getcomposer.org/doc/05-repositories.md#repositories].


Autoloading .[#toc-autoloading]
===============================

Eine Schlüsselfunktion von Composer ist das automatische Laden aller installierten Klassen, das Sie durch Einfügen einer Datei `vendor/autoload.php` starten.

Es ist jedoch auch möglich, Composer zu verwenden, um andere Klassen außerhalb des Ordners `vendor` zu laden. Die erste Möglichkeit besteht darin, Composer die definierten Ordner und Unterordner durchsuchen zu lassen, alle Klassen zu finden und sie in den Autoloader aufzunehmen. Dazu setzen Sie `autoload > classmap` in `composer.json`:

```js
{
	"autoload": {
		"classmap": [
			"src/",      #  includes the src/ folder and its subfolders
		]
	}
}
```

Anschließend müssen Sie bei jeder Änderung den Befehl `composer dumpautoload` ausführen und die Autoloader-Tabellen neu generieren lassen. Dies ist äußerst lästig, und es ist weitaus besser, diese Aufgabe [RobotLoader |robot-loader:] anzuvertrauen, der dieselbe Tätigkeit automatisch im Hintergrund und viel schneller durchführt.

Die zweite Möglichkeit ist, [PSR-4 |https://www.php-fig.org/psr/psr-4/] zu folgen. Einfach gesagt handelt es sich um ein System, bei dem die Namensräume und Klassennamen der Verzeichnisstruktur und den Dateinamen entsprechen, d. h. `App\Core\RouterFactory` befindet sich in der Datei `/path/to/App/Core/RouterFactory.php`. Beispiel für eine Konfiguration:

```js
{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # the App\ namespace is in the app/ directory
		}
	}
}
```

In der [Composer-Dokumentation |https://getcomposer.org/doc/04-schema.md#psr-4] finden Sie eine genaue Beschreibung, wie Sie dieses Verhalten konfigurieren können.


Testen neuer Versionen .[#toc-testing-new-versions]
===================================================

Sie möchten eine neue Entwicklungsversion eines Pakets testen. Wie kann man das tun? Fügen Sie zunächst dieses Paar von Optionen in die Datei `composer.json` ein, das es Ihnen ermöglicht, Entwicklungsversionen von Paketen zu installieren, aber nur, wenn es keine Kombination aus stabiler Version gibt, die den Anforderungen entspricht:

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

Wir empfehlen auch, die Datei `composer.lock` zu löschen, da Composer manchmal unverständlicherweise die Installation verweigert und dies das Problem lösen wird.

Nehmen wir an, das Paket heißt `nette/utils` und die neue Version ist 4.0. Sie installieren es mit dem Befehl:

```shell
composer require nette/utils:4.0.x-dev
```

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

```shell
composer require nette/utils:4.0.0-RC2
```

Wenn ein anderes Paket von der Bibliothek abhängt und auf eine ältere Version beschränkt ist (z. B. `^3.1`), ist es ideal, das Paket zu aktualisieren, damit es mit der neuen Version funktioniert.
Wenn Sie jedoch nur die Beschränkung umgehen und Composer zwingen wollen, die Entwicklungsversion zu installieren und so zu tun, als ob es sich um eine ältere Version handelt (z. B. 3.1.6), können Sie das Schlüsselwort `as` verwenden:

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


Aufrufen von Befehlen .[#toc-calling-commands]
==============================================

Sie können Ihre eigenen benutzerdefinierten Befehle und Skripte über Composer so aufrufen, als wären es native Composer-Befehle. Skripte, die sich im Ordner `vendor/bin` befinden, müssen diesen Ordner nicht angeben.

Als Beispiel definieren wir ein Skript in der Datei `composer.json`, das [Nette Tester |tester:] verwendet, um Tests auszuführen:

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

Wir führen die Tests dann mit `composer tester` aus. Wir können den Befehl auch dann aufrufen, wenn wir uns nicht im Stammverzeichnis des Projekts, sondern in einem Unterverzeichnis befinden.


Dank senden .[#toc-send-thanks]
===============================

Wir werden Ihnen einen Trick zeigen, der Open-Source-Autoren glücklich machen wird. Sie können den Bibliotheken, die Ihr Projekt verwendet, ganz einfach einen Stern auf GitHub geben. Installieren Sie einfach die Bibliothek `symfony/thanks`:

```shell
composer global require symfony/thanks
```

Und dann ausführen:

```shell
composer thanks
```

Versuchen Sie es!


Konfiguration .[#toc-configuration]
===================================

Composer ist eng mit dem Versionskontrollwerkzeug [Git |https://git-scm.com] integriert. Wenn Sie Git nicht verwenden, müssen Sie dies dem Composer mitteilen:

```shell
composer -g config preferred-install dist
```

{{sitename: Bewährte Praktiken}}