Skip to content

Commit 84b5474

Browse files
OskarStarkclaude
OskarStark
and
claude
committed
Add documentation for the new SemVer constraint
This documents the SemVer constraint introduced in Symfony 7.4, which validates semantic version strings according to the Semantic Versioning specification. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent e9f04f4 commit 84b5474

File tree

2 files changed

+308
-0
lines changed

2 files changed

+308
-0
lines changed

‎reference/constraints/SemVer.rst

Lines changed: 307 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,307 @@
1+
SemVer
2+
======
3+
4+
Validates that a value is a valid semantic version string according to the
5+
`Semantic Versioning`_ specification. This constraint supports various
6+
version formats including partial versions, pre-release versions, and
7+
build metadata.
8+
9+
.. versionadded:: 7.4
10+
The ``SemVer`` constraint was introduced in Symfony 7.4.
11+
12+
========== ===================================================================
13+
Applies to :ref:`property or method <validation-property-target>`
14+
Class :class:`Symfony\\Component\\Validator\\Constraints\\SemVer`
15+
Validator :class:`Symfony\\Component\\Validator\\Constraints\\SemVerValidator`
16+
========== ===================================================================
17+
18+
Basic Usage
19+
-----------
20+
21+
.. configuration-block::
22+
23+
.. code-block:: php-attributes
24+
25+
// src/Entity/Package.php
26+
namespace App\Entity;
27+
28+
use Symfony\Component\Validator\Constraints as Assert;
29+
30+
class Package
31+
{
32+
#[Assert\SemVer]
33+
protected string $version;
34+
}
35+
36+
.. code-block:: yaml
37+
38+
# config/validator/validation.yaml
39+
App\Entity\Package:
40+
properties:
41+
version:
42+
- SemVer: ~
43+
44+
.. code-block:: xml
45+
46+
<!-- config/validator/validation.xml -->
47+
<?xml version="1.0" encoding="UTF-8" ?>
48+
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
49+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
50+
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
51+
52+
<class name="App\Entity\Package">
53+
<property name="version">
54+
<constraint name="SemVer" />
55+
</property>
56+
</class>
57+
</constraint-mapping>
58+
59+
.. code-block:: php
60+
61+
// src/Entity/Package.php
62+
namespace App\Entity;
63+
64+
use Symfony\Component\Validator\Constraints as Assert;
65+
use Symfony\Component\Validator\Mapping\ClassMetadata;
66+
67+
class Package
68+
{
69+
// ...
70+
71+
public static function loadValidatorMetadata(ClassMetadata $metadata): void
72+
{
73+
$metadata->addPropertyConstraint('version', new Assert\SemVer());
74+
}
75+
}
76+
77+
.. include:: /reference/constraints/_empty-values-are-valid.rst.inc
78+
79+
Options
80+
-------
81+
82+
``requirePrefix``
83+
~~~~~~~~~~~~~~~~~
84+
85+
**type**: ``boolean`` **default**: ``false``
86+
87+
When set to ``true``, the version string must start with a "v" prefix
88+
(e.g., "v1.2.3" instead of "1.2.3").
89+
90+
.. configuration-block::
91+
92+
.. code-block:: php-attributes
93+
94+
// src/Entity/Package.php
95+
namespace App\Entity;
96+
97+
use Symfony\Component\Validator\Constraints as Assert;
98+
99+
class Package
100+
{
101+
#[Assert\SemVer(requirePrefix: true)]
102+
protected string $version;
103+
}
104+
105+
.. code-block:: yaml
106+
107+
# config/validator/validation.yaml
108+
App\Entity\Package:
109+
properties:
110+
version:
111+
- SemVer:
112+
requirePrefix: true
113+
114+
.. code-block:: xml
115+
116+
<!-- config/validator/validation.xml -->
117+
<?xml version="1.0" encoding="UTF-8" ?>
118+
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
119+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
120+
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
121+
122+
<class name="App\Entity\Package">
123+
<property name="version">
124+
<constraint name="SemVer">
125+
<option name="requirePrefix">true</option>
126+
</constraint>
127+
</property>
128+
</class>
129+
</constraint-mapping>
130+
131+
.. code-block:: php
132+
133+
// src/Entity/Package.php
134+
namespace App\Entity;
135+
136+
use Symfony\Component\Validator\Constraints as Assert;
137+
use Symfony\Component\Validator\Mapping\ClassMetadata;
138+
139+
class Package
140+
{
141+
// ...
142+
143+
public static function loadValidatorMetadata(ClassMetadata $metadata): void
144+
{
145+
$metadata->addPropertyConstraint('version', new Assert\SemVer([
146+
'requirePrefix' => true,
147+
]));
148+
}
149+
}
150+
151+
``allowPreRelease``
152+
~~~~~~~~~~~~~~~~~~~
153+
154+
**type**: ``boolean`` **default**: ``true``
155+
156+
Whether to allow pre-release versions (e.g., "1.2.3-beta", "2.0.0-rc.1").
157+
When set to ``false``, only stable versions are considered valid.
158+
159+
.. configuration-block::
160+
161+
.. code-block:: php-attributes
162+
163+
// src/Entity/Package.php
164+
namespace App\Entity;
165+
166+
use Symfony\Component\Validator\Constraints as Assert;
167+
168+
class Package
169+
{
170+
#[Assert\SemVer(allowPreRelease: false)]
171+
protected string $version;
172+
}
173+
174+
.. code-block:: yaml
175+
176+
# config/validator/validation.yaml
177+
App\Entity\Package:
178+
properties:
179+
version:
180+
- SemVer:
181+
allowPreRelease: false
182+
183+
.. code-block:: xml
184+
185+
<!-- config/validator/validation.xml -->
186+
<?xml version="1.0" encoding="UTF-8" ?>
187+
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
188+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
189+
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
190+
191+
<class name="App\Entity\Package">
192+
<property name="version">
193+
<constraint name="SemVer">
194+
<option name="allowPreRelease">false</option>
195+
</constraint>
196+
</property>
197+
</class>
198+
</constraint-mapping>
199+
200+
.. code-block:: php
201+
202+
// src/Entity/Package.php
203+
namespace App\Entity;
204+
205+
use Symfony\Component\Validator\Constraints as Assert;
206+
use Symfony\Component\Validator\Mapping\ClassMetadata;
207+
208+
class Package
209+
{
210+
// ...
211+
212+
public static function loadValidatorMetadata(ClassMetadata $metadata): void
213+
{
214+
$metadata->addPropertyConstraint('version', new Assert\SemVer([
215+
'allowPreRelease' => false,
216+
]));
217+
}
218+
}
219+
220+
``allowBuildMetadata``
221+
~~~~~~~~~~~~~~~~~~~~~~
222+
223+
**type**: ``boolean`` **default**: ``true``
224+
225+
Whether to allow build metadata in the version string (e.g., "1.2.3+20130313144700").
226+
When set to ``false``, build metadata is not allowed.
227+
228+
.. configuration-block::
229+
230+
.. code-block:: php-attributes
231+
232+
// src/Entity/Package.php
233+
namespace App\Entity;
234+
235+
use Symfony\Component\Validator\Constraints as Assert;
236+
237+
class Package
238+
{
239+
#[Assert\SemVer(allowBuildMetadata: false)]
240+
protected string $version;
241+
}
242+
243+
.. code-block:: yaml
244+
245+
# config/validator/validation.yaml
246+
App\Entity\Package:
247+
properties:
248+
version:
249+
- SemVer:
250+
allowBuildMetadata: false
251+
252+
.. code-block:: xml
253+
254+
<!-- config/validator/validation.xml -->
255+
<?xml version="1.0" encoding="UTF-8" ?>
256+
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
257+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
258+
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
259+
260+
<class name="App\Entity\Package">
261+
<property name="version">
262+
<constraint name="SemVer">
263+
<option name="allowBuildMetadata">false</option>
264+
</constraint>
265+
</property>
266+
</class>
267+
</constraint-mapping>
268+
269+
.. code-block:: php
270+
271+
// src/Entity/Package.php
272+
namespace App\Entity;
273+
274+
use Symfony\Component\Validator\Constraints as Assert;
275+
use Symfony\Component\Validator\Mapping\ClassMetadata;
276+
277+
class Package
278+
{
279+
// ...
280+
281+
public static function loadValidatorMetadata(ClassMetadata $metadata): void
282+
{
283+
$metadata->addPropertyConstraint('version', new Assert\SemVer([
284+
'allowBuildMetadata' => false,
285+
]));
286+
}
287+
}
288+
289+
.. include:: /reference/constraints/_groups-option.rst.inc
290+
291+
.. include:: /reference/constraints/_payload-option.rst.inc
292+
293+
Valid Version Examples
294+
----------------------
295+
296+
The following are examples of valid semantic versions:
297+
298+
- ``1`` (partial version)
299+
- ``1.2`` (partial version)
300+
- ``1.2.3`` (full version)
301+
- ``v1.2.3`` (with prefix)
302+
- ``1.2.3-alpha`` (pre-release)
303+
- ``1.2.3-beta.1`` (pre-release with numeric identifier)
304+
- ``1.2.3+20130313144700`` (with build metadata)
305+
- ``1.2.3-beta+exp.sha.5114f85`` (pre-release and build metadata)
306+
307+
.. _`Semantic Versioning`: https://semver.org/

‎reference/constraints/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ String Constraints
3333
* :doc:`NotCompromisedPassword </reference/constraints/NotCompromisedPassword>`
3434
* :doc:`PasswordStrength </reference/constraints/PasswordStrength>`
3535
* :doc:`Regex </reference/constraints/Regex>`
36+
* :doc:`SemVer </reference/constraints/SemVer>`
3637
* :doc:`Twig </reference/constraints/Twig>`
3738
* :doc:`Ulid </reference/constraints/Ulid>`
3839
* :doc:`Url </reference/constraints/Url>`

0 commit comments

Comments
 (0)