Composer : Conseils d'utilisation

Installation

Composer est un fichier .phar exécutable que vous téléchargez et installez de la manière suivante :

Windows

Utilisez l'installeur officiel Composer-Setup.exe.

Linux, macOS

Il suffit de 4 commandes que vous copiez depuis cette page.

Ensuite, en le plaçant dans un dossier qui se trouve dans le PATH système, Composer devient accessible globalement :

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

Utilisation dans un projet

Pour pouvoir commencer à utiliser Composer dans votre projet, vous n'avez besoin que du fichier composer.json. Celui-ci décrit les dépendances de notre projet et peut également contenir d'autres métadonnées. Un composer.json de base peut donc ressembler à ceci :

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

Nous indiquons ici que notre application (ou bibliothèque) nécessite le paquet nette/database (le nom du paquet se compose du nom de l'organisation et du nom du projet) et veut une version qui correspond à la contrainte ^3.0 (c'est-à-dire la dernière version 3).

Nous avons donc à la racine du projet le fichier composer.json et nous lançons l'installation :

composer update

Composer téléchargera Nette Database dans le dossier vendor/. Il créera également le fichier composer.lock, qui contient des informations sur les versions exactes des bibliothèques qu'il a installées.

Composer génère le fichier vendor/autoload.php, que nous pouvons simplement inclure et commencer à utiliser les bibliothèques sans aucun travail supplémentaire :

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

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

Mise à jour des paquets vers les dernières versions

La mise à jour des bibliothèques utilisées vers les dernières versions selon les contraintes définies dans composer.json est gérée par la commande composer update. Par exemple, pour 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 dans le fichier composer.json, par exemple vers "nette/database": "^4.1", afin de pouvoir 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 lister dans la ligne de commande, par ex. :

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

Ce qui n'est pas pratique. Utilisez donc le script simple Composer Frontline, qui le fera pour vous :

php composer-frontline.php

Création d'un nouveau projet

Vous créez un nouveau projet Nette à l'aide d'une seule commande :

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

Comme nom-du-projet, insérez le nom du répertoire pour votre projet et confirmez. Composer téléchargera le dépôt nette/web-project depuis GitHub, qui contient déjà le fichier composer.json, puis Nette Framework. Il devrait suffire de définir les permissions d'écriture sur les dossiers temp/ et log/ et le projet devrait prendre vie.

Si vous savez sur quelle version de PHP le projet sera hébergé, n'oubliez pas de la définir.

Version de PHP

Composer installe toujours les versions de paquets compatibles avec la version de PHP que vous utilisez actuellement (plus précisément, avec la version de PHP utilisée dans la ligne de commande lors de l'exécution de Composer). Ce qui n'est probablement pas la même version que celle utilisée par votre hébergement. C'est pourquoi il est très important d'ajouter au fichier composer.json l'information sur la version de PHP sur l'hébergement. Ensuite, seules les versions de paquets compatibles avec l'hébergement seront installées.

Le fait que le projet fonctionnera par exemple sur PHP 8.2.3 est défini par la commande :

composer config platform.php 8.2.3

La version est ainsi écrite dans le fichier composer.json :

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

Cependant, le numéro de version de PHP est indiqué à un autre endroit du fichier, dans la section require. Alors que le premier numéro détermine pour quelle version les paquets seront installés, le second numéro indique pour quelle version l'application elle-même est écrite. Et selon lui, par exemple, PhpStorm définit le niveau de langage PHP. (Bien sûr, il n'est pas logique que ces versions diffèrent, donc la double écriture est une imperfection.) Vous définissez cette version avec la commande :

composer require php 8.2.3 --no-update

Ou directement dans le fichier composer.json :

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

Ignorer la version de PHP

Les paquets indiquent généralement à la fois la version minimale de PHP avec laquelle ils sont compatibles et la version maximale avec laquelle ils sont testés. Si vous prévoyez d'utiliser une version de PHP encore plus récente, par exemple à des fins de test, Composer refusera d'installer un tel paquet. La solution est l'option --ignore-platform-req=php+, qui fait que Composer ignorera les limites supérieures de la version de PHP requise.

Faux rapports

