Conseils d'utilisation du compositeur
*************************************

<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
- l'utiliser dans un projet nouveau ou existant

</div>


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

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


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

Utilisez le programme d'installation officiel [Composer-Setup.exe |https://getcomposer.org/Composer-Setup.exe].


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

Tout ce dont vous avez besoin, c'est de 4 commandes, que vous pouvez copier à partir de [cette page |https://getcomposer.org/download/].

De plus, en copiant dans le dossier qui se trouve dans le système `PATH`, Composer devient globalement accessible :

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


Utilisation dans le projet .[#toc-use-in-project]
=================================================

Pour commencer à utiliser Composer dans votre projet, tout ce dont vous avez besoin est un fichier `composer.json`. Ce fichier décrit les dépendances de votre projet et peut également contenir d'autres métadonnées. Le fichier `composer.json` le plus simple peut ressembler à ceci :

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

Nous disons ici que notre application (ou bibliothèque) dépend du paquet `nette/database` (le nom du paquet est composé d'un nom de fournisseur et du nom du projet) et qu'elle veut la version qui correspond à la contrainte de version `^3.0`.

Ainsi, lorsque nous avons le fichier `composer.json` à la racine du projet et que nous exécutons :

```shell
composer update
```

Composer téléchargera la base de données Nette dans le répertoire `vendor`. Il crée également un fichier `composer.lock`, qui contient des informations sur les versions exactes des bibliothèques qu'il a installées.

Composer génère un fichier `vendor/autoload.php`. Vous pouvez simplement inclure ce fichier et commencer à utiliser les classes que ces bibliothèques fournissent sans aucun travail supplémentaire :

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

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


Mise à jour des paquets vers les dernières versions .[#toc-update-packages-to-the-latest-versions]
==================================================================================================

Pour mettre à jour tous les paquets utilisés à la dernière version selon les contraintes de version définies dans `composer.json`, utilisez la commande `composer update`. Par exemple, pour la dépendance `"nette/database": "^3.0"`, elle installera la dernière version 3.x.x, mais pas la version 4.

Pour mettre à jour les contraintes de version dans le fichier `composer.json`, par exemple `"nette/database": "^4.1"`, afin de permettre l'installation de la dernière version, utilisez la commande `composer require nette/database`.

Pour mettre à jour tous les paquets Nette utilisés, il serait nécessaire de les lister tous sur la ligne de commande, par ex :

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

Ce qui n'est pas pratique. Par conséquent, utilisez un simple script "Composer Frontline":https://gist.github.com/dg/734bebf55cf28ad6a5de1156d3099bff qui le fera pour vous :

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


Création d'un nouveau projet .[#toc-creating-new-project]
=========================================================

Un nouveau projet Nette peut être créé en exécutant une simple commande :

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

A la place de `name-of-the-project`, vous devez fournir le nom du répertoire de votre projet et exécuter la commande. Composer ira chercher le dépôt `nette/web-project` de GitHub, qui contient déjà le fichier `composer.json`, et juste après, il installera le Framework Nette lui-même. La seule chose qui reste à faire est de [vérifier les droits d'écriture |nette:troubleshooting#setting-directory-permissions] sur les répertoires `temp/` et `log/` et vous êtes prêt à partir.

Si vous connaissez la version de PHP sur laquelle le projet sera hébergé, assurez-vous de la [configurer |#PHP Version].


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

Composer installe toujours les versions des paquets compatibles avec la version de PHP que vous utilisez actuellement (ou plutôt, la version de PHP utilisée en ligne de commande lorsque vous lancez Composer). Ce qui n'est probablement pas la même version que celle utilisée par votre hébergeur. C'est pourquoi il est très important d'ajouter l'information sur la version de PHP de votre hébergement dans votre fichier `composer.json`. Ensuite, seules les versions des paquets compatibles avec l'hébergeur seront installées.

Par exemple, pour configurer le projet pour qu'il fonctionne avec PHP 8.2.3, utilisez la commande :

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

C'est ainsi que la version est écrite dans le fichier `composer.json`:

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

Cependant, le numéro de version de PHP est également indiqué ailleurs dans le fichier, dans la section `require`. Alors que le premier numéro spécifie la version pour laquelle les paquets seront installés, le second numéro indique la version pour laquelle l'application elle-même est écrite.
(Bien sûr, il n'y a pas de sens à ce que ces versions soient différentes, donc la double entrée est une redondance). Vous 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 .[#toc-ignoring-php-version]
======================================================

Les paquets spécifient généralement la version la plus basse de PHP avec laquelle ils sont compatibles et la version la plus haute avec laquelle ils ont été testés. Si vous prévoyez d'utiliser une version plus récente de PHP, peut-être à des fins de test, Composer refusera d'installer un tel paquet. La solution est d'utiliser l'option `--ignore-platform-req=php+`, qui permet à Composer d'ignorer les limites supérieures de la version de PHP requise.


Faux rapports .[#toc-false-reports]
===================================

Lors de la mise à niveau de paquets ou du changement de numéro de version, des conflits se produisent. Un paquet a des exigences qui entrent en conflit avec un autre, et ainsi de suite. Cependant, Composer imprime parfois un faux message. Il signale un conflit qui n'existe pas réellement. Dans ce cas, il est utile de supprimer le fichier `composer.lock` et de réessayer.

Si le message d'erreur persiste, c'est qu'il est sérieux et que vous devez y lire ce qu'il faut modifier et comment.


Packagist.org - Dépôt global .[#toc-packagist-org-global-repository]
====================================================================

[Packagist |https://packagist.org] est le dépôt de paquets principal, dans lequel Composer tente de rechercher des paquets, sauf indication contraire. Vous pouvez également y publier vos propres paquets.


Et si nous ne voulons pas du dépôt central ? .[#toc-what-if-we-don-t-want-the-central-repository]
-------------------------------------------------------------------------------------------------

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

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


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

Une caractéristique clé de Composer est qu'il fournit un chargement automatique pour toutes les classes qu'il installe, ce que vous commencez par inclure un fichier `vendor/autoload.php`.

Toutefois, il est également possible d'utiliser Composer pour charger d'autres classes en dehors du dossier `vendor`. La première option consiste à laisser Composer analyser les dossiers et sous-dossiers définis, trouver toutes les classes et les inclure dans l'autochargeur. Pour ce faire, définissez `autoload > classmap` dans `composer.json`:

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

Par la suite, il est nécessaire d'exécuter la commande `composer dumpautoload` à chaque modification et de laisser les tables d'autoloadage se régénérer. Ceci est extrêmement gênant, et il est de loin préférable de confier cette tâche à [RobotLoader |robot-loader:], qui effectue la même activité automatiquement en arrière-plan et beaucoup plus rapidement.

La deuxième option consiste à suivre le [système PSR-4 |https://www.php-fig.org/psr/psr-4/]. Pour faire simple, il s'agit d'un système où les espaces de noms et les noms de classes correspondent à la structure des répertoires et aux noms de fichiers, c'est-à-dire que `App\Core\RouterFactory` est situé dans le fichier `/path/to/App/Core/RouterFactory.php`. Exemple de configuration :

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

Voir la [documentation de Composer |https://getcomposer.org/doc/04-schema.md#psr-4] pour savoir exactement comment configurer ce comportement.


Test des nouvelles versions .[#toc-testing-new-versions]
========================================================

Vous voulez tester une nouvelle version de développement d'un paquet. Comment faire ? Tout d'abord, ajoutez cette paire d'options au fichier `composer.json`, qui vous permettra d'installer des versions de développement de paquets, mais ne le fera que s'il n'existe aucune combinaison de versions stables répondant aux exigences :

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

Nous vous recommandons également de supprimer le fichier `composer.lock`, car il arrive que Composer refuse de manière incompréhensible de procéder à l'installation et cela résoudra le problème.

Disons que le paquet est `nette/utils` et que la nouvelle version est 4.0. Vous l'installez avec la commande :

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

Ou vous pouvez installer une version spécifique, par exemple 4.0.0-RC2 :

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

Si un autre paquet dépend de la bibliothèque et est verrouillé sur une version plus ancienne (par exemple `^3.1`), il est idéal de mettre à jour le paquet pour qu'il fonctionne avec la nouvelle version.
Toutefois, si vous souhaitez simplement contourner la limitation et forcer Composer à installer la version de développement en prétendant qu'il s'agit d'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 .[#toc-calling-commands]
==============================================

Vous pouvez appeler vos propres commandes et scripts personnalisés via Composer comme s'il s'agissait de commandes Composer natives. Les scripts situés dans le dossier `vendor/bin` n'ont pas besoin de spécifier ce dossier.

À titre d'exemple, nous définissons un script dans le dossier `composer.json` qui utilise [Nette Tester |tester:] pour exécuter des tests :

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

Nous exécutons ensuite les tests avec `composer tester`. Nous pouvons appeler la commande même si nous ne sommes pas dans le dossier racine du projet, mais dans un sous-répertoire.


Envoyer Merci .[#toc-send-thanks]
=================================

Nous allons vous montrer une astuce qui va rendre les auteurs de logiciels libres heureux. Vous pouvez facilement donner une étoile sur GitHub aux bibliothèques que votre projet utilise. Il suffit d'installer la bibliothèque `symfony/thanks`:

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

Et puis exécutez :

```shell
composer thanks
```

Essayez !


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

Composer est étroitement intégré à l'outil de contrôle de version [Git |https://git-scm.com]. Si vous n'utilisez pas Git, il est nécessaire de l'indiquer à Composer :

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

{{sitename: Meilleures pratiques}}