diff --git a/reference/constraints/Charset.rst b/reference/constraints/Charset.rst new file mode 100644 index 00000000000..6f8592fa5e1 --- /dev/null +++ b/reference/constraints/Charset.rst @@ -0,0 +1,112 @@ +Charset +======= + +.. versionadded:: 7.1 + + The ``Charset`` constraint was introduced in Symfony 7.1. + +Validates that a string is encoded in a given charset. + +========== ===================================================================== +Applies to :ref:`property or method ` +Class :class:`Symfony\\Component\\Validator\\Constraints\\Charset` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\CharsetValidator` +========== ===================================================================== + +Basic Usage +----------- + +If you wanted to ensure that the ``content`` property of an ``FileDTO`` +class uses UTF-8, you could do the following: + +.. configuration-block:: + + .. code-block:: php-attributes + + // src/Entity/FileDTO.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class FileDTO + { + #[Assert\Charset('UTF-8')] + protected string $content; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\FileDTO: + properties: + content: + - Charset: 'UTF-8' + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/FileDTO.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + use Symfony\Component\Validator\Mapping\ClassMetadata; + + class FileDTO + { + // ... + + public static function loadValidatorMetadata(ClassMetadata $metadata): void + { + $metadata->addPropertyConstraint('content', new Assert\Charset('UTF-8')); + } + } + +Options +------- + +``encodings`` +~~~~~~~~~~~~~ + +**type**: ``array`` | ``string`` **default**: ``[]`` + +An encoding or a set of encodings to check against. If you pass an array of +encodings, the validator will check if the value is encoded in *any* of the +encodings. This option accept any value that can be passed to +:phpfunction:`mb_detect_encoding()`. + +.. include:: /reference/constraints/_groups-option.rst.inc + +``message`` +~~~~~~~~~~~ + +**type**: ``string`` **default**: ``The detected encoding "{{ detected }}" does not match one of the accepted encoding: "{{ encodings }}".`` + +This is the message that will be shown if the value does not match any of the +accepted encodings. + +You can use the following parameters in this message: + +=================== ============================================================== +Parameter Description +=================== ============================================================== +``{{ detected }}`` The detected encoding +``{{ encodings }}`` The accepted encodings +=================== ============================================================== + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc index 2fa03ac9a3e..a9692062d28 100644 --- a/reference/constraints/map.rst.inc +++ b/reference/constraints/map.rst.inc @@ -31,6 +31,7 @@ String Constraints * :doc:`PasswordStrength ` * :doc:`CssColor ` * :doc:`NoSuspiciousCharacters ` +* :doc:`Charset ` Comparison Constraints ~~~~~~~~~~~~~~~~~~~~~~