minor #19965 [Validator] Add the Yaml constraint (javiereguiluz)

This PR was squashed before being merged into the 7.2 branch.

Discussion
----------

[Validator] Add the Yaml constraint

Fixes #19963.

Ping `@xabbuh` for help 🙏  I don't know how to express this --> `YamlParser::PARSE_CONSTANT | YamlParser::PARSE_CUSTOM_TAGS | Yaml::PARSE_DATETIME` in YAML and XML config formats. Can you help me? Thanks!

Commits
-------

688db28 [Validator] Add the Yaml constraint

components/yaml.rst

@@ -214,6 +214,8 @@ During the parsing of the YAML contents, all the ``_`` characters are removed
 from the numeric literal contents, so there is not a limit in the number of
 underscores you can include or the way you group contents.
 
+.. _yaml-flags:
+
 Advanced Usage: Flags
 ---------------------
 

reference/constraints/Yaml.rst

@@ -0,0 +1,152 @@
+Yaml
+====
+
+Validates that a value has valid `YAML`_ syntax.
+
+.. versionadded:: 7.2
+
+ The ``Yaml`` constraint was introduced in Symfony 7.2.
+
+========== ===================================================================
+Applies to :ref:`property or method <validation-property-target>`
+Class :class:`Symfony\\Component\\Validator\\Constraints\\Yaml`
+Validator :class:`Symfony\\Component\\Validator\\Constraints\\YamlValidator`
+========== ===================================================================
+
+Basic Usage
+-----------
+
+The ``Yaml`` constraint can be applied to a property or a "getter" method:
+
+.. configuration-block::
+
+ .. code-block:: php-attributes
+
+ // src/Entity/Report.php
+ namespace App\Entity;
+
+ use Symfony\Component\Validator\Constraints as Assert;
+
+ class Report
+ {
+ #[Assert\Yaml(
+ message: "Your configuration doesn't have valid YAML syntax."
+ )]
+ private string $customConfiguration;
+ }
+
+ .. code-block:: yaml
+
+ # config/validator/validation.yaml
+ App\Entity\Report:
+ properties:
+ customConfiguration:
+ - Yaml:
+ message: Your configuration doesn't have valid YAML syntax.
+
+ .. code-block:: xml
+
+ <!-- config/validator/validation.xml -->
+ <?xml version="1.0" encoding="UTF-8" ?>
+ <constraint-mapping xmlns="https://symfony.com/schema/dic/constraint-mapping"
+ xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="https://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
+
+ <class name="App\Entity\Report">
+ <property name="customConfiguration">
+ <constraint name="Yaml">
+ <option name="message">Your configuration doesn't have valid YAML syntax.</option>
+ </constraint>
+ </property>
+ </class>
+ </constraint-mapping>
+
+ .. code-block:: php
+
+ // src/Entity/Report.php
+ namespace App\Entity;
+
+ use Symfony\Component\Validator\Constraints as Assert;
+ use Symfony\Component\Validator\Mapping\ClassMetadata;
+
+ class Report
+ {
+ public static function loadValidatorMetadata(ClassMetadata $metadata): void
+ {
+ $metadata->addPropertyConstraint('customConfiguration', new Assert\Yaml([
+ 'message' => 'Your configuration doesn\'t have valid YAML syntax.',
+ ]));
+ }
+ }
+
+Options
+-------
+
+``flags``
+~~~~~~~~~
+
+**type**: ``integer`` **default**: ``0``
+
+This option enables optional features of the YAML parser when validating contents.
+Its value is a combination of one or more of the :ref:`flags defined by the Yaml component <yaml-flags>`:
+
+.. configuration-block::
+
+ .. code-block:: php-attributes
+
+ // src/Entity/Report.php
+ namespace App\Entity;
+
+ use Symfony\Component\Validator\Constraints as Assert;
+ use Symfony\Component\Yaml\Yaml;
+
+ class Report
+ {
+ #[Assert\Yaml(
+ message: "Your configuration doesn't have valid YAML syntax.",
+ flags: Yaml::PARSE_CONSTANT | Yaml::PARSE_CUSTOM_TAGS | Yaml::PARSE_DATETIME,
+ )]
+ private string $customConfiguration;
+ }
+
+ .. code-block:: php
+
+ // src/Entity/Report.php
+ namespace App\Entity;
+
+ use Symfony\Component\Validator\Constraints as Assert;
+ use Symfony\Component\Validator\Mapping\ClassMetadata;
+ use Symfony\Component\Yaml\Yaml;
+
+ class Report
+ {
+ public static function loadValidatorMetadata(ClassMetadata $metadata): void
+ {
+ $metadata->addPropertyConstraint('customConfiguration', new Assert\Yaml([
+ 'message' => 'Your configuration doesn\'t have valid YAML syntax.',
+ 'flags' => Yaml::PARSE_CONSTANT | Yaml::PARSE_CUSTOM_TAGS | Yaml::PARSE_DATETIME,
+ ]));
+ }
+ }
+
+``message``
+~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``This value is not valid YAML.``
+
+This message shown if the underlying data is not a valid YAML value.
+
+You can use the following parameters in this message:
+
+=============== ==============================================================
+Parameter Description
+=============== ==============================================================
+``{{ error }}`` The full error message from the YAML parser
+``{{ line }}`` The line where the YAML syntax error happened
+=============== ==============================================================
+
+.. include:: /reference/constraints/_groups-option.rst.inc
+
+.. include:: /reference/constraints/_payload-option.rst.inc
+
+.. _`YAML`: https://en.wikipedia.org/wiki/YAML