jean85/pretty-package-versions

A small, independent wrapper to get pretty versions strings of your dependencies.

Installation

• If you use this package in a library, you're encouraged to require it with a constraint of ^1.5 || ^2.0, to obtain all the functionalities without constraining your end users to upgrade immediately to Composer 2.

To install, use Composer:

• from CLI: composer require 'jean85/pretty-package-versions:^1.5 || ^2.0'
• or, directly in your composer.json:

{
    "require": {
        "jean85/pretty-package-versions": "^1.5 || ^2.0"
    }
}

Compatibility

This package was born as a thin wrapper for ocramius/package-versions; with the advent of Composer 2, this is no longer needed, since we can use directly Composer\InstalledVersions. This led to this version compatibility chart:

pretty-package-versions	Composer	Dependency used
Up to 1.2	1.x only	ocramius/package-versions
1.3	Both 1.x and 2.x	composer/package-versions-deprecated, fork of ocramius/package-versions
1.4	2.x only	None
1.5+	Both 1.x and 2.x	composer/package-versions-deprecated, fork of ocramius/package-versions
2.0	2.x only	None

This means that, with this package, you can obtain pretty versions without tying your user to any specific Composer version, with a smooth upgrade path. The release of 1.4 was reverted due to some discussion in #21 and related issues.

Usage

This package should be used with a single class, Jean85\PrettyVersions: it provides a single method that returns a Jean85\Version object for the requested package, like in this example:

use Jean85\PrettyVersions;

$version = PrettyVersions::getVersion('phpunit/phpunit');
$version->getPrettyVersion(); // '6.0.0'
$version->getShortVersion(); // '6.0.0'
$version->getVersionWithShortReference(); // '6.0.0@fa5711'

$version = PrettyVersions::getVersion('roave/security-advisories');
$version->getPrettyVersion(); // 'dev-master@7cd88c8'
$version->getShortVersion(); // 'dev-master'
$version->getVersionWithShortReference(); // 'dev-master@7cd88c8'

The Version class has also a __toString() method implemented, so it can be easily cast to a string; the result would be the same as calling the getPrettyVersion() method.

Available methods

The Jean85\Version class has these public methods available:

• getPrettyVersion(): string: if the requested package is a tagged version, it will return just the short version; if not, it will output the same result as getVersionWithShortCommit()

• getShortVersion(): string: it will return just the version of the package (i.e. 6.0.0, v.1.7.0, 99999-dev etc...)

• getReference(): string will return the reference of the installed package, generally the full Git commit hash

• getShortReference(): string will return the shortened version of the reference (i.e. fa5711)

• getVersionWithShortReference(): string: it will return the version of the package, followed by the short version of the reference (i.e. 6.0.0@fa5711)

• getPackageName(): string will return the original package name

• getFullVersion(): string will return the same value as PackageVersions\Versions::getVersion()

• __toString(): string will return the same as getPrettyVersion()

Since 1.5

Since the 1.5 release, there are two additional methods available:

• PrettyVersions::getRootPackageName returns the package name of the current (root) project, so basically the name property value in your composer.json; it is a compatibility layer to be used in place of PackageVersions\Versions::ROOT_PACKAGE_NAME, which would be a transient dependency and it's not guaranteed to be present
• PrettyVersions::getRootPackageVersion, which is a shortcut to PrettyVersions::getVersion(PrettyVersions::getRootPackageName())

Before 2.0

The methods with reference in the name were introduced in the 2.0 release, to better reflect the meaning of the data retrieved from Composer 2 API. The behavior is the same as the old methods, which are still present but deprecated:

New method	Old, deprecated method
Version::getReference()	Version::getCommitHash()
Version::getShortReference()	Version::getShortCommitHash()
Version::getVersionWithShortReference()	Version::getVersionWithShortCommit()