Installer et utiliser composer sous Linux

Article posté le 03-11-2014 dans la catégorie Linux

Article mis à jour le : 05-05-2022

Petit tutoriel pour expliquer comment installer le gestionnaire de paquets composer sous Linux

Plus besoin de présenter composer : il s'agit du gestionnaire de paquet de PHP le plus utilisé. Le but de ce petit tutoriel est de vous expliquer comment l'installer sous Linux, ainsi que son utilisation basique.

1 - Installation de composer

Il y a trois façons de procéder. Deux d'entre-elles nécessitent PHP.

La première: ouvrez la console, et copions composer.phar, le fichier de composer :

La deuxième, toujours dans la console:

Troisième méthode: télécharger l'installer sur le site de composer. Ensuite positionnez vous, avec la console, sur le répertoire où se trouve l'installer, et faites :

A présent que vous avez installé composer, copions-le à présent dans /user/local/bin afin de pouvoir y accéder depuis tout le système :

Pour vérifier que tout c'est bien passé, ouvrez une nouvelle console , et tapez :

Vous aurez alors la version de votre installation de composer!

Note : il se peut que vous ayez aussi besoin de Git pour certains bundles que vous souhaiterez installer plus tard via composer. L'installation de Git est simplissime :

 

2 - Mettre à jour composer

La mise à jour de composer s'effectue simplement, via cette commande :

 

3 - Gestion du projet: installation, création et mise à jour

3-1 Installation des dépendances ou création d'un projet

Quand vous téléchargez un projet, vous ne téléchargez en général, pour des raisons de poids et de cohérence, que son squelette: il s'agit uniquement des fichiers de ce projet. Il manque tout ce qui est encombrant: les dépendances. Normal, ce sont des projets tiers, cela ne nous concerne pas.

Un projet utilisant composer dispose ainsi à minima d'un fichier listant les dépendances du projet: composer.json. Pour les télécharger et ainsi pouvoir utiliser ce projet, rien de plus simple:

Voilà, les dépendans sont installées. Cependant, comme vous pourrez le constater, il y a aussi, souvent, un fichier composer.lock à la racine de certains projets. Explications...

1. Le fichier composer.json est une liste présentant les dépendances requises, avec des contraintes de version ;
2. le composer.lock lui est un contrat de verrouillage précis, créée à partir du composer.json.

Allons plus en détails.

En effet, de votre côté, quand vous créez un projet, vous pourrez aussi avoir à versionner un fichier composer.lock. Celui-ci aura pour objectif de gérer les dependances ainsi que leur version de référence, une sorte de guide plus précis que le composer.json. Alors que le fichier .json ne contient lui que leur nom et demande une version peu précise de celles requises pour votre projet (par exemple je veux la librairie toto/titi en version 1.x) le .lock lui doit contenir la version exacte, leur checksum, les dépendances des dépendances...

Avant d'aller plus loin, voici ce que vous devez retenir :

• si vous créez un projet à partager (une librairie), votre projet ne doit contenir qu'un composer.json. C'est le projet qui utilisera votre librairie qui aura un .lock ;
• si vous créez un projet, par exemple un site web, qui n'est pas utilisable comme librairie d'un autre projet, vous devez avoir un composer.json et un composer.lock. C'est lui le projet "parent", qui contrôle les versions qu'il utilise. La commande composer install va parser tous les composer.json des lbrairies pour essayer de trouver la bonne version de chaque dépendance (et des dépendances des dépendances) pour pouvoir faire marcher le projet.

Pour bien comprendre, voici ce que fait la commande composer install:

• vérifie si un fichier .lock existe ;
• si ce n'est pas le cas: elle fait un composer update (voir plus bas) et en crée un, le remplissant avec les informations détaillés sur ce qu'il a récupéré ;
• si c'est le cas: elle télécharge les dépendances, dans leur version précise telle que décrite dans le .lock !

Exemple d'application: supprimez votre dossier vendor, faire un composer install à nouveau: il va télécharger tout ce qui est précisé dans le .lock.

Pour plus d'infos sur comment créer un projet utilisant composer, je vous laisse regarder la dock qui est assez claire.

Rappellez-vous d'une chose, en général, les commandes composer vous permettent de tout faire. Vous avez rarement besoin de toucher manuellement les fichiers .lock et .json.

3-2 Ajout d'une dépendance

composer require vendor/module

Attention cependant: certains packages ne doivent être installés que dans des environnements de développement (donc pas en production). C'est le cas de PHPUnit par exemple. Pour faire cela, vous avez juste à passer un paramètre à votre commande :  --dev. Exemple:

Sachez que plus tard, si vous faites un simple composer install, composer regardera si vous avez une variable d'environnement pour savoir si vous êtes en mode production ou développement et donc savoir si il peut installer ou non ces dépendances utiles uniquement en mode développement. Si vous avez un doute en production, vous pouvez toujours faire :

 Plus d'infos ici.

