diff --git a/reference/constraints/SemVer.rst b/reference/constraints/SemVer.rst new file mode 100644 index 00000000000..b4e1c78942a --- /dev/null +++ b/reference/constraints/SemVer.rst @@ -0,0 +1,182 @@ +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 +------- + +``strict`` +~~~~~~~~~~ + +**type**: ``boolean`` **default**: ``true`` + +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") +- A full version is required (major.minor.patch) + +When set to ``false``, common version variations are allowed: + +- The "v" prefix is accepted (e.g., "v1.2.3") +- Partial versions are valid (e.g., "1", "1.2") + +.. configuration-block:: + + .. code-block:: php-attributes + + // src/Entity/Package.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Package + { + #[Assert\SemVer(strict: false)] + protected string $version; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\Package: + properties: + version: + - SemVer: + strict: 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([ + 'strict' => false, + ])); + } + } + +.. include:: /reference/constraints/_groups-option.rst.inc + +.. include:: /reference/constraints/_payload-option.rst.inc + +Valid Version Examples +---------------------- + +When using ``strict: true`` (default), the following are valid: + +- ``1.2.3`` (full version) +- ``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 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 `