Contents
Après avoir abordé les règles et contraintes sémantiques des versions dans un précédent article, voyons comment définir ses dépendances avec Composer.
Patterns de contrainte
Composer propose un système de pattern pour définir les contraintes de version des dépendances incluses dans un projet. Cela permet de contrôler précisément quelle version sera loadée par Composer. Ce système est basé sur SemVer (tel que vu dans le précédent article).
La liste de dépendances apparaît dans le fichier de config composer.json de votre projet, sous les propriétés require et require-dev.
1 2 3 4 5 | { "require": { "vendor/package": "2.11.0", } } |
Voici les principales règles de contrainte:
| Exact | 1.2.3 | Correspond à une version précise au patch près. |
| Wildcard | 1.2.* | Le « * » est un jocker qui peut correspondre à un range de versions. |
| Range | >=1.2.3 <2.0 || >2.2 | Correspond à un « range » logique de version. |
| Tilde | ~1.2 | Correspond à un range de version au niveau du dernier chiffre. Il indique donc la version minium sur son dernier chiffre, mais implique qu’on ne fasse pas de saut de version sur ses autres chiffres. Si vous précisez deux chiffres comme dans l’exemple, la version minimum est mineure (1.2.*), mais ne passera jamais sur une nouvelle version majeur (2.*). |
| Caret | ^1.2.3 | Assure la rétrocompatibilité comme le tilde, mais permet également de préciser une version de patch minimum. |
Il est conseillé d’utiliser la contrainte de version « ^ » (Caret Operator). En effet, cela permet de bénéficier la dernière version d’une librairie qui soit rétrocompatible.
Par défaut, Composer harmonise la version de la sorte (ou avec « ~ » jusqu’il y a peu) lorsque vous utilisez la commande require sans préciser la version demandée. Vous aurez ainsi la dernière version majeure avec une contrainte optimisée pour celle-ci.
1 | $ composer require vendor/package |
Enfin, Composer accepte également les suffixes de stabilité (ex: 1.0.1-alpha) et les noms de branches (ex: dev-master).
Contraintes de stabilité
Si vous ne le demandez pas explicitement, Composer ne prendra pas en considération les versions non stables. Ainsi, si un projet possède une version avec un suffixe d’instabilité (ex: 1.0.1-alpha) ou s’il s’agit d’un nom de branche (ex: dev-master), celles-ci ne seront pas pris en compte lors de la résolution des contraintes.
Stabilité minimum
Ce comportement est défini par la configuration prefer-stable et et minimum-stability du fichier composer.json de votre projet.
Le paramètre prefer-stable (activé par défaut) indique simplement si Composer doit effectivement appliquer cette restriction.
Le paramètre minimum-stability (stable par défaut) spécifie quant à lui la stabilité minimum des dépendances à rechercher. Il agit comme un filtre. Composer ne recherchera que les versions au moins aussi stables (dev -> alpha -> beta -> RC -> stable). Par défaut, la valeur est stable, mais vous pouvez la redéfinir avec des valeurs comme dev, alpha, etc.
Si vous spécifier explicitement une version non-stable ou une branche dans vos contraintes de version, vous devez donc impérativement définir un minimum de stabilité qui soit au moins équivalent.
1 2 3 4 | { "minimum-stability": "dev", "vendor/package": "1.0.x-dev", } |
Notez enfin que toutes les dépendances seront affectées par cette valeur.
Flags de stabilité
Il faut savoir également qu’un système de stability flags (@alpha, @patch, etc) peut être spécifié dans la contrainte que vous définissez pour vos dépendances. Ces suffixes indiquent que vous désirez explicitement une version qui n’est pas encore stable et force la valeur globale de minimum-stability. Composer prendra donc le dernier commit en date qui corresponde à la contrainte.
1 2 3 4 5 6 7 | { "minimum-stability": "stable", "require": { "vendor/package": "1.0.*@dev", "vendor/package": "@dev", } } |
Enfin, il est possible de préciser un hash précis de commit pour les versions de dev.
1 2 3 4 5 6 7 | { "minimum-stability": "dev", "require": { "vendor/package": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7", "vendor/package": "1.0.x-dev#2eb0c0978d290a1c45346a1955188929cb4e5db7", } } |
Conclusion
Composer a instauré un système de contraintes basé sur SemVer qui permet un large panel de possibilités.
Une fois la version définie, encore faut-il loader et updater correctement sa dépendance, voire résoudre les conflits. C’est ce que nous verrons prochainement dans un article.
Haaaa cool, un peu de lecture pour ce soir.
Ping : Comment manager les versions de dépendance avec Composer?