Composer : conseils d'utilisation
*********************************

<div class=perex>

Composer est un outil de gestion des dépendances en PHP. Il vous permet de déclarer les bibliothèques dont dépend votre projet et il les installera et les mettra à jour pour vous. Nous allons apprendre :

- comment installer Composer
- comment l'utiliser dans un projet nouveau ou existant

</div>


Installation
============

Composer est un fichier exécutable `.phar` que vous téléchargez et installez comme suit.


Windows
-------

Utilisez l'installateur officiel [Composer-Setup.exe|https://getcomposer.org/Composer-Setup.exe].


Linux, macOS
------------

Il vous suffit de 4 commandes, que vous pouvez copier depuis [cette page |https://getcomposer.org/download/].

De plus, en le copiant dans un dossier figurant dans le `PATH` du système, Composer devient accessible globalement :

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


Utilisation dans un projet
==========================

Pour commencer à utiliser Composer dans votre projet, il vous suffit d'un fichier `composer.json`. Ce fichier décrit les dépendances de votre projet et peut aussi contenir d'autres métadonnées. Le `composer.json` le plus simple peut ressembler à ceci :

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

Nous disons ici que notre application (ou bibliothèque) requiert le paquet `nette/database` (le nom du paquet se compose du nom du fournisseur et du nom du projet) et qu'elle veut une version correspondant à la contrainte `^3.0` (c'est-à-dire la dernière version 3).

Avec le fichier `composer.json` à la racine du projet, exécutez donc :

```shell
composer update
```

Composer téléchargera Nette Database dans le répertoire `vendor/`. Il crée aussi un fichier `composer.lock`, qui contient l'information sur les versions exactes des bibliothèques installées.

Composer génère un fichier `vendor/autoload.php`. Il vous suffit d'inclure ce fichier pour commencer à utiliser les classes des bibliothèques sans travail supplémentaire :

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

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


Mettre les paquets à jour vers les dernières versions
=====================================================

Pour mettre à jour les bibliothèques utilisées vers les dernières versions autorisées par les contraintes définies dans `composer.json`, utilisez la commande `composer update`. Par exemple, avec la dépendance `"nette/database": "^3.0"`, il installera la dernière version 3.x.x, mais pas la version 4.

Pour mettre à jour les contraintes du fichier `composer.json`, par exemple vers `"nette/database": "^4.1"`, ce qui permet d'installer la dernière version, utilisez la commande `composer require nette/database`.

Pour mettre à jour tous les paquets Nette utilisés, il faudrait tous les énumérer sur la ligne de commande, par exemple :

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

Ce n'est pas pratique. Utilisez donc le petit script "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff, qui le fera pour vous :

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


Créer un nouveau projet
=======================

Vous pouvez créer un nouveau projet Nette en une seule commande :

```shell
composer create-project nette/web-project nom-du-projet
```

Remplacez `nom-du-projet` par le nom du répertoire de votre projet et exécutez la commande. Composer téléchargera depuis GitHub le dépôt `nette/web-project`, qui contient déjà un fichier `composer.json`, puis installera Nette Framework lui-même. Il ne reste plus qu'à [régler les permissions des répertoires |nette:troubleshooting#Régler les permissions des répertoires] `temp/` et `log/`, et le projet devrait être opérationnel.

Si vous savez sur quelle version de PHP votre projet sera hébergé, pensez à l'[indiquer |#Version de PHP].


Version de PHP
==============