3-3 Mise à jour de librairies

Je viens de parler de la commande update. Vous devinez qu'il s'agit de la mise à jour du projet. Ce n'est pas aussi simple. Voici ce qu'elle fait:

• vérifie le fichier .json (le strict minimum qui doit être présent, nous l'avons dit) ;
• télécharge la dernière version des dépendances listées tout en respectant le cadre demandé. Ainsi, pour la librairie toto/titi que vous demandez en 1.x dans le .json, composer téléchargera la 1.6 car c'est la version la plus récente, mais ne téléchargera pas le 2.0 car elle ne respecte pas votre demande ;
• met à jour le fichier .lock.

A présent, vous comprenez qu'un update ne doit pas être fait à la légère! Ou alors, faites le que pour une seule dépendance bien précise! Le fichier .lock étant aussi géré dans votre gestionnaire de version (SVN, Git...), cela signifie que si vous faites un update sans vous concertez, vous risquez de vous retrouvez tous avec une version de dépendance non validée par l'équipe. Le fichier .lock sert donc de base sur les versions précises requises! 

composer update vendor/module est donc la bonne pratique pour ne mettre à jour qu'une seule dépendance. On peut même préciser la version souhaitée.

4 - Quelques commandes et infos utiles 

Mettre à jour qu'une seule dépendance (possible de préciser la version)

Fichier lock plus à jour

Cette commande update peut aussi être utilisée dans une variante afin de mettre à jour votre .lock à partir de votre .json, notamment quand vous avez ce message:

Remarquez que ceci peut être aussi provoqué par une modification volontaire et manuelle de votre .lock (dangereux), ou même un espace en trop, bref n'importe quoi qui altererait le checksum de votre .json. Pour régler le problème:

Cette commande sert notamment à regénerer le fichier composer.lock après résolu un conflit dedans.

Ajouter une dépendance, et préciser la version ou la branche

Note: si vous ne précisez pas la version: composer prendra automatiquement la dernière version stable

Note 2: vous pouvez donc préciser ce que vous voulez comme version mais également jusqu'où vous voulez aller, en utilisant les caractères ~ et ^. Exemple:

~1.2 signifie que vous voulez une version >=1.2 et < 2.0.0

~1.2.3 signifie que vous voulez une version >=1.2 et < 1.3.0

Toutefois l'utilisation du caractère ^ est recommandée: ^1.2.3 signifie une version >=1.2. et < 2.0

Voici quelques exemples :

Autre exemple dans un autre projet avec le meme composant:

Autre exemple en json: "vendorname/my-bundle": "^1.27", accepte toutes les versions 1.x

Le mieux est de citer la doc qui explique bien pourquoi c'est recommandé d'utiliser ^ plutôt que ~ :

Une information importante : par défaut composer va utiliser la branche master du projet. Si vous voulez utiliser une branche précise (ci-dessous, le nom de la branche est 2.0-working-branch ):

Ajouter toutes les dépendances d'un vendor

Retirer un module

Créer un projet à partir d'un dépôt

 

Installation en production avec optimisation l'autoload

Exécuter composer dans un autre répertoire

Exemple: 

Vider le cache

ou juste celui de quelques packages en particuloer:

Un petit bilan des commandes

Un internaute bien intentionné a créé une page qui récapitule bien la plupart des commandes de composer.

5 - Erreurs lors de l'installation

Note : Parmi les erreurs fréquemement rencontrées, voici les deux principales et leur solution :

• curl manquant : il vous suffit d'installer curl avec cette commande : apt-get install php5-curl
• Plus de mémoire : Si vous utilisez une VM, augmentez la mémoire allouée. Sous Linux, vous pouvez aussi activer le swap. Cela règlera le problème. Sinon, vous pouvez simplement lancer composer avec la commande PHP pour demander de ne pas mettre de limite de mémoire :

Plus globalement, après l'installation de composer, vous pouvez effectuer un diagnostic de votre installation avec cette commande :

6- Fichier où sont stockées d'éventuels identifiants composer pour des dépôts privés

Exemple de contenu du fichier:

7- Créer une dépendance installable via composer

Une fois que votre repository git dédié à votre module est créé, vous pouvez travailler directement en l'intégrant dans un "vrai projet" pour faire vos tests. Exemple d'un module my-bundle, que vous développez. Vous voulez travailler avec la branche 2.0-working-branch mais dans le cadre d'un projet existant, pour tester son intégration. Voici ce que vous devez taper dans le dit projet:

En allant dans vendor/vendorname, vous trouverez votre bundle avec son dépôt git, vous permettant ainsi de travailler directement dedans et évitez les aller retours.

Note: depuis un dépôt GitHub, j'ai du utiliser cette commande:

(develop étant le nom de la branche).

A noter aussi que parfois, il faut supprimer le dossier de la librairie dans vendor et recommencer pour que cela marche.