Lors de la mise à niveau des paquets ou des changements de numéros de version, il arrive qu'un conflit se produise. Un paquet a des exigences qui sont en conflit avec un autre, etc. Mais Composer affiche parfois un faux rapport. 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, alors il est sérieux et il faut en déduire quoi et comment modifier.

Packagist.org – dépôt central

Packagist est le dépôt principal dans lequel Composer essaie de rechercher des paquets, sauf indication contraire. Nous pouvons y publier nos propres paquets.

Et si nous ne voulons pas utiliser le dépôt central ?

Si nous avons des applications internes à l'entreprise que nous ne pouvons tout simplement pas héberger publiquement, nous créons pour elles un dépôt d'entreprise.

Plus d'informations sur le sujet des dépôts dans la documentation officielle.

Autoloading

Une caractéristique essentielle de Composer est qu'il fournit l'autoloading pour toutes les classes qu'il a installées, que vous démarrez en incluant le fichier vendor/autoload.php.

Cependant, il est possible d'utiliser Composer également pour charger d'autres classes en dehors du dossier vendor. La première option est de laisser Composer parcourir les dossiers et sous-dossiers définis, trouver toutes les classes et les inclure dans l'autoloader. Vous obtenez cela en définissant autoload > classmap dans composer.json :

{
	"autoload": {
		"classmap": [
			"src/",      #  inclut le dossier src/ et ses sous-dossiers
		]
	}
}

Ensuite, il est nécessaire, à chaque modification, d'exécuter la commande composer dumpautoload et de laisser les tables d'autoloading se régénérer. C'est extrêmement inconfortable et il est bien préférable de confier cette tâche à RobotLoader, qui effectue la même activité automatiquement en arrière-plan et beaucoup plus rapidement.

La deuxième option est de respecter PSR-4. En termes simples, 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, donc par ex. App\Core\RouterFactory sera dans le fichier /chemin/vers/App/Core/RouterFactory.php. Exemple de configuration :

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

Comment configurer précisément le comportement est expliqué dans la documentation de Composer.

Test de nouvelles 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 permettra d'installer les versions de développement des paquets, mais n'y recourra que s'il n'existe aucune combinaison de versions stables qui satisferait aux exigences :

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

Ensuite, nous recommandons de supprimer le fichier composer.lock, parfois Composer refuse inexplicablement l'installation et cela résout le problème.

Supposons qu'il s'agisse du paquet nette/utils et que la nouvelle version porte le numéro 4.0. Vous l'installez avec la commande :

composer require nette/utils:4.0.x-dev

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

composer require nette/utils:4.0.0-RC2

Mais si un autre paquet dépend de la bibliothèque et est verrouillé sur une version plus ancienne (par ex. ^3.1), alors il est idéal de mettre à jour le paquet pour qu'il fonctionne avec la nouvelle version. Cependant, si vous voulez simplement contourner la restriction et forcer Composer à installer la version de développement et prétendre qu'il s'agit d'une version plus ancienne (par ex. 3.1.6), vous pouvez utiliser le mot-clé as :

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

Appel de commandes

Via Composer, il est possible d'appeler des commandes et des scripts personnalisés prédéfinis, comme s'il s'agissait de commandes natives de Composer. Pour les scripts qui se trouvent dans le dossier vendor/bin, il n'est pas nécessaire de spécifier ce dossier.

Comme exemple, définissons dans le fichier composer.json un script qui utilise Nette Tester pour lancer les tests :

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

Nous lançons ensuite les tests à l'aide de composer tester. Nous pouvons appeler la commande même si nous ne sommes pas dans le dossier racine du projet, mais dans l'un des sous-répertoires.

Envoyez un merci

Nous allons vous montrer une astuce qui fera plaisir aux auteurs open source. Vous pouvez facilement donner une étoile sur GitHub aux bibliothèques que votre projet utilise. Il suffit d'installer la bibliothèque symfony/thanks :

composer global require symfony/thanks

Et ensuite exécuter :

composer thanks

Essayez !

Configuration

Composer est étroitement lié à l'outil de versionnement Git. Si vous ne l'avez pas installé, il faut dire à Composer de ne pas l'utiliser :

composer -g config preferred-install dist