Download the PHP package z4kn4fein/php-semver without Composer

php-semver

Semantic Versioning library for PHP. It implements the full semantic version 2.0.0 specification and provides ability to parse, compare, and increment semantic versions along with validation against constraints.

Requirements

Install with Composer

Usage

The following options are supported to construct a Version:

1. Building part by part with Version::create().

2. Parsing from a string with Version::parse() or Version::parseOrNull().

The following information is accessible on a constructed Version object:

Strict vs. Loose Parsing

By default, the version parser considers partial versions like 1.0 and versions starting with the v prefix invalid. This behaviour can be turned off by setting the strict parameter to false.

Compare

It is possible to compare two Version objects with the following comparison methods.

Sort

Version::sort() and Version::sortString() are available to sort an array of versions.

You might want to sort in reverse order, then you can use Version::rsort() or Version::rsortString().

Version::compare() and Version::compareString() methods also can be used as callback for usort() to sort an array of versions.

Constraints

With constraints, it's possible to validate whether a version satisfies a set of rules or not. A constraint can be described as one or more conditions combined with logical OR and AND operators.

Conditions

Conditions are usually composed of a comparison operator and a version like >=1.2.0. The condition >=1.2.0 would be met by any version that greater than or equal to 1.2.0.

Supported comparison operators:

• = Equal (equivalent to no operator: 1.2.0 means =1.2.0)
• != Not equal
• < Less than
• <= Less than or equal
• > Greater than
• >= Greater than or equal

Conditions can be joined together with whitespace, representing the AND logical operator between them. The OR operator can be expressed with || or | between condition sets.

For example, the constraint >=1.2.0 <3.0.0 || >4.0.0 translates to: Only those versions are allowed that are either greater than or equal to 1.2.0 {AND} less than 3.0.0 {OR} greater than 4.0.0.

We can notice that the first part of the previous constraint (>=1.2.0 <3.0.0) is a simple semantic version range. There are more ways to express version ranges; the following section will go through all the available options.

Range Conditions

There are particular range indicators which are sugars for more extended range expressions.

• X-Range: The x, X, and * characters can be used as a wildcard for the numeric parts of a version.

  • 1.2.x translates to >=1.2.0 <1.3.0-0
  • 1.x translates to >=1.0.0 <2.0.0-0
  • * translates to >=0.0.0

  In partial version expressions, the missing numbers are treated as wildcards.

  • 1.2 means 1.2.x which finally translates to >=1.2.0 <1.3.0-0
  • 1 means 1.x or 1.x.x which finally translates to >=1.0.0 <2.0.0-0

• Hyphen Range: Describes an inclusive version range. Wildcards are evaluated and taken into account in the final range.

  • 1.0.0 - 1.2.0 translates to >=1.0.0 <=1.2.0
  • 1.1 - 1.4.0 means >=(>=1.1.0 <1.2.0-0) <=1.4.0 which finally translates to >=1.1.0 <=1.4.0
  • 1.1.0 - 2 means >=1.1.0 <=(>=2.0.0 <3.0.0-0) which finally translates to >=1.1.0 <3.0.0-0

• Tilde Range (~): Describes a patch level range when the minor version is specified or a minor level range when it's not.

  • ~1.0.1 translates to >=1.0.1 <1.1.0-0
  • ~1.0 translates to >=1.0.0 <1.1.0-0
  • ~1 translates to >=1.0.0 <2.0.0-0
  • ~1.0.0-alpha.1 translates to >=1.0.1-alpha.1 <1.1.0-0
• Caret Range (^): Describes a range with regard to the most left non-zero part of the version.
  • ^1.1.2 translates to >=1.1.2 <2.0.0-0
  • ^0.1.2 translates to >=0.1.2 <0.2.0-0
  • ^0.0.2 translates to >=0.0.2 <0.0.3-0
  • ^1.2 translates to >=1.2.0 <2.0.0-0
  • ^1 translates to >=1.0.0 <2.0.0-0
  • ^0.1.2-alpha.1 translates to >=0.1.2-alpha.1 <0.2.0-0

Validation

Let's see how we can determine whether a version satisfies a constraint or not.

Increment

Version objects can produce incremented versions of themselves with the getNext{Major|Minor|Patch|PreRelease}Version methods. These methods can be used to determine the next version in order incremented by the according part. Version objects are immutable, so each incrementing function creates a new Version.

This example shows how the incrementation works on a stable version:

In case of an unstable version:

Each incrementing function provides the option to set a pre-release identity on the incremented version.

Copy

It's possible to make a copy of a particular version with the copy() method. It allows altering the copied version's properties with optional parameters.

[!NOTE]\ Without setting any optional parameter, the copy() method will produce an exact copy of the original version.

Invalid version handling

When the version or constraint parsing fails due to an invalid format, the library throws a specific SemverException.

[!NOTE]\ The Version::parseOrNull() and Constraint::parseOrNull() methods can be used for exception-less conversions as they return null when the parsing fails.

Contact & Support

• Create an issue for bug reports and feature requests.
• Start a discussion for your questions and ideas.
• Add a ⭐️ to support the project!