jean85/pretty-package-versions

A small, independent wrapper to get pretty versions strings

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()

pretty-package-versions's Issues

Support Composer 2 natively

After #13, we support both Composer 1 and 2, but we're forced to rely on the forked dependency to do that.

We now could release a new version (1.4?) that would require Composer 2, but drop the dependency. In this way, any consumer of this package could still rely on ^1.0 of this package, without tying to a specific Composer version, but having a smooth upgrade path nonetheless, and dropping the additional dependency as soon as possible.

Typo in the about section

Hi,

There is a small typo in the about section, indipendent instead of independent.

Missing composer-runtime-api

When trying to install I get the following error:

Your requirements could not be resolved to an installable set of packages.
  Problem 1
    - Installation request for jean85/pretty-package-versions 2.0.4 -> satisfiable by jean85/pretty-package-versions[2.0.4].
    - jean85/pretty-package-versions 2.0.4 requires composer-runtime-api ^2.0.0 -> no matching package found.

There is no package called composer-runtime-api at packagist as of today.

Reference may be null

I thought that #31 fixed the only cases where reference was missing, but getsentry/sentry-symfony#435 (comment) reported that that wasn't the case.

We need to guard for cases where reference may be null when fetching it from Composer 2 APIs.

Version of the root package is displayed incorrectly

↪ wget https://github.com/phpstan/phpstan/releases/download/0.8.5/phpstan.phar

↪ php phpstan.phar --version
PHPStan - PHP Static Analysis Tool 0.8.5.0

The tag name is 0.8.5 according to the URL but the displayed version is 0.8.5.0. The same can be seen with any other application using \Jean85\PrettyVersions::getVersion('vendor/package')->getPrettyVersion(); where the vendor/package is the app itself.

Looks like when building the version from a git tag, composer/semver pads the version with zeros to have at least 4 numbers (see composer/semver@c1f064e#diff-b25d417df293a1cf205697536aed0410R33).

Not sure if the original tag can be restored from the padded version, but I'd say that most of the packages have 3 numbers in their version, so it should be safe to cut off the trailing zero. Unless there's a better solution.

Deprecated methods and their replacements

Hi!

2.0 version renamed some *CommitHash methods to Version::getReference, Version::getShortReference and Version::getVersionWithShortReference.

Would it be possible to add these new methods to 1.5 as a forward compatibility layer?

I require this package as ^1.5 || ^2.0 and what happens is that Psalm reports that I am using a deprecated method, however, there is no way to get rid of the deprecation message (other than ignoring it in Psalm) since those new methods are not available in 1.5.

I hope I am clear enough with my issue :)

Thanks!

getShortCommit method

Would it be possible to add a getShortCommit method, that will return the second part (after @) of the getVersionWithShortCommit output?

Thanks!

ReplacedPackageException thrown for packages that are listen as "replaced", yet not desired

I'm experiencing an unexpected behaviour, after upgrading to your v2.x. The ReplacedPackageException exception is thrown when a target package is listed in the replace section of my root composer.json. I fail to understand why this is needed...

Thus, when I attempt to obtain the version of one of my packages, e.g. aedart/athenaeum-console, from my unit or integration tests, the mentioned exception is thrown.

Additional Context

I am working on upgrading several packages in my Athenaeum project, which is a mono-repository. As such, all packages that are offered, are listed inside my root composer.json in the replacesection.
E.g.:

{
    "replace": {
        "aedart/athenaeum-acl": "self.version",
        "aedart/athenaeum-audit": "self.version",
        "aedart/athenaeum-circuits": "self.version",
        "aedart/athenaeum-collections": "self.version",
    }
}

(Entire composer.json content is not shown in the above example.)

The replace section is not something that I manually maintain, but rather something that Monorepo Builder does for me.

I'm sure that you have a good reason / edge-case when you must throw the mentioned exception, yet I have no idea how to avoid it in my particular case...

LICENSE file is missing on composer install

Hello.

Thanks for your package, that I used now. But I've a little problem to re-distribute a PHAR version of my package (php-compatinfo-db) that should include your package.

Please consider to remove this line

pretty-package-versions/.gitattributes

Line 9 in 75c7eff

LICENSE export-ignore

Laurent

Undefined class constant 'ROOT_PACKAGE_NAME'

In version 1.5.1:

PHP Fatal error:  Uncaught FatalThrowableError: Undefined class constant 'ROOT_PACKAGE_NAME' in vendor/jean85/pretty-package-versions/src/PrettyVersions.php:23

