8000 [Validator] Add `SemVer` constraint for semantic versioning validation by OskarStark · Pull Request #60995 · symfony/symfony · GitHub
[go: up one dir, main page]
Skip to content

[Validator] Add SemVer constraint for semantic versioning validation #60995

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 24 commits into
base: 7.4
Choose a base branch
from
Open

[Validator] Add SemVer constraint for semantic versioning validation #60995

wants to merge 24 commits into from
+590 −0

Conversation

OskarStark
Copy link
Contributor
@OskarStark OskarStark commented Jun 30, 2025 •
edited
Loading
Q A
Branch? 7.4
Bug fix? no
New feature? yes
Deprecations? no
Issues symfony/symfony-docs#21162
License MIT

Description

This PR adds a new SemVer constraint to validate semantic versioning strings according to the Semantic Versioning 2.0.0 specification.

Options

Specific Options

  • strict (default: true): Whether to use strict SemVer validation (no 'v' prefix, no partial versions) or loose validation
  • min (default: null): Minimum allowed version (uses version_compare() for comparison)
  • max (default: null): Maximum allowed version (uses version_compare() for comparison)
  • message (default: 'This value is not a valid semantic version.'): Message for invalid version format
  • minMessage (default: 'This value should be {{ min }} or more.'): Message when version is below minimum
  • maxMessage (default: 'This value should be {{ max }} or less.'): Message when version exceeds maximum

Default Options

  • groups: The validation groups this constraint belongs to
  • payload: Domain-specific data attached to the constraint

Features

Basic Validation

The constraint validates version strings with two modes:

  • Strict mode (default): Only accepts versions that strictly follow the SemVer 2.0.0 spec (e.g., 1.2.3, 1.0.0-alpha, 1.2.3+build123)
  • Loose mode: Also accepts common variations like partial versions and 'v' prefix (e.g., v1.2.3, 1.2, 1)

Version Range Validation

The constraint supports min and max options to validate version ranges:

use Symfony\Component\Validator\Constraints as Assert;

class Package
{
    #[Assert\SemVer(
        min: '1.0.0',
        max: '2.0.0',
        minMessage: 'This version is too old, minimum required is {{ min }}',
        maxMessage: 'This version is too new, maximum allowed is {{ max }}'
    )]
    private string $version;
}

Usage Examples

Basic usage (strict mode by default):

#[Assert\SemVer]
private string $version; // Valid: "1.2.3", Invalid: "v1.2.3", "1.2"

Loose mode:

#[Assert\SemVer(strict: false)]
private string $version; // Valid: "1.2.3", "v1.2.3", "1.2", "1"

With version constraints:

#[Assert\SemVer(min: '1.0.0', max: '3.0.0')]
private string $version; // Must be between 1.0.0 and 3.0.0

Custom error messages:

#[Assert\SemVer(
    message: 'Invalid version format',
    minMessage: 'Version must be at least {{ min }}',
    maxMessage: 'Version cannot exceed {{ max }}'
)]

Implementation Details

  • Uses version_compare() for min/max comparisons to ensure correct semantic version ordering
  • Min/max values must follow the same strict/loose rules as the validated value
  • Comprehensive test coverage with 99 tests covering all scenarios

@carsonbot carsonbot added this to the 7.4 milestone Jun 30, 2025
@OskarStark OskarStark changed the title [Validator] Add SemVer constraint for semantic versioning validation [Validator] Add SemVer constraint for semantic versioning validation Jun 30, 2025
@OskarStark OskarStark mentioned this pull request Jun 30, 2025
Open
@xabbuh
Copy link
Member
xabbuh commented Jul 1, 2025

Is checking for a version really common enough to justify adding it to the Validator component?

@OskarStark
Copy link
Contributor Author

I also thought about just using regex, but as you can see, the regex(es) itself are quite complicated, so I thought it would be a nice addition.

Ofc lets wait what others say

javiereguiluz
javiereguiluz reviewed Jul 1, 2025
View reviewed changes
OskarStark
OskarStark commented Jul 1, 2025
View reviewed changes
8000
alexandre-daubois
alexandre-daubois reviewed Jul 1, 2025
View reviewed changes
@OskarStark
Copy link
Contributor Author

Do you agree with the default true value for strict option?

stof
stof reviewed 8000 Jul 1, 2025
View reviewed changes
OskarStark
OskarStark commented Jul 1, 2025
View reviewed changes
OskarStark
OskarStark commented Jul 1, 2025
View reviewed changes
alexandre-daubois
alexandre-daubois approved these changes Jul 2, 2025
View reviewed changes
GromNaN
GromNaN reviewed Jul 2, 2025
View reviewed changes
Copy link
Member
@GromNaN GromNaN left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be useful to add the $min and $max parameters using version_compare to check the value?

@OskarStark
Copy link
Contributor Author

Great idea 💡 I can do that in a follow up PR 🙋‍♂️

@OskarStark
Copy link
Contributor Author

Min and max must then be a "valid" semantic version based on "strict" parameter, right?

@fabpot
Copy link
Member
fabpot commented Jul 2, 2025