Composer installe toujours les versions de paquets compatibles avec la version de PHP que vous utilisez actuellement (plus précisément la version de PHP employée en ligne de commande lors de l'exécution de Composer). Ce n'est peut-être pas la même version que celle de votre hébergement web. C'est pourquoi il est essentiel d'ajouter au fichier `composer.json` l'information sur la version de PHP de votre hébergement. Seules les versions de paquets compatibles avec l'hébergement seront alors installées.

Par exemple, pour indiquer que le projet tournera sur PHP 8.2.3, utilisez la commande :

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

La version sera écrite dans le fichier `composer.json` de cette façon :

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

Le numéro de version de PHP est cependant aussi indiqué ailleurs dans le fichier, dans la section `require`. Alors que le premier nombre détermine la version pour laquelle les paquets sont installés, le second indique la version pour laquelle l'application elle-même est écrite. PhpStorm s'en sert par exemple pour régler le *PHP language level*. (Bien sûr, il n'y a pas de sens à ce que ces versions diffèrent, cette double entrée est donc une maladresse.) Définissez cette version à l'aide de la commande :

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

Ou directement dans le fichier `composer.json` :

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


Ignorer la version de PHP
=========================

Les paquets indiquent généralement à la fois la version de PHP la plus basse avec laquelle ils sont compatibles et la version la plus élevée avec laquelle ils ont été testés. Si vous avez l'intention d'utiliser une version de PHP encore plus récente, par exemple pour tester, Composer refusera d'installer un tel paquet. La solution est l'option `--ignore-platform-req=php+`, qui fait ignorer à Composer les limites supérieures de la version de PHP requise.


Faux signalements
=================

Lors de la mise à jour des paquets ou du changement des numéros de version, des conflits surviennent parfois. Un paquet a des exigences qui entrent en conflit avec un autre, et ainsi de suite. Composer produit cependant parfois de faux signalements. Il annonce un conflit qui n'existe pas en réalité. Dans ce cas, supprimer le fichier `composer.lock` et réessayer peut aider.

Si le message d'erreur persiste, il est authentique et vous devez le lire pour comprendre quoi modifier et comment.


Packagist.org - le dépôt global
===============================

[Packagist |https://packagist.org] est le dépôt principal dans lequel Composer cherche les paquets par défaut. Vous pouvez aussi y publier vos propres paquets.


Et si nous ne voulons pas du dépôt central
------------------------------------------

Si nous avons dans notre entreprise des applications ou des bibliothèques internes qui ne peuvent pas être hébergées publiquement, nous pouvons créer nos propres dépôts pour elles.

Pour en savoir plus sur les dépôts, voir [la documentation officielle |https://getcomposer.org/doc/05-repositories.md#repositories].


Autoloading
===========

Une fonctionnalité clé de Composer est qu'il fournit l'autoloading de toutes les classes qu'il installe. Vous l'activez en incluant le fichier `vendor/autoload.php`.

Vous pouvez cependant aussi utiliser Composer pour charger d'autres classes situées en dehors du répertoire `vendor/`. La première possibilité est de laisser Composer parcourir des répertoires et sous-répertoires définis, y trouver toutes les classes et les inclure dans l'autoloader. Pour cela, définissez `autoload > classmap` dans `composer.json` :

```js
{
	"autoload": {
		"classmap": [
			"src/",      # inclut le répertoire src/ et ses sous-répertoires
		]
	}
}
```

Il faut ensuite exécuter la commande `composer dumpautoload` après chaque changement pour régénérer les tables d'autoloading. C'est extrêmement peu pratique. Il vaut bien mieux confier cette tâche à [RobotLoader|robot-loader:], qui effectue la même activité automatiquement en arrière-plan et bien plus vite.

La deuxième possibilité est de respecter [PSR-4 |https://www.php-fig.org/psr/psr-4/]. Dit simplement, c'est un système où les espaces de noms et les noms de classes correspondent à la structure des répertoires et aux noms de fichiers, par exemple `App\Core\RouterFactory` se trouvera dans le fichier `/path/to/App/Core/RouterFactory.php`. Exemple de configuration :

```js
{
	"autoload": {
		"psr-4": {
			"App\\": "app/"   # l'espace de noms App\ est dans le répertoire app/
		}
	}
}
```

Voir la [documentation de Composer |https://getcomposer.org/doc/04-schema.md#psr-4] pour les détails de configuration de ce comportement.


Tester de nouvelles versions
============================

Vous voulez tester une nouvelle version de développement d'un paquet ? Voici comment. Ajoutez d'abord cette paire d'options à votre fichier `composer.json`. Elle permet d'installer des versions de développement, mais Composer n'y aura recours que si aucune combinaison de versions stables ne satisfait les exigences :

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

Nous recommandons aussi de supprimer le fichier `composer.lock`, car Composer refuse parfois l'installation sans raison apparente et cela peut régler le problème.

Disons que le paquet est `nette/utils` et que la nouvelle version est la 4.0. Installez-la à l'aide de la commande :

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

Ou vous pouvez installer une version précise, par exemple la 4.0.0-RC2 :

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

Si un autre paquet dépend cependant de la bibliothèque et est verrouillé sur une version plus ancienne (par exemple `^3.1`), la solution idéale est de mettre à jour ce paquet dépendant pour qu'il fonctionne avec la nouvelle version. Mais si vous voulez simplement contourner la restriction et forcer Composer à installer la version de développement en la faisant passer pour une version plus ancienne (par exemple 3.1.6), vous pouvez utiliser le mot-clé `as` :

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


Appeler des commandes
=====================

Vous pouvez appeler vos propres commandes et scripts prédéfinis via Composer comme s'il s'agissait de commandes natives de Composer. Pour les scripts situés dans le répertoire `vendor/bin`, vous n'avez pas besoin d'indiquer ce chemin.

Définissons par exemple dans `composer.json` un script qui utilise [Nette Tester |tester:] pour lancer les tests :

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

Nous lançons ensuite les tests avec `composer tester`. Vous pouvez appeler la commande même si vous n'êtes pas dans le répertoire racine du projet, mais dans l'un de ses sous-répertoires.


Dire merci
==========

Voici une astuce pour faire plaisir aux auteurs open source. Vous pouvez facilement donner des étoiles sur GitHub aux bibliothèques que votre projet utilise. Il suffit d'installer la bibliothèque `symfony/thanks` :

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

Puis d'exécuter :

```shell
composer thanks
```

Essayez !


Configuration
=============

Composer est étroitement intégré à l'outil de gestion de versions [Git |https://git-scm.com]. Si Git n'est pas installé, vous devez indiquer à Composer de ne pas l'utiliser :

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