Conseils d'utilisation du compositeur

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

Installation

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

Windows

Utilisez le programme d'installation officiel Composer-Setup.exe.

Linux, macOS

Tout ce dont vous avez besoin, c'est de 4 commandes, que vous pouvez copier à partir de cette page.

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

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

Utilisation dans le projet

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 :

{
	"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 :

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 :

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

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

Mise à jour des paquets vers les dernières 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 :

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 qui le fera pour vous :

php composer-frontline.php

Création d'un nouveau projet

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

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 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.

Version PHP

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 :

composer config platform.php 8.2.3

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

{
	"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 :

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 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

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

Packagist 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 ?

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.

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:

{
	"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, 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. 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\Router\RouterFactory est situé dans le fichier /path/to/App/Router/RouterFactory.php. Exemple de configuration :

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

Voir la documentation de Composer pour savoir exactement comment configurer ce comportement.

Test des 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 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 :

{
	"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 :

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

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:

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

Appeler des commandes

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 pour exécuter des tests :

{
	"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

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:

composer global require symfony/thanks

Et puis exécutez :

composer thanks

Essayez !

Configuration

Composer est étroitement intégré à l'outil de contrôle de version Git. Si vous n'utilisez pas Git, il est nécessaire de l'indiquer à Composer :

composer -g config preferred-install dist