8000 feature #13167 [Validator] Documented the Hostname constraint (javier… · symfony/symfony-docs@d0b800f · GitHub
[go: up one dir, main page]
Skip to content

Commit d0b800f

Browse files
HeahDudeHeahDude
committed
feature #13167 [Validator] Documented the Hostname constraint (javiereguiluz)
This PR was merged into the master branch. Discussion ---------- [Validator] Documented the Hostname constraint Fixes #12923. Commits ------- 9bc1214 [Validator] Documented the Hostname constraint
2 parents 58e9262 + 9bc1214 commit d0b800f

File tree

3 files changed

+137
-0
lines changed

3 files changed

+137
-0
lines changed

‎reference/constraints.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Validation Constraints Reference
1717
constraints/Length
1818
constraints/Url
1919
constraints/Regex
20+
constraints/Hostname
2021
constraints/Ip
2122
constraints/Uuid
2223
constraints/Json

‎reference/constraints/Hostname.rst

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
Hostname
2+
========
3+
4+
This constraint ensures that the given value is a valid host name (internally it
5+
uses the ``FILTER_VALIDATE_DOMAIN`` option of the :phpfunction:`filter_var` PHP
6+
function).
7+
8+
.. versionadded:: 5.1
9+
10+
The ``Hostname`` constraint was introduced in Symfony 5.1.
11+
12+
========== ===================================================================
13+
Applies to :ref:`property or method <validation-property-target>`
14+
Options - `groups`_
15+
- `message`_
16+
- `payload`_
17+
- `requireTld`_
18+
Class :class:`Symfony\\Component\\Validator\\Constraints\\Hostname`
19+
Validator :class:`Symfony\\Component\\Validator\\Constraints\\HostnameValidator`
20+
========== ===================================================================
21+
22+
Basic Usage
23+
-----------
24+
25+
To use the Hostname validator, apply it to a property on an object that
26+
will contain a host name.
27+
28+
.. configuration-block::
29+
30+
.. code-block:: php-annotations
31+
32+
// src/Entity/ServerSettings.php
33+
namespace App\Entity;
34+
35+
use Symfony\Component\Validator\Constraints as Assert;
36+
37+
class ServerSettings
38+
{
39+
/**
40+
* @Assert\Hostname(message="The server name must be a valid hostname.")
41+
*/
42+
protected $name;
43+
}
44+
45+
.. code-block:: yaml
46+
47+
# config/validator/validation.yaml
48+
App\Entity\ServerSettings:
49+
properties:
50+
name:
51+
- Hostname:
52+
message: The server name must be a valid hostname.
53+
54+
.. code-block:: xml
55+
56+
<!-- config/validator/validation.xml -->
57+
<?xml version="1.0" encoding="UTF-8" ?>
58+
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
59+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
60+
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
61+
62+
<class name="App\Entity\ServerSettings">
63+
<property name="name">
64+
<constraint name="Hostname">
65+
<option name="message">The server name must be a valid hostname.</option>
66+
</constraint>
67+
</property>
8000
68+
</class>
69+
</constraint-mapping>
70+
71+
.. code-block:: php
72+
73+
// src/Entity/ServerSettings.php
74+
namespace App\Entity;
75+
76+
use Symfony\Component\Validator\Constraints as Assert;
77+
use Symfony\Component\Validator\Mapping\ClassMetadata;
78+
79+
class ServerSettings
80+
{
81+
public static function loadValidatorMetadata(ClassMetadata $metadata)
82+
{
83+
$metadata->addPropertyConstraint('name', new Assert\Hostname([
84+
'message' => 'The server name must be a valid hostname.',
85+
]));
86+
}
87+
}
88+
89+
The following top-level domains (TLD) are reserved according to `RFC 2606`_ and
90+
that's why hostnames containing them are not considered valid: ``.example``,
91+
``.invalid``, ``.localhost``, and ``.test``.
92+
93+
.. include:: /reference/constraints/_empty-values-are-valid.rst.inc
94+
95+
Options
96+
-------
97+
98+
.. include:: /reference/constraints/_groups-option.rst.inc
99+
100+
``message``
101+
~~~~~~~~~~~
102+
103+
**type**: ``string`` **default**: ``This value is not a valid hostname.``
104+
105+
The default message supplied when the value is not a valid hostname.
106+
107+
You can use the following parameters in this message:
108+
109+
=============== ==============================================================
110+
Parameter Description
111+
=============== ==============================================================
112+
``{{ value }}`` The current (invalid) value
113+
=============== ==============================================================
114+
115+
.. include:: /reference/constraints/_payload-option.rst.inc
116+
117+
``requireTld``
118+
~~~~~~~~~~~~~~
119+
120+
**type**: ``bool`` **default**: ``true``
121+
122+
By default, hostnames are considered valid only when they are fully qualified
123+
and include their TLDs (top-level domain names). For instance, ``example.com``
124+
is valid but ``example`` is not.
125+
126+
Set this option to ``false`` to not require any TLD in the hostnames.
127+
128+
.. note::
129+
130+
This constraint does not validate that the given TLD value is included in
131+
the `list of official top-level domains`_ (because that list is growing
132+
continuously and it's hard to keep track of it).
133+
134+
.. _`RFC 2606`: https://tools.ietf.org/html/rfc2606
135+
.. _`list of official top-level domains`: https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains

‎reference/constraints/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ String Constraints
1919
* :doc:`Length </reference/constraints/Length>`
2020
* :doc:`Url </reference/constraints/Url>`
2121
* :doc:`Regex </reference/constraints/Regex>`
22+
* :doc:`Hostname </reference/constraints/Hostname>`
2223
* :doc:`Ip </reference/constraints/Ip>`
2324
* :doc:`Json</reference/constraints/Json>`
2425
* :doc:`Uuid</reference/constraints/Uuid>`

0 commit comments

Comments
 (0)
0