Skip to content

Commit fb37120

Browse files
OskarStarkOskarStark
committed
Add documentation for the new SemVer constraint
1 parent e9f04f4 commit fb37120

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)