Great idea 💡 I can do that in a follow up PR 🙋‍♂️

Let's do it here :)

@OskarStark
Copy link
Contributor Author

Will do it tomorrow 🙌

OskarStark and others added 10 commits July 2, 2025 22:29
@OskarStark
Simplify SemVer constraint to use single 'strict' option
26e2501 
- Replace requirePrefix, allowPreRelease, and allowBuildMetadata with a single 'strict' boolean option
- When strict=true: follows official SemVer spec (no 'v' prefix, requires full version)
- When strict=false: allows common variations (parti
8000
al versions, 'v' prefix)
- Update tests to reflect the new behavior
@OskarStark
Update src/Symfony/Component/Validator/Constraints/SemVerValidator.php
90a91d9
@OskarStark
Change default value of strict option to true
53bbc78 
- Default behavior now follows the official SemVer specification
- Users must explicitly set strict=false to allow loose validation
@OskarStark
Remove array-based configuration support from SemVer constraint
7830db9 
- Remove off on off off off off off off off off on off on off on off off off on off off off on on off off off on on off off off off off off off on off off off off on off on off off off off off on off on on off off off on off on on off on on off off on on on off on on off on off off off off on off off off on off off on off on off off off on on off on off on off off on off off off on off off off off off off off off on off on off on on on off on on off off on off on on on off on on off on off on off off off off off on on off off on off off off off off on off off on on off on off off on off off off on off off off off on on off on off off off off off on off on off off off off off off off off off off on on off on off off off parameter from constructor as array-based configuration is deprecated in Symfony 8.0
- Only support named arguments for configuration
- This follows the modern Symfony constraint pattern
@OskarStark
Remove unnecessary comment
9cbff30
@OskarStark
Use x modifier for regex patterns to improve readability
642dfb1 
- Convert regex patterns to multi-line format with x modifier
- Add inline comments to explain each part of the pattern
- Makes complex regex patterns more maintainable
@OskarStark
Apply stof's suggestions for better compatibility
4ce63f8 
- Add HasNamedArguments attribute for XML/YAML mapping compatibility
- Move property defaults to constructor arguments as non-nullable
- Follow modern Symfony constraint pattern
@OskarStark
Apply suggestions from code review
bf43ccc
@OskarStark @alexandre-daubois
ebdc360 
Co-authored-by: Alexandre Daubois <2144837+alexandre-daubois@users.noreply.github.com>
@OskarStark
Add min/max version constraints to SemVer validator
a62f9f9 
- Add min and max parameters to SemVer constraint
- Implement version comparison logic using version_compare()
- Add normalizeVersion() method to handle version normalization
- Add comprehensive test coverage for min/max functionality
- Validate min/max parameters follow strict mode rules
@OskarStark OskarStark force-pushed the feature/semver-constraint branch from ceb986e to a62f9f9 Compare July 2, 2025 20:34
@OskarStark
Rename tooHighMessage/tooLowMessage to minMessage/maxMessage and make…
5dce356 
… strict parameter required in data providers
@OskarStark OskarStark force-pushed the feature/semver-constraint branch from cfe6583 to 5dce356 Compare July 2, 2025 20:39
@OskarStark
Copy link
Contributor Author

Done!

GromNaN
GromNaN approved these changes Jul 3, 2025
View reviewed changes
Copy link
Member
@GromNaN GromNaN left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excellent!

alexandre-daubois
alexandre-daubois reviewed Jul 3, 2025
View reviewed changes
OskarStark and others added 3 commits July 3, 2025 08:51
@OskarStark @alexandre-daubois
Update src/Symfony/Component/Validator/Tests/Constraints/SemVerValida…
b09799c 
…torTest.php

Co-authored-by: Alexandre Daubois <2144837+alexandre-daubois@users.noreply.github.com>
@OskarStark @alexandre-daubois
Update src/Symfony/Component/Validator/Tests/Constraints/SemVerValida…
c6f1545 
…torTest.php

Co-authored-by: Alexandre Daubois <2144837+alexandre-daubois@users.noreply.github.com>
@OskarStark
Remove unnecessary comments as requested in code review
b7a6d49 
As per Alex Daubois's review comments, removed explanatory comments
that were deemed unnecessary for clean, self-documenting code.
@OskarStark
Copy link
Contributor Author

done @alexandre-daubois

@OskarStark OskarStark requested a review from fabpot July 3, 2025 07:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@javiereguiluz javiereguiluz javiereguiluz approved these changes

@GromNaN GromNaN GromNaN approved these changes

@alexandre-daubois alexandre-daubois alexandre-daubois approved these changes

@xabbuh xabbuh Awaiting requested review from xabbuh

@stof stof Awaiting requested review from stof

@fabpot fabpot Awaiting requested review from fabpot

Assignees
No one assigned
Labels
Feature Status: Needs Review Validator
Projects
None yet
Milestone
7.4
Development

Successfully merging this pull request may close these issues.
8 participants
@OskarStark @xabbuh @fabpot @javiereguiluz @GromNaN @stof @alexandre-daubois @carsonbot
0