Understand Composer Versions and Constraints

Version: In the sense of a version control system, a "version" is a specific set of files that contain specific data. Version follow the format of X.Y.Z or vX.Y.Z with an optional suffix of -dev, -patch, -alpha, -beta or -RC. The patch, alpha, beta and RC suffixes can also be followed by a number. Example: 1.0.0-dev, 1.0.0-alpha3, 1.0.0-beta2 and 1.0.0-RC5

Tags: Normally, Composer deals with tags (as opposed to branches. When you write a version constraint, it may reference a specific tag (e.g., 1.1) or it may reference a valid range of tags (e.g., >=1.1 <2.0, or ~4.0). 

Branches: If you want Composer to check out a branch instead of a tag, you need to point it to the branch using the special dev-* prefix (or sometimes suffix),  Example: dev-{branchname}.

Writing Version Constraints

Exact Version Constraint: You can specify the exact version of a package. This will tell Composer to install this version and this version only. Example: 3.7.0

Version Range: By using comparison operators you can specify ranges of valid versions. Valid operators are >, >=, <, <=, !=.

You can define multiple ranges. Ranges separated by a space ( ) or comma (,) will be treated as a logical AND. A double pipe (||) will be treated as a logical OR. AND has higher precedence than OR.

Examples:

• >=1.0
• >=1.0 <2.0
• >=1.0 <1.1 || >=1.2

Hyphenated Version Range ( - ): Inclusive set of versions. Partial versions on the right include are completed with a wildcard. For example 1.0 - 2.0 is equivalent to >=1.0.0 <2.1 as the 2.0 becomes 2.0.*. On the other hand 1.0.0 - 2.1.0 is equivalent to >=1.0.0 <=2.1.0. Example: 1.0 - 2.0

Wildcard Version Range (.*): You can specify a pattern with a * wildcard. 1.0.* is the equivalent of >=1.0 <1.1. Example: 1.0.*

Next Significant release

Tilde Version Range (~): The ~ operator is best explained by example: ~1.2 is equivalent to >=1.2 <2.0.0, while ~1.2.3 is equivalent to >=1.2.3 <1.3.0. 

Caret Version Range (^): The ^ operator behaves very similarly, but it sticks closer to semantic versioning, and will always allow non-breaking updates. For example ^1.2.3 is equivalent to >=1.2.3 <2.0.0 as none of the releases until 2.0 should break backwards compatibility. For pre-1.0 versions it also acts with safety in mind and treats ^0.3 as >=0.3.0 <0.4.0. This is the recommended operator for maximum interoperability when writing library code. Example: ^1.2.3 

Stability Constraints

If you are using a constraint that does not explicitly define a stability, Composer will default internally to -dev or -stable, depending on the operator(s) used. This happens transparently.

If you wish to explicitly consider only the stable release in the comparison, add the suffix -stable.

Example:

Testing Version Constraints

You can test version constraints using semver.mwl.be. Fill in a package name and it will autofill the default version constraint which Composer would add to your composer.json file. You can adjust the version constraint and the tool will highlight all releases that match.