phar-io/version · error · InvalidVersionException

Version string ' ' does not follow SemVer semantics

Error message

Version string '%s' does not follow SemVer semantics

What it means

InvalidVersionException is thrown by Version::ensureVersionStringIsValid when the supplied string fails the library's full SemVer regex (major.minor.patch with optional pre-release and build metadata). The constructor validates before parsing, so any malformed version string cannot produce a Version object. Note the library's regex is stricter than pure SemVer in places (e.g. numeric release segments).

Solutions

  1. Fix the version string to full SemVer 'MAJOR.MINOR.PATCH[-prerelease][+build]', e.g. '1.2' -> '1.2.0'.
  2. Normalize input before construction: pad missing segments, trim whitespace, strip a leading 'v' only if the regex allows it.
  3. Validate the string against a SemVer pattern before calling the constructor and surface a user-friendly message.
  4. If versions come from external sources, log the raw value to diagnose which producer emits malformed strings.

Example fix

// before
$version = new Version($config['min_version']); // '1.2'

// after
$normalized = $config['min_version'];
if (preg_match('/^\d+\.\d+$/', $normalized)) {
    $normalized .= '.0';
}
$version = new Version($normalized); // '1.2.0'
Defensive patterns

Strategy: validation

Validate before calling

// PHP
if (!preg_match('/^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/', $input)) {
    throw new InvalidArgumentException("Not a valid SemVer string: $input");
}

Try / catch

try {
    $version = new Version($input);
} catch (InvalidVersionException $e) {
    // log raw input and fall back to a default or surface a user error
}

Prevention

When it happens

Trigger: new Version('1.2'), new Version('v1.2.3') depending on regex strictness, new Version('') , new Version('1.2.3.4'), or strings with stray spaces/invalid characters passed to the Version constructor via ensureVersionStringIsValid.

Common situations: Reading versions from composer.json, package metadata, or env vars that contain partial versions like '1.2' or '3'; user-supplied input passed straight into the constructor; upstream tools emitting non-SemVer tags such as '2024.09.14-build'.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of phar-io/version@5eeb03f1ee (2026-09-14). Data as JSON: /api/errors/e085e4e222d50cb9. Report an issue: GitHub.

Appendix: source

Thrown at src/Version.php:202

            (?P<Major>0|[1-9]\d*)
            (\\.
            (?P<Minor>0|[1-9]\d*)
            )?
            (\\.
                (?P<Patch>0|[1-9]\d*)
            )?
            (?:
                -
                (?<PreReleaseSuffix>(?:(dev|beta|b|rc|alpha|a|patch|p|pl)\.?\d*))
            )?
            (?:
                \\+
                (?P<BuildMetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-@]+)*)
            )?
        $/xi';

        if (\preg_match($regex, $version, $matches) !== 1) {
            throw new InvalidVersionException(
                \sprintf("Version string '%s' does not follow SemVer semantics", $version)
            );
        }

        $this->parseVersion($matches);
    }
}

View on GitHub (pinned to 5eeb03f1ee)