diff --git a/reference/constraints/CssColor.rst b/reference/constraints/CssColor.rst index 894325cb2e4..eb04df19b4c 100644 --- a/reference/constraints/CssColor.rst +++ b/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"> - + + + + - - + + - + - - + + @@ -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)``