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 28 commits into
base: 7.4
Choose a base branch
from
Open

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

wants to merge 28 commits into from
+592 −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
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 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 16 commits July 8, 2025 09:05
@OskarStark
Remove unnecessary comment
980da3b
@OskarStark
Use x modifier for regex patterns to improve readability
24ae6af 
- 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
29fa35a 
- 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
a1150a8
@OskarStark @alexandre-daubois
Update src/Symfony/Component/Validator/Constraints/SemVer.php
16a50f5 
Co-authored-by: Alexandre Daubois <2144837+alexandre-daubois@users.noreply.github.com>
@OskarStark
Add min/max version constraints to SemVer validator
eb7cb3a 
- 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
Rename tooHighMessage/tooLowMessage to minMessage/maxMessage and make…
c662126 
… strict parameter required in data providers
@OskarStark
Update src/Symfony/Component/Validator/Tests/Constraints/SemVerValida…
b944f69 
…torTest.php
@OskarStark
Move expectException calls directly before the code that triggers the…
2481bab 
… exception
@OskarStark
Add tests for custom message, minMessage and maxMessage
ccf6364
@OskarStark
Follow Symfony constraint pattern: initialize message properties with…
5fc3119 
… default values
@OskarStark @alexandre-daubois
Update src/Symfony/Component/Validator/Tests/Constraints/SemVerValida…
7b2c9d2 
…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…
dd3a772 
…torTest.php

Co-authored-by: Alexandre Daubois <2144837+alexandre-daubois@users.noreply.github.com>
@OskarStark
Remove unnecessary comments as requested in code review
bcd66da 
As per Alex Daubois's review comments, removed explanatory comments
that were deemed unnecessary for clean, self-documenting code.
@OskarStark
Apply code review feedback from fabpot and nicolas-grekas
f87dff0 
- Add backslash to count() function for consistency
- Refactor regex matching to use ternary operator for more concise code
- Note: Data providers were already correctly placed after their test methods
- Note: Min/max constraints implementation is complete and working as expected
@OskarStark
Add documentation for SemVer constraint options
2af8ece 
Document the available options (strict, min, max) in the class header
to make it clearer what configuration options are available.
@OskarStark OskarStark force-pushed the feature/semver-constraint branch from abc0eac to 2af8ece Compare July 8, 2025 07:06
OskarStark added 2 commits July 8, 2025 09:09
@OskarStark
Refactor SemVer constraint to use non-nullable constructor arguments
8d04e1e 
- Move default values from property declarations to constructor arguments
- Make message, minMessage, maxMessage, and strict parameters non-nullable
- Rearrange parameters in logical order: strict, message, min, minMessage, max, maxMessage
@OskarStark
Fix parameter order: keep nullable parameters at the end
09dbe1c 
Reorder constructor parameters to follow Symfony conventions where
nullable parameters should come after non-nullable ones.
@stof
Copy link
Member

stof commented Jul 9, 2025

Note that various package managers have different regexps for versions they accept. Composer and npm don't agree on the regexp for instance.
And the regex used here does not match the Composer one (I haven't checked whether it matches the npm one)

@OskarStark
Copy link
Contributor Author

Note that various package managers have different regexps for versions they accept. Composer and npm don't agree on the regexp for instance.
And the regex used here does not match the Composer one (I haven't checked whether it matches the npm one)

I would say its fine to have a constraint based on the official RFC, I guess there are more projects with different regexes out there and we can't fulfill all of them

@fabpot
Copy link
Member

fabpot commented Jul 10, 2025

Note that various package managers have different regexps for versions they accept. Composer and npm don't agree on the regexp for instance.
And the regex used here does not match the Composer one (I haven't checked whether it matches the npm one)

I would say its fine to have a constraint based on the official RFC, I guess there are more projects with different regexes out there and we can't fulfill all of them

But then, the usefulness for this in core is limited? I suppose that supporting at least Composer would make sense?

@OskarStark
Copy link
Contributor Author

But then, the usefulness for this in core is limited? I suppose that supporting at least Composer would make sense?

Well I don't want to use the composer logic, but the strict RFC one, we could ofc implement an option like "type": rfc, composer. To me following standards makes sense, this is what we do for IBAN, BIC, Http etc.

@stof
Copy link
Member

stof commented Jul 10, 2025

The question is whether it is useful to have this in core, if projects cannot use it in practice because they expect a version supported by npm or by composer.

To me, this is too specific to be in core.

@OskarStark
Copy link
Contributor Author

WDYT @alexandre-daubois @javiereguiluz @GromNaN as you approved this PR

@GromNaN
Copy link
Member

GromNaN commented Jul 10, 2025

There may be more validations based on composer version and constraint parser. In that case, you would need to use composer/semver.

But I must admit that I can't think of a use for it.

@stof
Copy link
Member

stof commented Jul 10, 2025

What are the actual use cases for using that constraint ?

@alexandre-daubois
Copy link
Member

alexandre-daubois commented Jul 10, 2025 •
edited
Loading

I wasn't aware that there were multiple "standards" for semver. I thought all the tools agreed on the same definition. If two major tools like Composer and NPM can't agree on that, it becomes really specific. But as @stof asked, maybe actual use cases would be welcomed to have a better opinion?

@OskarStark
Copy link
Contributor Author

What are the actual use cases for using that constraint ?

We release software for pur clients based on SemVer and following the official specs, and in our database we want to track when, what was delivered. So I need this constraint in this way. I don't need the min/max thing and we only use strict, so these options are only added by me for the community. OFC I can use this constraint on my own in userland.

@stof
Copy link
Member

stof commented Jul 11, 2025

I suggest keeping this (simplified) constraint in your own project (or maybe even just defining a constant holding the regexp and using it with the Regex constraint).
I think having it in core is risky (people will then complain that this constraint is not compatible with what composer accepts because they work with versions targeting usage in composer)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@fabpot fabpot fabpot left review comments

@nicolas-grekas nicolas-grekas nicolas-grekas left review comments

@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

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.
9 participants
@OskarStark @xabbuh @fabpot @stof @GromNaN @alexandre-daubois @javiereguiluz @nicolas-grekas @carsonbot
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy