DOCSEARCHbyAlgolia
Submit Docs

composer/semver

repository·main·Indexed 25 days ago

https://github.com/composer/semver

A PHP library providing utilities for version comparison, constraint parsing, and validation. It is a standalone version of the logic used within Composer to handle semantic versioning and version constraints. Key components include VersionParser for normalization and validation, Comparator for boolean version comparisons, Semver for checking constraint satisfaction and sorting, and Intervals for managing complex version ranges and boundaries.

Tokens
2.8K
Snippets
1
Records
25
Agent score
84%

What's inside composer/semver

  2. Validate and normalize versions with VersionParser

    main

    The Composer\Semver\VersionParser class provides methods for parsing, normalizing, and validating versions and constraints. Numeric versions are normalized to 4-component versions (e.g., 1.2.3 becomes 1.2.3.0) for internal consistency.

    Version methods:

    • isValid($version): Validates a version string.
    • normalize($version, $fullVersion = null): Normalizes a version string.
    • normalizeBranch($name): Normalizes a branch name.
    • normalizeDefaultBranch($name): Normalizes a default branch name.

    Constraint methods:

    • parseConstraints($constraints): Parses constraint strings.

    Stability methods:

    • parseStability($version): Parses stability from a version.
    • normalizeStability($stability): Normalizes a stability string.

  3. Work with version intervals using Intervals

    main

    The Composer\Semver\Intervals static class provides utilities for working with complex constraints and version intervals.

    Methods:

    • isSubsetOf(ConstraintInterface $candidate, ConstraintInterface $constraint): Checks whether the candidate constraint is a subset of the target constraint.
    • haveIntersections(ConstraintInterface $a, ConstraintInterface $b): Checks if two constraints have any intersection.
    • compactConstraint(ConstraintInterface $constraint): Optimizes a complex multi-constraint by merging intervals down to the smallest possible multi-constraint.
    • get(ConstraintInterface $constraint): Creates an array of numeric intervals and branch constraints representing a given constraint.
    • clear(): Clears the memoization cache.

  4. Check version satisfaction and sort with Semver

    main

    The Composer\Semver\Semver class provides high-level utilities for checking if versions meet specific constraints and for sorting version lists.

    Methods:

    • satisfies($version, $constraints): Checks if a version string satisfies the given constraints.
    • satisfiedBy(array $versions, $constraint): Returns an array of versions from the input array that satisfy the constraint.
    • sort($versions): Sorts an array of version strings in ascending order.
    • rsort($versions): Sorts an array of version strings in descending order.

  5. Compare versions with Comparator

    main

    The Composer\Semver\Comparator class provides static methods to compare two version strings. Each method returns a boolean.

    Comparison methods:

    • greaterThan($v1, $v2)
    • greaterThanOrEqualTo($v1, $v2)
    • lessThan($v1, $v2)
    • lessThanOrEqualTo($v1, $v2)
    • equalTo($v1, $v2)
    • notEqualTo($v1, $v2)

  6. Normalize stability strings with VersionParser::normalizeStability()

    main

    Use VersionParser::normalizeStability($stability) to convert a stability string into its canonical form.

    Accepted values: stable, RC, beta, alpha, dev.

    Throws \InvalidArgumentException if the provided stability is not one of the accepted values.

  7. Filter versions by constraints with Semver::satisfiedBy()

    main

    Use Semver::satisfiedBy(array $versions, $constraints) to filter an array of version strings, returning only those that satisfy the provided constraints.

    • $versions: An array of version strings.
    • $constraints: The constraint string to match against.

    Returns a new list of version strings that match the constraints.

  8. Sort versions with Semver::sort() and Semver::rsort()

    main

    Sort an array of version strings using semantic versioning logic.

    • Semver::sort(array $versions): Sorts versions in ascending order (lowest to highest).
    • Semver::rsort(array $versions): Sorts versions in descending order (highest to lowest).

    Both methods return a new array containing the sorted version strings.

  9. Normalize a version string with VersionParser::normalize()

    main

    Use VersionParser::normalize($version, $fullVersion = null) to convert a version string into a canonical format suitable for comparisons.

    This method handles:

    • Stripping aliasing (e.g., 1.0.0 as 1.0.0)
    • Stripping stability flags (e.g., @dev)
    • Normalizing branch names like master, trunk, or default to dev-master, etc.
    • Stripping build metadata.
    • Converting date-based versioning to standard numeric segments.

    Throws \UnexpectedValueException if the version string is invalid.

  11. Check if a version satisfies constraints with Semver::satisfies()

    main

    Use Semver::satisfies($version, $constraints) to determine if a specific version string meets a set of semantic versioning constraints.

    • $version: The version string to check (e.g., '1.2.3').
    • $constraints: The constraint string (e.g., '^1.2', '~1.0', or '1.2.3').

    Returns true if the version satisfies the constraints, false otherwise.