diff --git a/reference/constraints.rst b/reference/constraints.rst index 317a836e396..3f2e5b909ec 100644 --- a/reference/constraints.rst +++ b/reference/constraints.rst @@ -17,6 +17,7 @@ Validation Constraints Reference constraints/Length constraints/Url constraints/Regex + constraints/Hostname constraints/Ip constraints/Uuid constraints/Json diff --git a/reference/constraints/Hostname.rst b/reference/constraints/Hostname.rst new file mode 100644 index 00000000000..4cbe606ccb4 --- /dev/null +++ b/reference/constraints/Hostname.rst @@ -0,0 +1,135 @@ +Hostname +======== + +This constraint ensures that the given value is a valid host name (internally it +uses the ``FILTER_VALIDATE_DOMAIN`` option of the :phpfunction:`filter_var` PHP +function). + +.. versionadded:: 5.1 + + The ``Hostname`` constraint was introduced in Symfony 5.1. + +========== =================================================================== +Applies to :ref:`property or method ` +Options - `groups`_ + - `message`_ + - `payload`_ + - `requireTld`_ +Class :class:`Symfony\\Component\\Validator\\Constraints\\Hostname` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\HostnameValidator` +========== =================================================================== + +Basic Usage +----------- + +To use the Hostname validator, apply it to a property on an object that +will contain a host name. + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/Entity/ServerSettings.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class ServerSettings + { + /** + * @Assert\Hostname(message="The server name must be a valid hostname.") + */ + protected $name; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\ServerSettings: + properties: + name: + - Hostname: + message: The server name must be a valid hostname. + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/ServerSettings.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + use Symfony\Component\Validator\Mapping\ClassMetadata; + + class ServerSettings + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('name', new Assert\Hostname([ + 'message' => 'The server name must be a valid hostname.', + ])); + } + } + +The following top-level domains (TLD) are reserved according to `RFC 2606`_ and +that's why hostnames containing them are not considered valid: ``.example``, +``.invalid``, ``.localhost``, and ``.test``. + +.. include:: /reference/constraints/_empty-values-are-valid.rst.inc + +Options +------- + +.. include:: /reference/constraints/_groups-option.rst.inc + +``message`` +~~~~~~~~~~~ + +**type**: ``string`` **default**: ``This value is not a valid hostname.`` + +The default message supplied when the value is not a valid hostname. + +You can use the following parameters in this message: + +=============== ============================================================== +Parameter Description +=============== ============================================================== +``{{ value }}`` The current (invalid) value +=============== ============================================================== + +.. include:: /reference/constraints/_payload-option.rst.inc + +``requireTld`` +~~~~~~~~~~~~~~ + +**type**: ``bool`` **default**: ``true`` + +By default, hostnames are considered valid only when they are fully qualified +and include their TLDs (top-level domain names). For instance, ``example.com`` +is valid but ``example`` is not. + +Set this option to ``false`` to not require any TLD in the hostnames. + +.. note:: + + This constraint does not validate that the given TLD value is included in + the `list of official top-level domains`_ (because that list is growing + continuously and it's hard to keep track of it). + +.. _`RFC 2606`: https://tools.ietf.org/html/rfc2606 +.. _`list of official top-level domains`: https://en.wikipedia.org/wiki/List_of_Internet_top-level_domains diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc index 337798c51da..4fb03e6534c 100644 --- a/reference/constraints/map.rst.inc +++ b/reference/constraints/map.rst.inc @@ -19,6 +19,7 @@ String Constraints * :doc:`Length ` * :doc:`Url ` * :doc:`Regex ` +* :doc:`Hostname ` * :doc:`Ip ` * :doc:`Json` * :doc:`Uuid`