PHPackages                             mistralys/version-parser - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. mistralys/version-parser

ActiveLibrary[Utility & Helpers](/categories/utility)

mistralys/version-parser
========================

Class used to parse version numbers.

2.1.1(2y ago)156.9k↑18.2%2MITPHPPHP >=7.4

Since Sep 8Pushed 2y ago1 watchersCompare

[ Source](https://github.com/Mistralys/version-parser)[ Packagist](https://packagist.org/packages/mistralys/version-parser)[ RSS](/packages/mistralys-version-parser/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (5)Dependencies (3)Versions (6)Used By (2)

Version string parser for PHP
=============================

[](#version-string-parser-for-php)

PHP utility used to parse application version strings, and retrieve information on the version, as well as convert it to a numeric build number (float or integer). Supports release tags like alpha, beta and reelease candidate, as well as custom branch names.

Supported version strings
-------------------------

[](#supported-version-strings)

The parser expects versions to be in the following format:

`MajorVersion.MinorVersion.PatchVersion-BranchOrTag`

This allows the use of a wide range of version strings. Some examples:

- `1`
- `1.1`
- `1.1.5`
- `1.145.147`
- `1.1.5-rc1`
- `1.1.5-beta`
- `1.1.5-beta2`
- `1.1.5-beta.42`
- `1.1.5-BranchName`
- `1.1.5-BranchName-alpha2`
- `1.1.5 BranchName A2` *Spaces are allowed*
- `1.1.5 "Branch name"` *Quotes are stripped*
- `1.1.5 (BranchName) / Alpha 2` *Special characters are filtered out*
- `1.1.5-DEV Branch Name` *Branch names after the tag type*

Most special characters are filtered out, which means that it is very lenient in what is passed to it. After the version number, anything that is not a tag qualifier (`beta`, `alpha`, etc.) is considered the branch name.

Installation
------------

[](#installation)

Simply require the package with composer.

Via command line:

```
composer require mistralys/version-parser
```

Via composer.json:

```
{
    "require": {
      "mistralys/version-parser": "dev-master"
    }
}
```

Usage
-----

[](#usage)

### Getting individual version numbers

[](#getting-individual-version-numbers)

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2');

$major = $version->getMajorVersion(); // 1
$minor = $version->getMinorVersion(); // 5
$patch = $version->getPatchVersion(); // 2
```

### Getting a version without tag

[](#getting-a-version-without-tag)

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2-RC3');

$number = $version->getVersion(); // 1.5.2
```

The version is normalized to show all three levels, even if they were not specified.

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1');

$number = $version->getVersion(); // 1.0.0
```

### Getting a short version

[](#getting-a-short-version)

The method `getShortVersion()` retrieves a version string with the minimum possible levels.

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.0.0');

$number = $version->getVersion(); // 1
```

### Getting the full version, normalized

[](#getting-the-full-version-normalized)

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create("1.2.0 'Cool Release' RC5");

$normalized = $version->getTagVersion(); // 1.0.0-CoolRelease-rc5
```

> NOTE: The branch name is also normalized. Words are capitalized, and spaces are removed. Other special characters are preserved.

### Checking the tag type

[](#checking-the-tag-type)

To check the release type, the shorthand methods `isBeta()`, `isAlpha()`, etc. can be used. See "Supported release tags" for details.

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2-beta');

$isBeta = $version->isBeta(); // true
```

Alternatively, it is possible to check the tag type manually.

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2-beta5');

if($version->getTagType() === VersionParser::TAG_TYPE_BETA)
{
	// is a beta version
}
```

The tag info object that can be accessed with the `getTagInfo()`method goes more in depth.

For example, the method `getTagName()` will return the tag type exactly as used in the version string, whereas `getTagType()` will only return the long type variant (e.g. `beta` instead of `b`):

```
use Mistralys\VersionParser\VersionParser;

$tag = VersionParser::create('1.5.2-B2')->getTagInfo();

if($tag !== null)
{
    echo $tag->getTagName(); // b
    echo $tag->getTagType(); // beta
}
```

### Getting the tag number

[](#getting-the-tag-number)

When no number is added to the tag, it is assumed that it is the tag #1.

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2-beta');

$betaVersion = $version->getTagNumber(); // 1 (implicit)
```

With a number added:

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2-beta5');

$betaVersion = $version->getTagNumber(); // 5
```

### Getting the branch name

[](#getting-the-branch-name)

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2-Foobar');

$hasBranch = $version->hasBranch(); // true
$branchName = $version->getBranchName(); // Foobar
```

This also works in combination with a release tag:

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2-Foobar-RC1');

$hasBranch = $version->hasBranch(); // true
$branchName = $version->getBranchName(); // Foobar
```

Branch names may contain special characters. Quotes are filtered out:

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2 "Foobar/42"');

$hasBranch = $version->hasBranch(); // true
$branchName = $version->getBranchName(); // Foobar/42
```

### Setting the separator character

[](#setting-the-separator-character)

By default, the branch name and tag are separated with hyphens (`-`) when normalizing the version string. This can be adjusted to any character:

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2-BranchName-alpha5');

echo $version
    ->setSeparatorChar('_')
    ->getTagVersion();
```

Will output:

```
1.5.2_BranchName_alpha5

```

### Converting tag types to uppercase

[](#converting-tag-types-to-uppercase)

By default, tag types are converted to lowercase when normalizing the version string. They can be switched to uppercase instead:

```
use Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.5.2-BranchName-alpha5');

echo $version
    ->setTagUppercase()
    ->getTagVersion();
```

Will output:

```
1.5.2-BranchName-ALPHA5

```

Supported release tags
----------------------

[](#supported-release-tags)

The parser will handle the following tags automatically, and assign them a build number value:

- `dev` or `snapshot` - Development release, weight: `8`
- `alpha` - Alpha release, weight: `6`
- `beta` - Beta release, weight: `4`
- `rc` - Release candidate, weight: `2`
- `patch` - Patch/bugfix release, weight: `1`
- `stable` - Stable release, weight: `0`

This means that comparing the same version numbers with different release tags will work. For example, `1.4-beta` is considered a higher version than `1.4-alpha`, because `beta` has a lower weight than `alpha`.

### Numbering tags

[](#numbering-tags)

Also supported is numbering tagged versions:

- `1.0-alpha` - Implied `alpha1`
- `1.0-alpha2` - Alpha `2`

### Adding custom tags

[](#adding-custom-tags)

If you use other tag types in your application's version strings, they can be added so the parser recognizes them:

```
use Mistralys\VersionParser\VersionParser;

// The third parameter is the short variant of the tag type.
VersionParser::registerTagType('foobar', 5, 'f');

$version = VersionParser::create('1.0.5-foobar2');
$short = VersionParser::create('1.0.5-F2');

echo $version->getTagType(); // foobar
echo $short->getTagType(); // foobar
```

If you mix custom tag types and the standard ones, be careful with the sorting weight you set for them, so they will be weighted correctly. If needed, you can change the weight of the default types to make more room.

This for example resets the weights for some existing tag types, and inserts new ones:

```
use Mistralys\VersionParser\VersionParser;

$weight = 900; // Can be any number
VersionParser::registerTagType(VersionParser::TAG_TYPE_ALPHA, $weight--);
VersionParser::registerTagType(VersionParser::TAG_TYPE_BETA, $weight--);
VersionParser::registerTagType('foobar', $weight--);
VersionParser::registerTagType(VersionParser::TAG_TYPE_RELEASE_CANDIDATE, $weight--);
VersionParser::registerTagType('prefinal', $weight--);
```

> NOTE: The weights are used in the generated build numbers. Changing the default tag type weights will change their build numbers as well.

Build numbers
-------------

[](#build-numbers)

The version strings are intelligently converted to numbers, to allow comparisons and sorting. This includes the release tags like `alpha`or `beta`, which are converted as well. The result is a build number which can be either a floating point number, or an integer.

> NOTE: These numbers are not meant to be human-readable. Their sole purpose is to recognize version numbers programmatically.

There are two methods related to this:

```
use \Mistralys\VersionParser\VersionParser;

$version = VersionParser::create('1.0-alpha2');

$float = $version->getBuildNumber();
$int = $version->getBuildNumberInt();
```

Sorting versions
----------------

[](#sorting-versions)

The best way to sort versions is to use the build numbers, which allow numeric comparisons. Here's an example that sorts them in ascending order:

```
use \Mistralys\VersionParser\VersionParser;

$versions = array(
    VersionParser::create('1.1'),
    VersionParser::create('2'),
    VersionParser::create('1.5.9'),
    VersionParser::create('1.5.9-beta'),
    VersionParser::create('2.0.0-alpha')
);

usort($versions, static function (VersionParser $a, VersionParser $b) : int {
    return $a->getBuildNumberInt() - $b->getBuildNumberInt();
});
```

This will sort the list the following way:

1. `1.1.0`
2. `1.5.9-beta`
3. `1.5.9`
4. `2.0.0-alpha`
5. `2.0.0`

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity31

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~299 days

Total

5

Last Release

882d ago

Major Versions

1.0.1 → 2.0.02023-04-20

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8895528?v=4)[Mistralys](/maintainers/Mistralys)[@Mistralys](https://github.com/Mistralys)

---

Top Contributors

[![Mistralys](https://avatars.githubusercontent.com/u/8895528?v=4)](https://github.com/Mistralys "Mistralys (43 commits)")

---

Tags

phpsemantic-versioningversion-checkerversion-parser

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/mistralys-version-parser/health.svg)

```
[![Health](https://phpackages.com/badges/mistralys-version-parser/health.svg)](https://phpackages.com/packages/mistralys-version-parser)
```

###  Alternatives

[composer/composer

Composer helps you declare, manage and install dependencies of PHP projects. It ensures you have the right stack everywhere.

29.4k187.2M2.6k](/packages/composer-composer)[vlucas/phpdotenv

Loads environment variables from `.env` to `getenv()`, `$\_ENV` and `$\_SERVER` automagically.

13.5k602.4M5.4k](/packages/vlucas-phpdotenv)[friendsofphp/php-cs-fixer

A tool to automatically fix PHP code style

13.5k234.7M20.6k](/packages/friendsofphp-php-cs-fixer)[rubix/ml

A high-level machine learning and deep learning library for the PHP language.

2.2k1.4M28](/packages/rubix-ml)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

728272.9k20](/packages/civicrm-civicrm-core)[jmikola/geojson

GeoJSON implementation for PHP

3109.0M77](/packages/jmikola-geojson)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)