From 3fa7a6cb5104cc2235a767ee7b2df1475c4763a0 Mon Sep 17 00:00:00 2001 From: Martin Herndl Date: Mon, 25 Oct 2021 11:09:52 +0200 Subject: [PATCH] Add types to `Package/Version` (#10199) --- .../Package/Version/VersionGuesser.php | 66 ++++++++++++++++++- .../Package/Version/VersionParser.php | 7 +- .../Package/Version/VersionSelector.php | 20 ++++-- 3 files changed, 84 insertions(+), 9 deletions(-) diff --git a/src/Composer/Package/Version/VersionGuesser.php b/src/Composer/Package/Version/VersionGuesser.php index ef8a057bb..504263a6c 100644 --- a/src/Composer/Package/Version/VersionGuesser.php +++ b/src/Composer/Package/Version/VersionGuesser.php @@ -26,6 +26,8 @@ use Composer\Util\Svn as SvnUtil; * * @author Jordi Boggiano * @author Samuel Roze + * + * @phpstan-type Version array{version: string, commit: string|null, pretty_version: string|null, feature_version?: string|null, feature_pretty_version?: string|null} */ class VersionGuesser { @@ -57,10 +59,11 @@ class VersionGuesser } /** - * @param array $packageConfig - * @param string $path Path to guess into + * @param array $packageConfig + * @param string $path Path to guess into * - * @return null|array versionData, 'version', 'pretty_version' and 'commit' keys, if the version is a feature branch, 'feature_version' and 'feature_pretty_version' keys may also be returned + * @return array|null + * @phpstan-return Version|null */ public function guessVersion(array $packageConfig, $path) { @@ -91,6 +94,14 @@ class VersionGuesser return null; } + /** + * @param array $versionData + * + * @phpstan-param Version $versionData + * + * @return array + * @phpstan-return Version + */ private function postprocess(array $versionData) { if (!empty($versionData['feature_version']) && $versionData['feature_version'] === $versionData['version'] && $versionData['feature_pretty_version'] === $versionData['pretty_version']) { @@ -108,6 +119,12 @@ class VersionGuesser return $versionData; } + /** + * @param array $packageConfig + * @param string $path + * + * @return array{version: string|null, commit: string|null, pretty_version: string|null, feature_version?: string|null, feature_pretty_version?: string|null} + */ private function guessGitVersion(array $packageConfig, $path) { GitUtil::cleanEnv(); @@ -188,6 +205,11 @@ class VersionGuesser return array('version' => $version, 'commit' => $commit, 'pretty_version' => $prettyVersion); } + /** + * @param string $path + * + * @return array{version: string, pretty_version: string}|null + */ private function versionFromGitTags($path) { // try to fetch current version from git tags @@ -203,6 +225,12 @@ class VersionGuesser return null; } + /** + * @param array $packageConfig + * @param string $path + * + * @return array{version: string|null, commit: ''|null, pretty_version: string|null, feature_version?: string|null, feature_pretty_version?: string|null}|null + */ private function guessHgVersion(array $packageConfig, $path) { // try to fetch current version from hg branch @@ -232,8 +260,21 @@ class VersionGuesser return $result; } + + return null; } + /** + * @param array $packageConfig + * @param string|null $version + * @param string[] $branches + * @param string $scmCmdline + * @param string $path + * + * @phpstan-param non-empty-string $scmCmdline + * + * @return array{version: string|null, pretty_version: string|null} + */ private function guessFeatureVersion(array $packageConfig, $version, array $branches, $scmCmdline, $path) { $prettyVersion = $version; @@ -292,6 +333,12 @@ class VersionGuesser return array('version' => $version, 'pretty_version' => $prettyVersion); } + /** + * @param array $packageConfig + * @param string|null $branchName + * + * @return bool + */ private function isFeatureBranch(array $packageConfig, $branchName) { $nonFeatureBranches = ''; @@ -302,6 +349,11 @@ class VersionGuesser return !preg_match('{^(' . $nonFeatureBranches . '|master|main|latest|next|current|support|tip|trunk|default|develop|\d+\..+)$}', $branchName, $match); } + /** + * @param string $path + * + * @return array{version: string|null, commit: '', pretty_version: string|null} + */ private function guessFossilVersion($path) { $version = null; @@ -326,6 +378,12 @@ class VersionGuesser return array('version' => $version, 'commit' => '', 'pretty_version' => $prettyVersion); } + /** + * @param array $packageConfig + * @param string $path + * + * @return array{version: string, commit: '', pretty_version: string}|null + */ private function guessSvnVersion(array $packageConfig, $path) { SvnUtil::cleanEnv(); @@ -357,5 +415,7 @@ class VersionGuesser return array('version' => $version, 'commit' => '', 'pretty_version' => $prettyVersion); } } + + return null; } } diff --git a/src/Composer/Package/Version/VersionParser.php b/src/Composer/Package/Version/VersionParser.php index 455162726..41a2447bc 100644 --- a/src/Composer/Package/Version/VersionParser.php +++ b/src/Composer/Package/Version/VersionParser.php @@ -42,9 +42,9 @@ class VersionParser extends SemverVersionParser * The parsing results in an array of arrays, each of which * contain a 'name' key with value and optionally a 'version' key with value. * - * @param array $pairs a set of package/version pairs separated by ":", "=" or " " + * @param string[] $pairs a set of package/version pairs separated by ":", "=" or " " * - * @return array[] array of arrays containing a name and (if provided) a version + * @return list */ public function parseNameVersionPairs(array $pairs) { @@ -70,6 +70,9 @@ class VersionParser extends SemverVersionParser } /** + * @param string $normalizedFrom + * @param string $normalizedTo + * * @return bool */ public static function isUpgrade($normalizedFrom, $normalizedTo) diff --git a/src/Composer/Package/Version/VersionSelector.php b/src/Composer/Package/Version/VersionSelector.php index 641575488..046cccde6 100644 --- a/src/Composer/Package/Version/VersionSelector.php +++ b/src/Composer/Package/Version/VersionSelector.php @@ -57,10 +57,12 @@ class VersionSelector * Given a package name and optional version, returns the latest PackageInterface * that matches. * - * @param string $packageName - * @param string $targetPackageVersion - * @param string $preferredStability - * @param bool|array $ignorePlatformReqs + * @param string $packageName + * @param string $targetPackageVersion + * @param string $preferredStability + * @param bool|string[] $ignorePlatformReqs + * @param int $repoSetFlags + * * @return PackageInterface|false */ public function findBestCandidate($packageName, $targetPackageVersion = null, $preferredStability = 'stable', $ignorePlatformReqs = false, $repoSetFlags = 0) @@ -187,6 +189,13 @@ class VersionSelector return $package->getPrettyVersion(); } + /** + * @param string $version + * @param string $prettyVersion + * @param string $stability + * + * @return string + */ private function transformVersion($version, $prettyVersion, $stability) { // attempt to transform 2.1.1 to 2.1 @@ -215,6 +224,9 @@ class VersionSelector return '^' . $version; } + /** + * @return VersionParser + */ private function getParser() { if ($this->parser === null) {