minor #15906 [Validator] Some tweaks to CssColor constraint (javiereguiluz)

This PR was merged into the 5.4 branch.

Discussion
----------

[Validator] Some tweaks to CssColor constraint

This tweaks the great work made by `@welcoMattic` in #14965.

It's mostly minor tweaks ... but I also expanded the "basic usage" example to show the case of not adding any parameters to the constraint, which is a common case when you just want to allow any of the valid CSS color formats.

Commits
-------

07e38b7 [Validator] Some tweaks to CssColor constraint

Author: javiereguiluz

reference/constraints/CssColor.rst

@@ -1,6 +1,10 @@
 CssColor
 =========
 
+.. versionadded:: 5.4
+
+    The ``CssColor`` constraint was introduced in Symfony 5.4.
+
 Validates that a value is a valid CSS color. The underlying value is
 casted to a string before being validated.
 
@@ -17,6 +21,12 @@ Validator   :class:`Symfony\\Component\\Validator\\Constraints\\CssColorValidato
 Basic Usage
 -----------
 
+In the following example, the ``$defaultColor`` value must be a CSS color
+defined in any of the valid CSS formats (e.g. ``red``, ``#369``,
+``hsla(0, 0%, 20%, 0.4)``); the ``$accentColor`` must be a CSS color defined in
+hexadecimal format; and ``$currentColor`` must be a CSS color defined as any of
+the named CSS colors:
+
 .. configuration-block::
 
     .. code-block:: php-annotations
@@ -28,18 +38,26 @@ Basic Usage
 
         class Bulb
         {
+            /**
+             * @Assert\CssColor
+             */
+            protected $defaultColor;
+
             /**
              * @Assert\CssColor(
-             *     formats = { Assert\CssColor::HEX_LONG }
-             *     message = "The color '{{ value }}' is not a valid CSS color."
+             *     formats = Assert\CssColor::HEX_LONG,
+             *     message = "The accent color must be a 6-character hexadecimal color."
              * )
              */
-            protected $defaultColor;
+            protected $accentColor;
 
             /**
              * @Assert\CssColor(
-             *     formats = Assert\CssColor::BASIC_NAMED_COLORS
-             *     message = "The color '{{ value }}' is not a valid CSS color."
+             *     formats = {
+             *         Assert\CssColor::BASIC_NAMED_COLORS,
+             *         Assert\CssColor::EXTENDED_NAMED_COLORS
+             *     },
+             *     message = "The color '{{ value }}' is not a valid CSS color name."
              * )
              */
             protected $currentColor;
@@ -54,15 +72,18 @@ Basic Usage
 
         class Bulb
         {
+            #[Assert\CssColor]
+            protected $defaultColor;
+
             #[Assert\CssColor(
-                formats: [Assert\CssColor::HEX_LONG]
-                message: 'The color '{{ value }}' is not a valid CSS color.',
+                formats: Assert\CssColor::HEX_LONG,
+                message: 'The accent color must be a 6-character hexadecimal color.',
             )]
-            protected $defaultColor;
+            protected $accentColor;
 
             #[Assert\CssColor(
-                formats: Assert\CssColor::BASIC_NAMED_COLORS
-                message: 'The color '{{ value }}' is not a valid CSS color.',
+                formats: [Assert\CssColor::BASIC_NAMED_COLORS, Assert\CssColor::EXTENDED_NAMED_COLORS],
+                message: 'The color '{{ value }}' is not a valid CSS color name.',
             )]
             protected $currentColor;
         }
@@ -73,13 +94,17 @@ Basic Usage
         App\Entity\Bulb:
             properties:
                 defaultColor:
+                    - CssColor: ~
+                accentColor:
                     - CssColor:
-                        formats: [ !php/const Symfony\Component\Validator\Constraints\CssColor::HEX_LONG ]
-                        message: The color "{{ value }}" is not a valid CSS color.
+                        formats: !php/const Symfony\Component\Validator\Constraints\CssColor::HEX_LONG
+                        message: The accent color must be a 6-character hexadecimal color.
                 currentColor:
                     - CssColor:
-                        formats: !php/const Symfony\Component\Validator\Constraints\CssColor::BASIC_NAMED_COLORS
-                        message: The color "{{ value }}" is not a valid CSS color.
+                        formats:
+                            - !php/const Symfony\Component\Validator\Constraints\CssColor::BASIC_NAMED_COLORS
+                            - !php/const Symfony\Component\Validator\Constraints\CssColor::EXTENDED_NAMED_COLORS
+                        message: The color "{{ value }}" is not a valid CSS color name.
 
     .. code-block:: xml
 
@@ -90,18 +115,22 @@ Basic Usage
             xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
 
             <class name="App\Entity\Bulb">
-                <property name="currentColor">
+                <property name="defaultColor">
+                    <constraint name="CssColor"/>
+                </property>
+                <property name="accentColor">
                     <constraint name="CssColor">
-                        <option name="formats">
-                            <value>hex_long</value>
-                        </option>
-                        <option name="message">The color "{{ value }}" is not a valid CSS color.</option>
+                        <option name="formats">hex_long</option>
+                        <option name="message">The accent color must be a 6-character hexadecimal color.</option>
                     </constraint>
                 </property>
-                <property name="defaultColor">
+                <property name="currentColor">
                     <constraint name="CssColor">
-                        <option name="formats">basic_named_colors</option>
-                        <option name="message">The color "{{ value }}" is not a valid CSS color.</option>
+                        <option name="formats">
+                            <value>basic_named_colors</value>
+                            <value>extended_named_colors</value>
+                        </option>
+                        <option name="message">The color "{{ value }}" is not a valid CSS color name.</option>
                     </constraint>
                 </property>
             </class>
@@ -119,14 +148,16 @@ Basic Usage
         {
             public static function loadValidatorMetadata(ClassMetadata $metadata)
             {
-                $metadata->addPropertyConstraint('defaultColor', new Assert\CssColor([
-                    'formats' => [Assert\CssColor::HEX_LONG],
-                    'message' => 'The color "{{ value }}" is not a valid CSS color.',
+                $metadata->addPropertyConstraint('defaultColor', new Assert\CssColor());
+
+                $metadata->addPropertyConstraint('accentColor', new Assert\CssColor([
+                    'formats' => Assert\CssColor::HEX_LONG,
+                    'message' => 'The accent color must be a 6-character hexadecimal color.',
                 ]));
 
                 $metadata->addPropertyConstraint('currentColor', new Assert\CssColor([
-                    'formats' => Assert\CssColor::BASIC_NAMED_COLORS,
-                    'message' => 'The color "{{ value }}" is not a valid CSS color.',
+                    'formats' => [Assert\CssColor::BASIC_NAMED_COLORS, Assert\CssColor::EXTENDED_NAMED_COLORS],
+                    'message' => 'The color "{{ value }}" is not a valid CSS color name.',
                 ]));
             }
         }
@@ -158,8 +189,10 @@ formats
 
 **type**: ``string`` | ``array``
 
-This option is optional and defines the pattern the CSS color is validated against.
-Valid values are:
+By default, this constraint considers valid any of the many ways of defining
+CSS colors. Use the ``formats`` option to restrict which CSS formats are allowed.
+These are the available formats (which are also defined as PHP constants; e.g.
+``Assert\CssColor::HEX_LONG``):
 
 * ``hex_long``
 * ``hex_long_with_alpha``
@@ -177,88 +210,99 @@ Valid values are:
 hex_long
 ........
 
-A regular expression. Allows all values which represent a CSS color
-of 6 characters (in addition of the leading ``#``) and contained in ranges: 0 to 9 and A to F (case insensitive).
+A regular expression. Allows all values which represent a CSS color of 6
+characters (in addition of the leading ``#``) and contained in ranges: ``0`` to
+``9`` and ``A`` to ``F`` (case insensitive).
 
 Examples: ``#2F2F2F``, ``#2f2f2f``
 
 hex_long_with_alpha
 ...................
 
-A regular expression. Allows all values which represent a CSS color with alpha part
-of 8 characters (in addition of the leading ``#``) and contained in ranges: 0 to 9 and A to F (case insensitive).
+A regular expression. Allows all values which represent a CSS color with alpha
+part of 8 characters (in addition of the leading ``#``) and contained in
+ranges: ``0`` to ``9`` and ``A`` to ``F`` (case insensitive).
 
 Examples: ``#2F2F2F80``, ``#2f2f2f80``
 
 hex_short
 .........
 
-A regular expression. Allows all values which represent a CSS color
-of strictly 3 characters (in addition of the leading ``#``) and contained in ranges: 0 to 9 and A to F (case insensitive).
+A regular expression. Allows all values which represent a CSS color of strictly
+3 characters (in addition of the leading ``#``) and contained in ranges: ``0``
+to ``9`` and ``A`` to ``F`` (case insensitive).
 
 Examples: ``#CCC``, ``#ccc``
 
 hex_short_with_alpha
 ....................
 
-A regular expression. Allows all values which represent a CSS color with alpha part
-of strictly 4 characters (in addition of the leading ``#``) and contained in ranges: 0 to 9 and A to F (case insensitive).
+A regular expression. Allows all values which represent a CSS color with alpha
+part of strictly 4 characters (in addition of the leading ``#``) and contained
+in ranges: ``0`` to ``9`` and ``A`` to ``F`` (case insensitive).
 
 Examples: ``#CCC8``, ``#ccc8``
 
 basic_named_colors
 ..................
 
-Accordingly to the `W3C list of basic named colors`_, it allows to use colors by their names (case insensitive).
+Any of the valid color names defined in the `W3C list of basic named colors`_
+(case insensitive).
 
 Examples: ``black``, ``red``, ``green``
 
 extended_named_colors
 .....................
 
-Accordingly to the `W3C list of extended named colors`_, it allows to use colors by their names (case insensitive).
+Any of the valid color names defined in the `W3C list of extended named colors`_
+(case insensitive).
 
 Examples: ``aqua``, ``brown``, ``chocolate``
 
 system_colors
 .............
 
-Accordingly to the `CSS WG list of system colors`_, it allows to use colors by their names (case insensitive).
+Any of the valid color names defined in the `CSS WG list of system colors`_
+(case insensitive).
 
 Examples: ``LinkText``, ``VisitedText``, ``ActiveText``, ``ButtonFace``, ``ButtonText``
 
 keywords
 ........
 
-Accordingly to the `CSS WG list of keywords`_, it allows to use colors by their names (case insensitive).
+Any of the valid keywords defined in the `CSS WG list of keywords`_ (case insensitive).
 
 Examples: ``transparent``, ``currentColor``
 
 rgb
 ...
 
-A regular expression. Allows all values which represent a CSS color following th RGB notation, with or without space between values.
+A regular expression. Allows all values which represent a CSS color following
+the RGB notation, with or without space between values.
 
 Examples: ``rgb(255, 255, 255)``, ``rgb(255,255,255)``
 
 rgba
 ....
 
-A regular expression. Allows all values which represent a CSS color with alpha part following th RGB notation, with or without space between values.
+A regular expression. Allows all values which represent a CSS color with alpha
+part following the RGB notation, with or without space between values.
 
 Examples: ``rgba(255, 255, 255, 0.3)``, ``rgba(255,255,255,0.3)``
 
 hsl
 ...
 
-A regular expression. Allows all values which represent a CSS color following th HSL notation, with or without space between values.
+A regular expression. Allows all values which represent a CSS color following
+the HSL notation, with or without space between values.
 
 Examples: ``hsl(0, 0%, 20%)``, ``hsl(0,0%,20%)``
 
 hsla
 ....
 
-A regular expression. Allows all values which represent a CSS color with alpha part following th HSLA notation, with or without space between values.
+A regular expression. Allows all values which represent a CSS color with alpha
+part following the HSLA notation, with or without space between values.
 
 Examples: ``hsla(0, 0%, 20%, 0.4)``, ``hsla(0,0%,20%,0.4)``