php semver
v3.0.0
Bibliothèque de versioning sémantique pour PHP. Il implémente la spécification sémantique complète de la version 2.0.0 et offre la possibilité d' analyser , de comparer et d'incrémenter les versions sémantiques ainsi qu'une validation par rapport aux contraintes .
| Version | Version PHP |
|---|---|
>=1.0, <1.2 | >=5,5 |
>=1.2, <3.0 | >=7,1 |
>=3.0 | >=8,1 |
composer require z4kn4fein/php-semver Les options suivantes sont prises en charge pour construire une Version :
Construire partie par partie avec Version::create() .
Version:: create ( 3 , 5 , 2 , " alpha " , " build " ); Analyse d'une chaîne avec Version::parse() ou Version::parseOrNull() .
Version:: parse ( " 3.5.2-alpha+build " ); Les informations suivantes sont accessibles sur un objet Version construit :
<?php
use z4kn4fein SemVer Version ;
$ version = Version:: parse ( " 2.5.6-alpha.12+build.34 " );
echo $ version -> getMajor (); // 2
echo $ version -> getMinor (); // 5
echo $ version -> getPatch (); // 6
echo $ version -> getPreRelease (); // alpha.12
echo $ version -> getBuildMeta (); // build.34
echo $ version -> isPreRelease (); // true
echo $ version -> isStable (); // false
echo $ version -> withoutSuffixes (); // 2.5.6
echo $ version ; // 2.5.6-alpha.12+build.34 Par défaut, l'analyseur de version considère les versions partielles comme 1.0 et les versions commençant par le préfixe v comme invalides. Ce comportement peut être désactivé en définissant le paramètre strict sur false .
echo Version:: parse ( " v2.3-alpha " ); // exception
echo Version:: parse ( " 2.1 " ); // exception
echo Version:: parse ( " v3 " ); // exception
echo Version:: parse ( " v2.3-alpha " , false ); // 2.3.0-alpha
echo Version:: parse ( " 2.1 " , false ); // 2.1.0
echo Version:: parse ( " v3 " , false ); // 3.0.0 Il est possible de comparer deux objets Version avec les méthodes de comparaison suivantes.
<?php
use z4kn4fein SemVer Version ;
// with static methods
echo Version:: lessThan ( " 2.3.4 " , " 2.4.1 " ); // true
echo Version:: lessThanOrEqual ( " 2.4.1 " , " 2.4.1 " ); // true
echo Version:: greaterThan ( " 2.3.1-alpha.5 " , " 2.3.1-alpha.3 " ); // true
echo Version:: greaterThanOrEqual ( " 3.2.3 " , " 3.2.2 " ); // true
echo Version:: equal ( " 3.2.3 " , " 3.2.3+build.3 " ); // true
echo Version:: notEqual ( " 3.2.3 " , " 2.2.4 " ); // true
// compare() or compareString()
echo Version:: compare (Version:: parse ( " 2.3.4 " ), Version:: parse ( " 2.4.1 " )); // -1
echo Version:: compare (Version:: parse ( " 2.3.4 " ), Version:: parse ( " 2.3.4 " )); // 0
echo Version:: compare (Version:: parse ( " 2.3.4 " ), Version:: parse ( " 2.2.0 " )); // 1
echo Version:: compareString ( " 2.3.4 " , " 2.4.1 " ); // -1
echo Version:: compareString ( " 2.3.4 " , " 2.3.4 " ); // 0
echo Version:: compareString ( " 2.3.4 " , " 2.2.0 " ); // 1
// with instance methods
$ version = Version:: parse ( " 2.5.6-alpha.12+build.34 " );
echo $ version -> isLessThan (Version:: parse ( " 2.3.1 " )); // false
echo $ version -> isLessThanOrEqual (Version:: parse ( " 2.5.6-alpha.15 " )); // true
echo $ version -> isGreaterThan (Version:: parse ( " 2.5.6 " )); // false
echo $ version -> isLessThanOrEqual (Version:: parse ( " 2.5.6-alpha.12 " )); // true
echo $ version -> isEqual (Version:: parse ( " 2.5.6-alpha.12+build.56 " )); // true
echo $ version -> isNotEqual (Version:: parse ( " 2.2.4 " )); // true Version::sort() et Version::sortString() sont disponibles pour trier un tableau de versions.
<?php
use z4kn4fein SemVer Version ;
$ versions = array_map ( function ( string $ version ) {
return Version:: parse ( $ version );
}, [
" 1.0.1 " ,
" 1.0.1-alpha " ,
" 1.0.1-alpha.beta " ,
" 1.0.1-alpha.3 " ,
" 1.0.1-alpha.2 " ,
" 1.1.0 " ,
" 1.1.0+build " ,
]);
$ sorted = Version:: sort ( $ versions );
// The result:
// "1.0.1-alpha"
// "1.0.1-alpha.2"
// "1.0.1-alpha.3"
// "1.0.1-alpha.beta"
// "1.0.1"
// "1.1.0"
// "1.1.0+build" Vous souhaiterez peut-être trier dans l'ordre inverse, vous pouvez alors utiliser Version::rsort() ou Version::rsortString() .
<?php
use z4kn4fein SemVer Version ;
$ versions = array_map ( function ( string $ version ) {
return Version:: parse ( $ version );
}, [
" 1.0.1 " ,
" 1.0.1-alpha " ,
" 1.0.1-alpha.beta " ,
" 1.0.1-alpha.3 " ,
" 1.0.1-alpha.2 " ,
" 1.1.0 " ,
" 1.1.0+build " ,
]);
$ sorted = Version:: rsort ( $ versions );
// The result:
// "1.1.0"
// "1.1.0+build"
// "1.0.1"
// "1.0.1-alpha.beta"
// "1.0.1-alpha.3"
// "1.0.1-alpha.2"
// "1.0.1-alpha" Les méthodes Version::compare() et Version::compareString() peuvent également être utilisées comme rappel pour usort() pour trier un tableau de versions.
<?php
use z4kn4fein SemVer Version ;
$ versions = array_map ( function ( string $ version ) {
return Version:: parse ( $ version );
}, [
" 1.0.1 " ,
" 1.0.1-alpha " ,
" 1.0.1-alpha.beta " ,
" 1.0.1-alpha.3 " ,
" 1.0.1-alpha.2 " ,
" 1.1.0 " ,
" 1.1.0+build " ,
]);
usort ( $ versions , [ " z4kn4feinSemVerVersion " , " compare " ]);
// The result:
// "1.0.1-alpha"
// "1.0.1-alpha.2"
// "1.0.1-alpha.3"
// "1.0.1-alpha.beta"
// "1.0.1"
// "1.1.0"
// "1.1.0+build" Avec des contraintes, il est possible de valider si une version satisfait ou non à un ensemble de règles. Une contrainte peut être décrite comme une ou plusieurs conditions combinées avec des opérateurs logiques OR et AND .
Les conditions sont généralement composées d'un opérateur de comparaison et d'une version comme >=1.2.0 . La condition >=1.2.0 serait remplie par toute version supérieure ou égale à 1.2.0 .
Opérateurs de comparaison pris en charge :
= Égal (équivalent à aucun opérateur : 1.2.0 signifie =1.2.0 )!= Pas égal< Moins de<= Inférieur ou égal> Supérieur à>= Supérieur ou égal Les conditions peuvent être jointes par des espaces, représentant l'opérateur logique AND entre elles. L'opérateur OR peut être exprimé avec || ou | entre les ensembles de conditions.
Par exemple, la contrainte >=1.2.0 <3.0.0 || >4.0.0 se traduit par : Seules les versions supérieures ou égales à 1.2.0 { AND } inférieures à 3.0.0 { OR } supérieures à 4.0.0 sont autorisées .
On peut remarquer que la première partie de la contrainte précédente ( >=1.2.0 <3.0.0 ) est une simple plage de versions sémantiques. Il existe d'autres façons d'exprimer les plages de versions ; la section suivante passera en revue toutes les options disponibles.
Il existe des indicateurs de plage particuliers qui sont des sucres pour des expressions à plage plus étendue.
X-Range : Les caractères x , X et * peuvent être utilisés comme caractère générique pour les parties numériques d'une version.
1.2.x se traduit par >=1.2.0 <1.3.0-01.x se traduit par >=1.0.0 <2.0.0-0* se traduit par >=0.0.0Dans les expressions de version partielle, les nombres manquants sont traités comme des caractères génériques.
1.2 signifie 1.2.x , ce qui se traduit finalement par >=1.2.0 <1.3.0-01 signifie 1.x ou 1.xx , ce qui se traduit finalement par >=1.0.0 <2.0.0-0Plage de traits d'union : décrit une plage de versions inclusive. Les jokers sont évalués et pris en compte dans la fourchette finale.
1.0.0 - 1.2.0 se traduit par >=1.0.0 <=1.2.01.1 - 1.4.0 signifie >=(>=1.1.0 <1.2.0-0) <=1.4.0 ce qui se traduit finalement par >=1.1.0 <=1.4.01.1.0 - 2 signifie >=1.1.0 <=(>=2.0.0 <3.0.0-0) ce qui se traduit finalement par >=1.1.0 <3.0.0-0 Plage Tilde ( ~ ) : Décrit une plage de niveaux de correctifs lorsque la version mineure est spécifiée ou une plage de niveaux mineurs lorsqu'elle ne l'est pas.
~1.0.1 se traduit par >=1.0.1 <1.1.0-0~1.0 se traduit par >=1.0.0 <1.1.0-0~1 se traduit par >=1.0.0 <2.0.0-0~1.0.0-alpha.1 se traduit par >=1.0.1-alpha.1 <1.1.0-0 Caret Range ( ^ ) : Décrit une plage par rapport à la partie non nulle la plus à gauche de la version.
^1.1.2 se traduit par >=1.1.2 <2.0.0-0^0.1.2 se traduit par >=0.1.2 <0.2.0-0^0.0.2 se traduit par >=0.0.2 <0.0.3-0^1.2 se traduit par >=1.2.0 <2.0.0-0^1 se traduit par >=1.0.0 <2.0.0-0^0.1.2-alpha.1 se traduit par >=0.1.2-alpha.1 <0.2.0-0Voyons comment déterminer si une version satisfait ou non à une contrainte.
<?php
use z4kn4fein SemVer Version ;
use z4kn4fein SemVer Constraints Constraint ;
$ constraint = Constraint:: parse ( " >=1.2.0 " );
$ version = Version:: parse ( " 1.2.1 " );
echo $ version -> isSatisfying ( $ constraint ); // true
echo $ constraint -> isSatisfiedBy ( $ version ); // true
// Or using the static satisfies() method with strings:
echo Version:: satisfies ( " 1.2.1 " , " >=1.2.0 " ); // true Les objets Version peuvent produire des versions incrémentées d'eux-mêmes avec les méthodes getNext{Major|Minor|Patch|PreRelease}Version . Ces méthodes peuvent être utilisées pour déterminer la version suivante dans l'ordre incrémenté de la pièce correspondante. Les objets Version sont immuables , donc chaque fonction d'incrémentation crée une nouvelle Version .
Cet exemple montre comment fonctionne l'incrémentation sur une version stable :
<?php
use z4kn4fein SemVer Version ;
use z4kn4fein SemVer Inc ;
$ stableVersion = Version:: create ( 1 , 0 , 0 );
echo $ stableVersion -> getNextMajorVersion (); // 2.0.0
echo $ stableVersion -> getNextMinorVersion (); // 1.1.0
echo $ stableVersion -> getNextPatchVersion (); // 1.0.1
echo $ stableVersion -> getNextPreReleaseVersion (); // 1.0.1-0
// or with the inc() method:
echo $ stableVersion -> inc (Inc:: MAJOR ); // 2.0.0
echo $ stableVersion -> inc (Inc:: MINOR ); // 1.1.0
echo $ stableVersion -> inc (Inc:: PATCH ); // 1.0.1
echo $ stableVersion -> inc (Inc:: PRE_RELEASE ); // 1.0.1-0En cas de version instable :
<?php
use z4kn4fein SemVer Version ;
use z4kn4fein SemVer Inc ;
$ unstableVersion = Version:: parce ( " 1.0.0-alpha.2+build.1 " );
echo $ unstableVersion -> getNextMajorVersion (); // 2.0.0
echo $ unstableVersion -> getNextMinorVersion (); // 1.1.0
echo $ unstableVersion -> getNextPatchVersion (); // 1.0.0
echo $ unstableVersion -> getNextPreReleaseVersion (); // 1.0.0-alpha.3
// or with the inc() method:
echo $ unstableVersion -> inc (Inc:: MAJOR ); // 2.0.0
echo $ unstableVersion -> inc (Inc:: MINOR ); // 1.1.0
echo $ unstableVersion -> inc (Inc:: PATCH ); // 1.0.0
echo $ unstableVersion -> inc (Inc:: PRE_RELEASE ); // 1.0.0-alpha.3Chaque fonction d'incrémentation offre la possibilité de définir une identité préliminaire sur la version incrémentée.
<?php
use z4kn4fein SemVer Version ;
use z4kn4fein SemVer Inc ;
$ version = Version:: parce ( " 1.0.0-alpha.1 " );
echo $ version -> getNextMajorVersion ( " beta " ); // 2.0.0-beta
echo $ version -> getNextMinorVersion ( "" ); // 1.1.0-0
echo $ version -> getNextPatchVersion ( " alpha " ); // 1.0.1-alpha
echo $ version -> getNextPreReleaseVersion ( " alpha " ); // 1.0.0-alpha.2
// or with the inc() method:
echo $ version -> inc (Inc:: MAJOR , " beta " ); // 2.0.0-beta
echo $ version -> inc (Inc:: MINOR , "" ); // 1.1.0-0
echo $ version -> inc (Inc:: PATCH , " alpha " ); // 1.0.1-alpha
echo $ version -> inc (Inc:: PRE_RELEASE , " alpha " ); // 1.0.0-alpha.2 Il est possible de faire une copie d'une version particulière avec la méthode copy() . Il permet de modifier les propriétés de la version copiée avec des paramètres facultatifs.
$ version = Version:: parse ( " 1.0.0-alpha.2+build.1 " );
echo $ version -> copy (); // 1.0.0-alpha.2+build.1
echo $ version -> copy ( 3 ); // 3.0.0-alpha.2+build.1
echo $ version -> copy ( null , 4 ); // 1.4.0-alpha.2+build.1
echo $ version -> copy ( null , null , 5 ); // 1.0.5-alpha.2+build.1
echo $ version -> copy ( null , null , null , " alpha.4 " ); // 1.0.0-alpha.4+build.1
echo $ version -> copy ( null , null , null , null , " build.3 " ); // 1.0.0-alpha.2+build.3
echo $ version -> copy ( 3 , 4 , 5 ); // 3.4.5-alpha.2+build.1 Note
Sans définir de paramètre facultatif, la méthode copy() produira une copie exacte de la version originale.
Lorsque l'analyse de version ou de contrainte échoue en raison d'un format non valide, la bibliothèque renvoie une SemverException spécifique.
Note
Les méthodes Version::parseOrNull() et Constraint::parseOrNull() peuvent être utilisées pour des conversions sans exception car elles renvoient null lorsque l'analyse échoue.
