From fb37120b6ebf3593e61ed3672ed3e6e938aa336d Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Mon, 30 Jun 2025 23:04:27 +0200 Subject: [PATCH 1/5] Add documentation for the new SemVer constraint --- reference/constraints/SemVer.rst | 307 ++++++++++++++++++++++++++++++ reference/constraints/map.rst.inc | 1 + 2 files changed, 308 insertions(+) create mode 100644 reference/constraints/SemVer.rst diff --git a/reference/constraints/SemVer.rst b/reference/constraints/SemVer.rst new file mode 100644 index 00000000000..007e2aa530e --- /dev/null +++ b/reference/constraints/SemVer.rst @@ -0,0 +1,307 @@ +SemVer +====== + +Validates that a value is a valid semantic version string according to the +`Semantic Versioning`_ specification. This constraint supports various +version formats including partial versions, pre-release versions, and +build metadata. + +.. versionadded:: 7.4 + The ``SemVer`` constraint was introduced in Symfony 7.4. + +========== =================================================================== +Applies to :ref:`property or method ` +Class :class:`Symfony\\Component\\Validator\\Constraints\\SemVer` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\SemVerValidator` +========== =================================================================== + +Basic Usage +----------- + +.. configuration-block:: + + .. code-block:: php-attributes + + // src/Entity/Package.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Package + { + #[Assert\SemVer] + protected string $version; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\Package: + properties: + version: + - SemVer: ~ + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/Package.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + use Symfony\Component\Validator\Mapping\ClassMetadata; + + class Package + { + // ... + + public static function loadValidatorMetadata(ClassMetadata $metadata): void + { + $metadata->addPropertyConstraint('version', new Assert\SemVer()); + } + } + +.. include:: /reference/constraints/_empty-values-are-valid.rst.inc + +Options +------- + +``requirePrefix`` +~~~~~~~~~~~~~~~~~ + +**type**: ``boolean`` **default**: ``false`` + +When set to ``true``, the version string must start with a "v" prefix +(e.g., "v1.2.3" instead of "1.2.3"). + +.. configuration-block:: + + .. code-block:: php-attributes + + // src/Entity/Package.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Package + { + #[Assert\SemVer(requirePrefix: true)] + protected string $version; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\Package: + properties: + version: + - SemVer: + requirePrefix: true + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/Package.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + use Symfony\Component\Validator\Mapping\ClassMetadata; + + class Package + { + // ... + + public static function loadValidatorMetadata(ClassMetadata $metadata): void + { + $metadata->addPropertyConstraint('version', new Assert\SemVer([ + 'requirePrefix' => true, + ])); + } + } + +``allowPreRelease`` +~~~~~~~~~~~~~~~~~~~ + +**type**: ``boolean`` **default**: ``true`` + +Whether to allow pre-release versions (e.g., "1.2.3-beta", "2.0.0-rc.1"). +When set to ``false``, only stable versions are considered valid. + +.. configuration-block:: + + .. code-block:: php-attributes + + // src/Entity/Package.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Package + { + #[Assert\SemVer(allowPreRelease: false)] + protected string $version; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\Package: + properties: + version: + - SemVer: + allowPreRelease: false + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/Package.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + use Symfony\Component\Validator\Mapping\ClassMetadata; + + class Package + { + // ... + + public static function loadValidatorMetadata(ClassMetadata $metadata): void + { + $metadata->addPropertyConstraint('version', new Assert\SemVer([ + 'allowPreRelease' => false, + ])); + } + } + +``allowBuildMetadata`` +~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``boolean`` **default**: ``true`` + +Whether to allow build metadata in the version string (e.g., "1.2.3+20130313144700"). +When set to ``false``, build metadata is not allowed. + +.. configuration-block:: + + .. code-block:: php-attributes + + // src/Entity/Package.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Package + { + #[Assert\SemVer(allowBuildMetadata: false)] + protected string $version; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\Package: + properties: + version: + - SemVer: + allowBuildMetadata: false + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/Package.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + use Symfony\Component\Validator\Mapping\ClassMetadata; + + class Package + { + // ... + + public static function loadValidatorMetadata(ClassMetadata $metadata): void + { + $metadata->addPropertyConstraint('version', new Assert\SemVer([ + 'allowBuildMetadata' => false, + ])); + } + } + +.. include:: /reference/constraints/_groups-option.rst.inc + +.. include:: /reference/constraints/_payload-option.rst.inc + +Valid Version Examples +---------------------- + +The following are examples of valid semantic versions: + +- ``1`` (partial version) +- ``1.2`` (partial version) +- ``1.2.3`` (full version) +- ``v1.2.3`` (with prefix) +- ``1.2.3-alpha`` (pre-release) +- ``1.2.3-beta.1`` (pre-release with numeric identifier) +- ``1.2.3+20130313144700`` (with build metadata) +- ``1.2.3-beta+exp.sha.5114f85`` (pre-release and build metadata) + +.. _`Semantic Versioning`: https://semver.org/ \ No newline at end of file diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc index 06680e42207..9dffb98c448 100644 --- a/reference/constraints/map.rst.inc +++ b/reference/constraints/map.rst.inc @@ -33,6 +33,7 @@ String Constraints * :doc:`NotCompromisedPassword ` * :doc:`PasswordStrength ` * :doc:`Regex ` +* :doc:`SemVer ` * :doc:`Twig ` * :doc:`Ulid ` * :doc:`Url ` From f584de1a812b51a12e0ce0bd1c9327acf83c6918 Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Mon, 30 Jun 2025 23:08:46 +0200 Subject: [PATCH 2/5] Update reference/constraints/SemVer.rst --- reference/constraints/SemVer.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/reference/constraints/SemVer.rst b/reference/constraints/SemVer.rst index 007e2aa530e..5f6b56c031a 100644 --- a/reference/constraints/SemVer.rst +++ b/reference/constraints/SemVer.rst @@ -7,6 +7,7 @@ version formats including partial versions, pre-release versions, and build metadata. .. versionadded:: 7.4 + The ``SemVer`` constraint was introduced in Symfony 7.4. ========== =================================================================== From 6795cf551a37694181614c56626dc23acbdc69c2 Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 09:56:00 +0200 Subject: [PATCH 3/5] Update SemVer constraint documentation to reflect latest changes - Remove requirePrefix, allowPreRelease, and allowBuildMetadata options - Add strict option (default: true) as the only configuration option - Update examples to show behavior with strict mode enabled/disabled --- reference/constraints/SemVer.rst | 168 ++++--------------------------- 1 file changed, 21 insertions(+), 147 deletions(-) diff --git a/reference/constraints/SemVer.rst b/reference/constraints/SemVer.rst index 5f6b56c031a..511c6ff49fb 100644 --- a/reference/constraints/SemVer.rst +++ b/reference/constraints/SemVer.rst @@ -80,151 +80,21 @@ Basic Usage Options ------- -``requirePrefix`` -~~~~~~~~~~~~~~~~~ - -**type**: ``boolean`` **default**: ``false`` - -When set to ``true``, the version string must start with a "v" prefix -(e.g., "v1.2.3" instead of "1.2.3"). - -.. configuration-block:: - - .. code-block:: php-attributes - - // src/Entity/Package.php - namespace App\Entity; - - use Symfony\Component\Validator\Constraints as Assert; - - class Package - { - #[Assert\SemVer(requirePrefix: true)] - protected string $version; - } - - .. code-block:: yaml - - # config/validator/validation.yaml - App\Entity\Package: - properties: - version: - - SemVer: - requirePrefix: true - - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php - - // src/Entity/Package.php - namespace App\Entity; - - use Symfony\Component\Validator\Constraints as Assert; - use Symfony\Component\Validator\Mapping\ClassMetadata; - - class Package - { - // ... - - public static function loadValidatorMetadata(ClassMetadata $metadata): void - { - $metadata->addPropertyConstraint('version', new Assert\SemVer([ - 'requirePrefix' => true, - ])); - } - } - -``allowPreRelease`` -~~~~~~~~~~~~~~~~~~~ +``strict`` +~~~~~~~~~~ **type**: ``boolean`` **default**: ``true`` -Whether to allow pre-release versions (e.g., "1.2.3-beta", "2.0.0-rc.1"). -When set to ``false``, only stable versions are considered valid. - -.. configuration-block:: - - .. code-block:: php-attributes - - // src/Entity/Package.php - namespace App\Entity; - - use Symfony\Component\Validator\Constraints as Assert; - - class Package - { - #[Assert\SemVer(allowPreRelease: false)] - protected string $version; - } - - .. code-block:: yaml - - # config/validator/validation.yaml - App\Entity\Package: - properties: - version: - - SemVer: - allowPreRelease: false - - .. code-block:: xml - - - - - - - - - - - - - - - .. code-block:: php +When set to ``true``, the version must strictly follow the official +`Semantic Versioning`_ specification. This means: - // src/Entity/Package.php - namespace App\Entity; +- No "v" prefix is allowed (use "1.2.3", not "v1.2.3") +- A full version is required (major.minor.patch) - use Symfony\Component\Validator\Constraints as Assert; - use Symfony\Component\Validator\Mapping\ClassMetadata; +When set to ``false``, common version variations are allowed: - class Package - { - // ... - - public static function loadValidatorMetadata(ClassMetadata $metadata): void - { - $metadata->addPropertyConstraint('version', new Assert\SemVer([ - 'allowPreRelease' => false, - ])); - } - } - -``allowBuildMetadata`` -~~~~~~~~~~~~~~~~~~~~~~ - -**type**: ``boolean`` **default**: ``true`` - -Whether to allow build metadata in the version string (e.g., "1.2.3+20130313144700"). -When set to ``false``, build metadata is not allowed. +- The "v" prefix is accepted (e.g., "v1.2.3") +- Partial versions are valid (e.g., "1", "1.2") .. configuration-block:: @@ -237,7 +107,7 @@ When set to ``false``, build metadata is not allowed. class Package { - #[Assert\SemVer(allowBuildMetadata: false)] + #[Assert\SemVer(strict: false)] protected string $version; } @@ -248,7 +118,7 @@ When set to ``false``, build metadata is not allowed. properties: version: - SemVer: - allowBuildMetadata: false + strict: false .. code-block:: xml @@ -261,7 +131,7 @@ When set to ``false``, build metadata is not allowed. - + @@ -282,7 +152,7 @@ When set to ``false``, build metadata is not allowed. public static function loadValidatorMetadata(ClassMetadata $metadata): void { $metadata->addPropertyConstraint('version', new Assert\SemVer([ - 'allowBuildMetadata' => false, + 'strict' => false, ])); } } @@ -294,15 +164,19 @@ When set to ``false``, build metadata is not allowed. Valid Version Examples ---------------------- -The following are examples of valid semantic versions: +When using ``strict: true`` (default), the following are valid: -- ``1`` (partial version) -- ``1.2`` (partial version) - ``1.2.3`` (full version) -- ``v1.2.3`` (with prefix) - ``1.2.3-alpha`` (pre-release) - ``1.2.3-beta.1`` (pre-release with numeric identifier) - ``1.2.3+20130313144700`` (with build metadata) - ``1.2.3-beta+exp.sha.5114f85`` (pre-release and build metadata) +When using ``strict: false``, additional formats are accepted: + +- ``1`` (partial version) +- ``1.2`` (partial version) +- ``v1.2.3`` (with "v" prefix) +- ``v1.2.3-alpha`` (prefix with pre-release) + .. _`Semantic Versioning`: https://semver.org/ \ No newline at end of file From 246e93eee28425f1cb5b320cd154201f2d998656 Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Wed, 2 Jul 2025 22:56:08 +0200 Subject: [PATCH 4/5] fix --- reference/constraints/SemVer.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/reference/constraints/SemVer.rst b/reference/constraints/SemVer.rst index 511c6ff49fb..3c6d454f643 100644 --- a/reference/constraints/SemVer.rst +++ b/reference/constraints/SemVer.rst @@ -1,9 +1,9 @@ SemVer ====== -Validates that a value is a valid semantic version string according to the -`Semantic Versioning`_ specification. This constraint supports various -version formats including partial versions, pre-release versions, and +Validates that a value is a valid semantic version string according to the +`Semantic Versioning`_ specification. This constraint supports various +version formats including partial versions, pre-release versions, and build metadata. .. versionadded:: 7.4 @@ -85,7 +85,7 @@ Options **type**: ``boolean`` **default**: ``true`` -When set to ``true``, the version must strictly follow the official +When set to ``true``, the version must strictly follow the official `Semantic Versioning`_ specification. This means: - No "v" prefix is allowed (use "1.2.3", not "v1.2.3") From bcb7e019e7ba3825e9593e9de01f7746791f7874 Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Thu, 3 Jul 2025 09:02:42 +0200 Subject: [PATCH 5/5] Update reference/constraints/SemVer.rst Co-authored-by: Christian Flothmann --- reference/constraints/SemVer.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/constraints/SemVer.rst b/reference/constraints/SemVer.rst index 3c6d454f643..b4e1c78942a 100644 --- a/reference/constraints/SemVer.rst +++ b/reference/constraints/SemVer.rst @@ -52,7 +52,7 @@ Basic Usage - +