Version Constraints

SemVer Format

  MAJOR.MINOR.PATCH
  |       |       |
  |       |       +-- Bug fixes (backwards compatible)
  |       +-- New features (backwards compatible)
  +-- Breaking changes

Version Examples

  1.0.0      -> First stable release
  1.0.1      -> Bug fix
  1.1.0      -> New feature
  2.0.0      -> Breaking changes
  1.0.0-beta -> Pre-release
  1.0.0-RC1  -> Release candidate
  1.0.0-dev  -> Development version

Magento Versioning

  2.4.6      -> Magento release
  2.4.6-p1   -> Security patch
  2.4.6-p2   -> Security patch
  103.0.5    -> Framework version
  101.1.0    -> Module version

Exact Version

{
    "require": {
        "vendor/package": "1.2.3"
    }
}

Range Operators

{
    "require": {
        "vendor/package": ">=1.0 <2.0",    
        "vendor/package": "^1.2.3",        
        "vendor/package": "~1.2.3",        
        "vendor/package": "1.*",            
        "vendor/package": "1.0.*",
        "vendor/package": "*"              
    }
}

Operator Reference

Caret Operator (^)

  ^1.2.3  -> >=1.2.3 <2.0.0
  ^0.2.3  -> >=0.2.3 <0.3.0
  ^0.0.3  -> >=0.0.3 <0.0.4

Tilde Operator (~)

  ~1.2.3  -> >=1.2.3 <1.3.0
  ~1.2    -> >=1.2.0 <1.3.0
  ~1      -> >=1.0.0 <2.0.0

Stability Levels

  stable   -> Production ready
  RC       -> Release candidate
  beta     -> Beta testing
  alpha    -> Early development
  dev      -> Development version

Stability Constraints

{
    "require": {
        "vendor/package": "1.0.0@stable",
        "vendor/package": "1.0.0@RC",
        "vendor/package": "1.0.0@beta",
        "vendor/package": "1.0.0@alpha",
        "vendor/package": "1.0.0@dev",
        "vendor/package": "dev-master@dev"
    }
}

Minimum Stability

{
    "minimum-stability": "stable",
    "prefer-stable": true
}

Stability Flags

{
    "stability-flags": {
        "vendor/package": 20,
        "vendor/other": 10
    }
}

Dev Dependencies

{
    "require-dev": {
        "phpunit/phpunit": "^9.5",
        "phpstan/phpstan": "^1.0"
    }
}

Magento Module Constraints

{
    "require": {
        "php": "^8.1",
        "magento/framework": "^103.0",
        "magento/module-store": "^101.0",
        "magento/module-catalog": "^104.0"
    }
}

Tight vs Loose Constraints

// Tight (patch-level)
"^1.2.3"  // >=1.2.3 <2.0.0

// Loose (major-level)
">=1.0 <3.0"

// Very tight (exact)
"1.2.3"

Breaking Change Strategy

namespace Vendor\Module\Version;

class VersionStrategy
{
    public function getConstraints(): array
    {
        return [
            // Always use ^ for Magento modules
            'magento/framework' => '^103.0',

            // Use ^ for your modules
            'vendor/module-a' => '^1.0',

            // Use ~ for minor version control
            'vendor/module-b' => '~1.2.0',

            // Exact for critical dependencies
            'vendor/critical' => '1.0.0',
        ];
    }
}

Constraint Validation

namespace Vendor\Composer\Validation;

class ConstraintValidator
{
    public function validate(array $constraints): ValidationResult
    {
        $errors = [];

        foreach ($constraints as $package => $constraint) {
            if ($this->isTooLoose($constraint)) {
                $errors[] = "$package: constraint too loose: $constraint";
            }

            if ($this->isTooTight($constraint)) {
                $errors[] = "$package: constraint too tight: $constraint";
            }
        }

        return new ValidationResult(empty($errors), $errors);
    }
}