{"id":24540679,"url":"https://github.com/mistralys/version-parser","last_synced_at":"2026-05-18T08:33:09.997Z","repository":{"id":57017611,"uuid":"293903820","full_name":"Mistralys/version-parser","owner":"Mistralys","description":"Flexible semantic version string parser for PHP","archived":false,"fork":false,"pushed_at":"2023-12-19T07:21:45.000Z","size":78,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-22T21:04:50.231Z","etag":null,"topics":["php","semantic-versioning","version-checker","version-parser"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mistralys.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-09-08T19:09:57.000Z","updated_at":"2023-12-19T15:31:38.000Z","dependencies_parsed_at":"2023-12-18T16:02:42.367Z","dependency_job_id":"ff038ba0-f61e-49f3-93a8-9dac3997b9e5","html_url":"https://github.com/Mistralys/version-parser","commit_stats":{"total_commits":9,"total_committers":1,"mean_commits":9.0,"dds":0.0,"last_synced_commit":"cc6c0b3e918a9f85fb063ab6b8e64b319239a167"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fversion-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fversion-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fversion-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fversion-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mistralys","download_url":"https://codeload.github.com/Mistralys/version-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243830914,"owners_count":20354850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php","semantic-versioning","version-checker","version-parser"],"created_at":"2025-01-22T18:14:40.202Z","updated_at":"2026-05-18T08:33:09.963Z","avatar_url":"https://github.com/Mistralys.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Version string parser for PHP\n\nPHP 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.\n\n## Supported version strings\n\nThe parser expects versions to be in the following format:\n\n`MajorVersion.MinorVersion.PatchVersion-BranchOrTag`\n\nThis allows the use of a wide range of version strings. Some examples:\n\n- `1`\n- `1.1`\n- `1.1.5`\n- `1.145.147`\n- `1.1.5-rc1`\n- `1.1.5-beta`\n- `1.1.5-beta2`\n- `1.1.5-beta.42`\n- `1.1.5-BranchName`\n- `1.1.5-BranchName-alpha2`\n- `1.1.5 BranchName A2` _Spaces are allowed_\n- `1.1.5 \"Branch name\"` _Quotes are stripped_\n- `1.1.5 (BranchName) / Alpha 2` _Special characters are filtered out_\n- `1.1.5-DEV Branch Name` _Branch names after the tag type_\n\nMost special characters are filtered out, which means that it is \nvery lenient in what is passed to it. After the version number,\nanything that is not a tag qualifier (`beta`, `alpha`, etc.) is\nconsidered the branch name.\n\n## Installation\n\nSimply require the package with composer.\n\nVia command line:\n\n```shell\ncomposer require mistralys/version-parser\n```\n\nVia composer.json:\n\n```json\n{\n    \"require\": {\n      \"mistralys/version-parser\": \"dev-master\"\n    }\n}\n```\n\n## Usage\n\n### Getting individual version numbers\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2');\n\n$major = $version-\u003egetMajorVersion(); // 1\n$minor = $version-\u003egetMinorVersion(); // 5\n$patch = $version-\u003egetPatchVersion(); // 2\n```\n\n### Getting a version without tag\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2-RC3');\n\n$number = $version-\u003egetVersion(); // 1.5.2\n```\n\nThe version is normalized to show all three levels, even if they were not specified.\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1');\n\n$number = $version-\u003egetVersion(); // 1.0.0\n```\n\n### Getting a short version\n\nThe method `getShortVersion()` retrieves a version string with the minimum possible levels.\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.0.0');\n\n$number = $version-\u003egetVersion(); // 1\n```\n\n### Getting the full version, normalized\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create(\"1.2.0 'Cool Release' RC5\");\n\n$normalized = $version-\u003egetTagVersion(); // 1.0.0-CoolRelease-rc5\n```\n\n\u003e NOTE: The branch name is also normalized. Words are capitalized,\n\u003e and spaces are removed. Other special characters are preserved.\n\n### Checking the tag type\n\nTo check the release type, the shorthand methods `isBeta()`, `isAlpha()`, \netc. can be used. See \"Supported release tags\" for details.\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2-beta');\n\n$isBeta = $version-\u003eisBeta(); // true\n```\n\nAlternatively, it is possible to check the tag type manually.\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2-beta5');\n\nif($version-\u003egetTagType() === VersionParser::TAG_TYPE_BETA)\n{\n\t// is a beta version\n}\n```\n\nThe tag info object that can be accessed with the `getTagInfo()`\nmethod goes more in depth. \n\nFor example, the method `getTagName()` will return the tag type \nexactly as used in the version string, whereas `getTagType()` will \nonly return the long type variant (e.g. `beta` instead of `b`):\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$tag = VersionParser::create('1.5.2-B2')-\u003egetTagInfo();\n\nif($tag !== null)\n{\n    echo $tag-\u003egetTagName(); // b\n    echo $tag-\u003egetTagType(); // beta\n}\n```\n\n### Getting the tag number\n\nWhen no number is added to the tag, it is assumed that it is the tag #1.\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2-beta');\n\n$betaVersion = $version-\u003egetTagNumber(); // 1 (implicit)\n```\n\nWith a number added:\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2-beta5');\n\n$betaVersion = $version-\u003egetTagNumber(); // 5\n```\n\n### Getting the branch name\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2-Foobar');\n\n$hasBranch = $version-\u003ehasBranch(); // true\n$branchName = $version-\u003egetBranchName(); // Foobar\n```\n\nThis also works in combination with a release tag:\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2-Foobar-RC1');\n\n$hasBranch = $version-\u003ehasBranch(); // true\n$branchName = $version-\u003egetBranchName(); // Foobar\n```\n\nBranch names may contain special characters. Quotes are filtered out:\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2 \"Foobar/42\"');\n\n$hasBranch = $version-\u003ehasBranch(); // true\n$branchName = $version-\u003egetBranchName(); // Foobar/42\n```\n\n### Setting the separator character\n\nBy default, the branch name and tag are separated with hyphens (`-`) \nwhen normalizing the version string. This can be adjusted to any character:\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2-BranchName-alpha5');\n\necho $version\n    -\u003esetSeparatorChar('_')\n    -\u003egetTagVersion();\n```\n\nWill output:\n\n```\n1.5.2_BranchName_alpha5\n```\n\n### Converting tag types to uppercase\n\nBy default, tag types are converted to lowercase when normalizing the\nversion string. They can be switched to uppercase instead:\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.5.2-BranchName-alpha5');\n\necho $version\n    -\u003esetTagUppercase()\n    -\u003egetTagVersion();\n```\n\nWill output:\n\n```\n1.5.2-BranchName-ALPHA5\n```\n\n## Supported release tags\n\nThe parser will handle the following tags automatically, and assign\nthem a build number value:\n\n- `dev` or `snapshot` - Development release, weight: `8`\n- `alpha` - Alpha release, weight: `6`\n- `beta` - Beta release, weight: `4`\n- `rc` - Release candidate, weight: `2`\n- `patch` - Patch/bugfix release, weight: `1`\n- `stable` - Stable release, weight: `0`\n\nThis means that comparing the same version numbers with different \nrelease tags will work. For example, `1.4-beta` is considered a higher\nversion than `1.4-alpha`, because `beta` has a lower weight than `alpha`.\n\n### Numbering tags\n\nAlso supported is numbering tagged versions:\n\n- `1.0-alpha` - Implied `alpha1`\n- `1.0-alpha2` - Alpha `2`\n\n### Adding custom tags\n\nIf you use other tag types in your application's version strings,\nthey can be added so the parser recognizes them:\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n// The third parameter is the short variant of the tag type.\nVersionParser::registerTagType('foobar', 5, 'f');\n\n$version = VersionParser::create('1.0.5-foobar2');\n$short = VersionParser::create('1.0.5-F2');\n\necho $version-\u003egetTagType(); // foobar\necho $short-\u003egetTagType(); // foobar\n```\n\nIf you mix custom tag types and the standard ones, be careful with\nthe sorting weight you set for them, so they will be weighted correctly.\nIf needed, you can change the weight of the default types to make more\nroom.\n\nThis for example resets the weights for some existing tag types, and \ninserts new ones:\n\n```php\nuse Mistralys\\VersionParser\\VersionParser;\n\n$weight = 900; // Can be any number\nVersionParser::registerTagType(VersionParser::TAG_TYPE_ALPHA, $weight--);\nVersionParser::registerTagType(VersionParser::TAG_TYPE_BETA, $weight--);\nVersionParser::registerTagType('foobar', $weight--);\nVersionParser::registerTagType(VersionParser::TAG_TYPE_RELEASE_CANDIDATE, $weight--);\nVersionParser::registerTagType('prefinal', $weight--);\n```\n\n\u003e NOTE: The weights are used in the generated build numbers. Changing the\n\u003e default tag type weights will change their build numbers as well.\n\n## Build numbers\n\nThe version strings are intelligently converted to numbers, to allow\ncomparisons and sorting. This includes the release tags like `alpha`\nor `beta`, which are converted as well. The result is a build number \nwhich can be either a floating point number, or an integer.\n\n  \u003e NOTE: These numbers are not meant to be human-readable. Their sole\n    purpose is to recognize version numbers programmatically.\n   \nThere are two methods related to this:\n\n```php\nuse \\Mistralys\\VersionParser\\VersionParser;\n\n$version = VersionParser::create('1.0-alpha2');\n\n$float = $version-\u003egetBuildNumber();\n$int = $version-\u003egetBuildNumberInt();\n```\n\n## Sorting versions\n\nThe best way to sort versions is to use the build numbers, which allow\nnumeric comparisons. Here's an example that sorts them in ascending order:\n\n```php\nuse \\Mistralys\\VersionParser\\VersionParser;\n\n$versions = array(\n    VersionParser::create('1.1'),\n    VersionParser::create('2'),\n    VersionParser::create('1.5.9'),\n    VersionParser::create('1.5.9-beta'),\n    VersionParser::create('2.0.0-alpha')\n);\n\nusort($versions, static function (VersionParser $a, VersionParser $b) : int {\n    return $a-\u003egetBuildNumberInt() - $b-\u003egetBuildNumberInt();\n});\n```\n\nThis will sort the list the following way:\n\n1. `1.1.0`\n2. `1.5.9-beta`\n3. `1.5.9`\n4. `2.0.0-alpha`\n5. `2.0.0`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistralys%2Fversion-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmistralys%2Fversion-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistralys%2Fversion-parser/lists"}