1.4.0 without Composer 1 support should be a major release

Hi,

That release should be rather a major release: https://github.com/Jean85/pretty-package-versions/releases/tag/1.4.0

Packages such as sentry/sentry-symfony include "jean85/pretty-package-versions": "^1.0" which finally forces the installation of Jean85/pretty-package-versions 1.4.0 with dropped support for Composer 1.

We still need and have to use Composer 1.

Adding "jean85/pretty-package-versions": "1.3.0" explicitly to composer.json require section it solves issues meanwhile:
Package operations: 0 installs, 2 updates, 0 removals

• Updating composer/package-versions-deprecated (1.8.0 => 1.8.0): Loading from cache
• Downgrading jean85/pretty-package-versions (1.4.0 => 1.3.0): Loading from cache

Thanks
Rico

Dependency just changed to php 7.4 requirement

The orcas dependency has changed its required to php 7.4 which we have not upgraded to yet and will not be able to any time soon. We're just trying to use the sentry/sdk plugin which requires your module so now we're stuck. Is there a way around this?

Don't support component which does not has pretty_version.

hyperf/hyperf#3224

Prettify "No version set"

When Composer can not determine the version of a package, it sets it to No version set (parsed as 1.0.0)@.
(For example, this happens for the root package if we are not in a Git repository.)

Maybe PrettyVersions could return something more user-friendly like null or "unknown"?

Please keep compat with Composer 1 in the foreaseeable future

Hello, I saw that v1.4 of this package dropped support for Composer 1.

I fear that new features will be added here in the future, but will be made available only to Composer 2 users.

As soon as a dependent will start to require ^1.4 of this package, it means Composer 1 will conflict.

We have the responsibility to make the transition smoother IMHO, thus this issue.

Class 'Composer\InstalledVersions' not found

we are using sentry-laravel package which requires your package.
but after installation we get below error.

Class 'Composer\InstalledVersions' not found

we are using composer.phar instead of installing composer.

FC layer for Version::ROOT_PACKAGE

I got a false positive with Composer Require Checker as reported in maglnet/ComposerRequireChecker#188, but that made me realize that we could expose a getRootPackageName FC layer, which the end user could rely on while on the upgrade path from Ocramius' package to Composer 2 native support in 1.4.

This should be released as a backported patch in 1.2.x and 1.3.x, and as a full feature in 1.4.

Root package version generated from the branch name is not pretty

Consider the following example:

git init
cat > composer.json <<EOF
{
    "name": "test/test",
    "require": {
        "jean85/pretty-package-versions": "^1.0.2"
    }
}
EOF

cat > main.php  <<EOF
<?php

require __DIR__ . '/vendor/autoload.php';
echo \Jean85\PrettyVersions::getVersion('test/test')->getPrettyVersion(), PHP_EOL;
EOF

git checkout -b 3.0
git add .
git commit -mTest
composer install
php main.php

# 3.0.9999999.9999999-dev@412b22b

The issue is reproducible with the patch from Ocramius/PackageVersions/pull/51 applied. Similarly to #3, it's only reproducible for the root package. For dependencies, the version is displayed without the 9s (e.g. phpunit/phpunit 6.4.x-dev@a94c40a).

Sorry for making so much noise :-) I'm trying to start using pretty versions in a project.

High memory usage

During getsentry/sentry-php#1606, the user discovered a high memory usage by Jean85\PrettyVersions::getVersion, more specifically in the Jean85\PrettyVersions::checkProvidedPackage private method:

Retrieve root package information using native APIs

Currently getRootPackageVersion does this:

pretty-package-versions/src/PrettyVersions.php

Lines 39 to 42 in 6d9ae9a

	public static function getRootPackageVersion(): Version
	{
	return self::getVersion(self::getRootPackageName());
	}

This seems dangerous if the user hasn't given a proper name to his project, or if he's using a name that is somehow provided or replaced by some of the installed dependencies. Since the root project name has no effect it the project itself is not a redistributed library, we could leverage the InstalledVersions::getRootPackage() API directly to avoid this kind of issue.

This has been originally discovered in getsentry/sentry-symfony#435

Possible to lock Ocramius/PackageVersions dependency?

Ocramius/PackageVersions dropped php 7.2 support. PHP 7.2 is still actively maintained.
I use this package through phpstan for a ton of my repos. But this breaks at version 1.5 of Ocramius/PackageVersions
Ocramius/PackageVersions#105
Seems a bit radically to suddendly drop support for an active php version.