diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index c2eb9a6a4a1..52470ef8dfb 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -214,6 +214,7 @@ * :doc:`/cookbook/validation/index` * :doc:`/cookbook/validation/custom_constraint` + * :doc:`/cookbook/validation/severity` * :doc:`/cookbook/web_server/index` diff --git a/cookbook/validation/index.rst b/cookbook/validation/index.rst index 3712610011d..d194c118025 100644 --- a/cookbook/validation/index.rst +++ b/cookbook/validation/index.rst @@ -5,3 +5,4 @@ Validation :maxdepth: 2 custom_constraint + severity diff --git a/cookbook/validation/severity.rst b/cookbook/validation/severity.rst new file mode 100644 index 00000000000..cb638135277 --- /dev/null +++ b/cookbook/validation/severity.rst @@ -0,0 +1,165 @@ +.. index:: + single: Validation; Error Levels + single: Validation; Payload + +How to Handle Different Error Levels +==================================== + +Sometimes, you may want to display constraint validation error messages differently +based on some rules. For example, you have a registration form for new users +where they enter some personal information and choose their authentication +credentials. They would have to choose a username and a secure password, +but providing bank account information would be optional. Nonetheless, you +want to make sure that these optional data, if entered, are still valid, +but display them differently. + +The process to achieve this behavior consists of two steps: + +#. Apply different error levels to the validation constraints; +#. Customize your error messages depending on the configured error level. + +1. Assigning the Error Level +---------------------------- + +.. versionadded:: 2.6 + The ``payload`` option was introduced in Symfony 2.6. + +Use the ``payload`` option to configure the error level for each constraint: + +.. configuration-block:: + + .. code-block:: yaml + + # src/AppBundle/Resources/config/validation.yml + AppBundle\Entity\User: + properties: + username: + - NotBlank: + payload: + severity: error + password: + - NotBlank: + payload: + severity: error + bankAccountNumber: + - Iban: + payload: + severity: warning + + .. code-block:: php-annotations + + // src/AppBundle/Entity/User.php + namespace AppBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class User + { + /** + * @Assert\NotBlank(payload = {severity = "error"}) + */ + protected $username; + + /** + * @Assert\NotBlank(payload = {severity = "error"}) + */ + protected $password; + + /** + * @Assert\Iban(payload = {severity = "warning"}) + */ + protected $bankAccountNumber; + } + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + .. code-block:: php + + // src/AppBundle/Entity/User.php + namespace AppBundle\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class User + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('username', new Assert\NotBlank(array( + 'payload' => array('severity' => 'error'), + ))); + $metadata->addPropertyConstraint('password', new Assert\NotBlank(array( + 'payload' => array('severity' => 'error'), + ))); + $metadata->addPropertyConstraint('bankAccountNumber', new Assert\Iban(array( + 'payload' => array('severity' => 'warning'), + ))); + } + } + +2. Customize the Error Message Template +--------------------------------------- + +.. versionadded:: 2.6 + The ``getConstraint()`` method in the ``ConstraintViolation`` class was + introduced in Symfony 2.6. + +When validating the ``User`` object failed, you can retrieve the constraint +that caused a particular failure using the +:method:`Symfony\\Component\\Validator\\ConstraintViolation::getConstraint` +method. Each constraint exposes the attached payload as a public property:: + + // a constraint validation failure, instance of + // Symfony\Component\Validator\ConstraintViolation + $constraintViolation = ...; + $constraint = $constraintViolation->getConstraint(); + $severity = isset($constraint->payload['severity']) ? $constraint->payload['severity'] : null; + +For example, you can leverage this to customize the ``form_errors`` block +such that the severity is added as an additional HTML class: + +.. code-block:: html+jinja + + {%- block form_errors -%} + {%- if errors|length > 0 -%} + + {%- endif -%} + {%- endblock form_errors -%} diff --git a/reference/constraints/All.rst b/reference/constraints/All.rst index 5f5aa859a3d..8fb48ffaf0d 100644 --- a/reference/constraints/All.rst +++ b/reference/constraints/All.rst @@ -8,6 +8,7 @@ you to apply a collection of constraints to each element of the array. | Applies to | :ref:`property or method ` | +----------------+------------------------------------------------------------------------+ | Options | - `constraints`_ | +| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\All` | +----------------+------------------------------------------------------------------------+ @@ -107,3 +108,5 @@ constraints This required option is the array of validation constraints that you want to apply to each element of the underlying array. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Blank.rst b/reference/constraints/Blank.rst index 5679aa5bf56..1823675f571 100644 --- a/reference/constraints/Blank.rst +++ b/reference/constraints/Blank.rst @@ -10,6 +10,7 @@ blank, see :doc:`/reference/constraints/NotBlank`. | Applies to | :ref:`property or method ` | +----------------+-----------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Blank` | +----------------+-----------------------------------------------------------------------+ @@ -87,3 +88,5 @@ message **type**: ``string`` **default**: ``This value should be blank.`` This is the message that will be shown if the value is not blank. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Callback.rst b/reference/constraints/Callback.rst index e0a21e4b2e0..41739752d40 100644 --- a/reference/constraints/Callback.rst +++ b/reference/constraints/Callback.rst @@ -26,6 +26,7 @@ can do anything, including creating and assigning validation errors. | Applies to | :ref:`class ` | +----------------+------------------------------------------------------------------------+ | Options | - :ref:`callback ` | +| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Callback` | +----------------+------------------------------------------------------------------------+ @@ -302,3 +303,5 @@ instance as only argument. Static or closure callbacks receive the validated object as the first argument and the :class:`Symfony\\Component\\Validator\\ExecutionContextInterface` instance as the second argument. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/CardScheme.rst b/reference/constraints/CardScheme.rst index b589b4d334a..7a6b7136418 100644 --- a/reference/constraints/CardScheme.rst +++ b/reference/constraints/CardScheme.rst @@ -10,6 +10,7 @@ through a payment gateway. +----------------+--------------------------------------------------------------------------+ | Options | - `schemes`_ | | | - `message`_ | +| | - `payload`_ | +----------------+--------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\CardScheme` | +----------------+--------------------------------------------------------------------------+ @@ -124,4 +125,6 @@ message The message shown when the value does not pass the ``CardScheme`` check. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`Wikipedia: Issuer identification number (IIN)`: http://en.wikipedia.org/wiki/Bank_card_number#Issuer_identification_number_.28IIN.29 diff --git a/reference/constraints/Choice.rst b/reference/constraints/Choice.rst index 28f1628d042..1e0d9345ad6 100644 --- a/reference/constraints/Choice.rst +++ b/reference/constraints/Choice.rst @@ -18,6 +18,7 @@ an array of items is one of those valid choices. | | - `minMessage`_ | | | - `maxMessage`_ | | | - `strict`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Choice` | +----------------+-----------------------------------------------------------------------+ @@ -89,11 +90,11 @@ If your valid choice list is simple, you can pass them in directly via the use Symfony\Component\Validator\Mapping\ClassMetadata; use Symfony\Component\Validator\Constraints as Assert; - + class Author { protected $gender; - + public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('gender', new Assert\Choice(array( @@ -176,11 +177,11 @@ constraint. use Symfony\Component\Validator\Mapping\ClassMetadata; use Symfony\Component\Validator\Constraints as Assert; - + class Author { protected $gender; - + public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('gender', new Assert\Choice(array( @@ -244,11 +245,11 @@ you can pass the class name and the method as an array. use Symfony\Component\Validator\Mapping\ClassMetadata; use Symfony\Component\Validator\Constraints as Assert; - + class Author { protected $gender; - + public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('gender', new Assert\Choice(array( @@ -349,3 +350,5 @@ strict If true, the validator will also check the type of the input value. Specifically, this value is passed to as the third argument to the PHP :phpfunction:`in_array` method when checking to see if a value is in the valid choices array. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index 2c93325da2f..53e2ddeaeeb 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -18,6 +18,7 @@ and that extra keys are not present. | | - `extraFieldsMessage`_ | | | - `allowMissingFields`_ | | | - `missingFieldsMessage`_ | +| | - `payload`_ | +----------------+--------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Collection` | +----------------+--------------------------------------------------------------------------+ @@ -328,3 +329,5 @@ missingFieldsMessage The message shown if `allowMissingFields`_ is false and one or more fields are missing from the underlying collection. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Count.rst b/reference/constraints/Count.rst index 0e1f0fbe51c..77cb3ac40c9 100644 --- a/reference/constraints/Count.rst +++ b/reference/constraints/Count.rst @@ -12,6 +12,7 @@ element count is *between* some minimum and maximum value. | | - `minMessage`_ | | | - `maxMessage`_ | | | - `exactMessage`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Count` | +----------------+---------------------------------------------------------------------+ @@ -139,3 +140,5 @@ exactMessage The message that will be shown if min and max values are equal and the underlying collection elements count is not exactly this value. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Country.rst b/reference/constraints/Country.rst index f6dc5c10446..6f9b7ed1d09 100644 --- a/reference/constraints/Country.rst +++ b/reference/constraints/Country.rst @@ -7,6 +7,7 @@ Validates that a value is a valid `ISO 3166-1 alpha-2`_ country code. | Applies to | :ref:`property or method ` | +----------------+------------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Country` | +----------------+------------------------------------------------------------------------+ @@ -82,4 +83,6 @@ message This message is shown if the string is not a valid country code. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`ISO 3166-1 alpha-2`: http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes diff --git a/reference/constraints/Currency.rst b/reference/constraints/Currency.rst index 553c2be4ec1..55483843a39 100644 --- a/reference/constraints/Currency.rst +++ b/reference/constraints/Currency.rst @@ -10,6 +10,7 @@ Validates that a value is a valid `3-letter ISO 4217`_ currency name. | Applies to | :ref:`property or method` | +----------------+---------------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Currency` | +----------------+---------------------------------------------------------------------------+ @@ -88,4 +89,6 @@ message This is the message that will be shown if the value is not a valid currency. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`3-letter ISO 4217`: http://en.wikipedia.org/wiki/ISO_4217 diff --git a/reference/constraints/Date.rst b/reference/constraints/Date.rst index 88ff0aea46c..f972895cac5 100644 --- a/reference/constraints/Date.rst +++ b/reference/constraints/Date.rst @@ -9,6 +9,7 @@ valid YYYY-MM-DD format. | Applies to | :ref:`property or method ` | +----------------+--------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+--------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Date` | +----------------+--------------------------------------------------------------------+ @@ -83,3 +84,5 @@ message **type**: ``string`` **default**: ``This value is not a valid date.`` This message is shown if the underlying data is not a valid date. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/DateTime.rst b/reference/constraints/DateTime.rst index c6897b9edf6..c7420b75ad9 100644 --- a/reference/constraints/DateTime.rst +++ b/reference/constraints/DateTime.rst @@ -9,6 +9,7 @@ a valid YYYY-MM-DD HH:MM:SS format. | Applies to | :ref:`property or method ` | +----------------+------------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\DateTime` | +----------------+------------------------------------------------------------------------+ @@ -83,3 +84,5 @@ message **type**: ``string`` **default**: ``This value is not a valid datetime.`` This message is shown if the underlying data is not a valid datetime. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Email.rst b/reference/constraints/Email.rst index 9df3332a749..69e9e776f2a 100644 --- a/reference/constraints/Email.rst +++ b/reference/constraints/Email.rst @@ -11,6 +11,7 @@ cast to a string before being validated. | | - `message`_ | | | - `checkMX`_ | | | - `checkHost`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Email` | +----------------+---------------------------------------------------------------------+ @@ -99,7 +100,7 @@ strict **type**: ``boolean`` **default**: ``false`` When false, the email will be validated against a simple regular expression. -If true, then the `egulias/email-validator`_ library is required to perform +If true, then the `egulias/email-validator`_ library is required to perform an RFC compliant validation. message @@ -126,4 +127,6 @@ If true, then the :phpfunction:`checkdnsrr` PHP function will be used to check the validity of the MX *or* the A *or* the AAAA record of the host of the given email. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _egulias/email-validator: https://packagist.org/packages/egulias/email-validator diff --git a/reference/constraints/EqualTo.rst b/reference/constraints/EqualTo.rst index c57fce55e11..88a5ab812ef 100644 --- a/reference/constraints/EqualTo.rst +++ b/reference/constraints/EqualTo.rst @@ -18,6 +18,7 @@ force that a value is *not* equal, see :doc:`/reference/constraints/NotEqualTo`. +----------------+-----------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\EqualTo` | +----------------+-----------------------------------------------------------------------+ @@ -104,3 +105,5 @@ message **type**: ``string`` **default**: ``This value should be equal to {{ compared_value }}.`` This is the message that will be shown if the value is not equal. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Expression.rst b/reference/constraints/Expression.rst index b3d8f386fa1..14cb0af2925 100644 --- a/reference/constraints/Expression.rst +++ b/reference/constraints/Expression.rst @@ -14,6 +14,7 @@ gives you similar flexibility. +----------------+-----------------------------------------------------------------------------------------------+ | Options | - :ref:`expression ` | | | - `message`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Expression` | +----------------+-----------------------------------------------------------------------------------------------+ @@ -258,3 +259,5 @@ message **type**: ``string`` **default**: ``This value is not valid.`` The default message supplied when the expression evaluates to false. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/False.rst b/reference/constraints/False.rst index b3d241881e7..483c25c1eef 100644 --- a/reference/constraints/False.rst +++ b/reference/constraints/False.rst @@ -11,6 +11,7 @@ Also see :doc:`True `. | Applies to | :ref:`property or method ` | +----------------+---------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\False` | +----------------+---------------------------------------------------------------------+ @@ -115,3 +116,5 @@ message **type**: ``string`` **default**: ``This value should be false.`` This message is shown if the underlying data is not false. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/File.rst b/reference/constraints/File.rst index eb45c931475..503d0e1995b 100644 --- a/reference/constraints/File.rst +++ b/reference/constraints/File.rst @@ -30,6 +30,7 @@ form type. | | - `uploadIniSizeErrorMessage`_ | | | - `uploadFormSizeErrorMessage`_ | | | - `uploadErrorMessage`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\File` | +----------------+---------------------------------------------------------------------+ @@ -276,6 +277,7 @@ The message that is displayed if the uploaded file could not be uploaded for some unknown reason, such as the file upload failed or it couldn't be written to disk. +.. include:: /reference/constraints/_payload-option.rst.inc .. _`IANA website`: http://www.iana.org/assignments/media-types/index.html .. _`Wikipedia: Binary prefix`: http://en.wikipedia.org/wiki/Binary_prefix diff --git a/reference/constraints/GreaterThan.rst b/reference/constraints/GreaterThan.rst index 2d773953bcd..f18958061ea 100644 --- a/reference/constraints/GreaterThan.rst +++ b/reference/constraints/GreaterThan.rst @@ -14,6 +14,7 @@ than another value, see :doc:`/reference/constraints/LessThan`. +----------------+---------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThan` | +----------------+---------------------------------------------------------------------------+ @@ -101,3 +102,5 @@ message This is the message that will be shown if the value is not greater than the comparison value. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/GreaterThanOrEqual.rst b/reference/constraints/GreaterThanOrEqual.rst index 9d4cf37ecc5..b4169479f94 100644 --- a/reference/constraints/GreaterThanOrEqual.rst +++ b/reference/constraints/GreaterThanOrEqual.rst @@ -13,6 +13,7 @@ the options. To force that a value is greater than another value, see +----------------+----------------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+----------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\GreaterThanOrEqual` | +----------------+----------------------------------------------------------------------------------+ @@ -100,3 +101,5 @@ message This is the message that will be shown if the value is not greater than or equal to the comparison value. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Iban.rst b/reference/constraints/Iban.rst index 45a423e945c..ecd02f52d91 100644 --- a/reference/constraints/Iban.rst +++ b/reference/constraints/Iban.rst @@ -13,6 +13,7 @@ transcription errors. | Applies to | :ref:`property or method` | +----------------+-----------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Iban` | +----------------+-----------------------------------------------------------------------+ @@ -98,4 +99,6 @@ message The default message supplied when the value does not pass the Iban check. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`International Bank Account Number (IBAN)`: http://en.wikipedia.org/wiki/International_Bank_Account_Number diff --git a/reference/constraints/IdenticalTo.rst b/reference/constraints/IdenticalTo.rst index 068035f31a9..e3df6e872f4 100644 --- a/reference/constraints/IdenticalTo.rst +++ b/reference/constraints/IdenticalTo.rst @@ -19,6 +19,7 @@ To force that a value is *not* identical, see +----------------+--------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+--------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\IdenticalTo` | +----------------+--------------------------------------------------------------------------+ @@ -105,3 +106,5 @@ message **type**: ``string`` **default**: ``This value should be identical to {{ compared_value_type }} {{ compared_value }}.`` This is the message that will be shown if the value is not identical. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Ip.rst b/reference/constraints/Ip.rst index 0cea9668340..18a025a4fff 100644 --- a/reference/constraints/Ip.rst +++ b/reference/constraints/Ip.rst @@ -10,6 +10,7 @@ IPv6 and many other combinations. +----------------+---------------------------------------------------------------------+ | Options | - `version`_ | | | - `message`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Ip` | +----------------+---------------------------------------------------------------------+ @@ -116,3 +117,5 @@ message **type**: ``string`` **default**: ``This is not a valid IP address.`` This message is shown if the string is not a valid IP address. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Isbn.rst b/reference/constraints/Isbn.rst index 6883f0e1aa4..21fba6e1e17 100644 --- a/reference/constraints/Isbn.rst +++ b/reference/constraints/Isbn.rst @@ -22,6 +22,7 @@ is either a valid ISBN-10 or a valid ISBN-13. | | - `isbn10Message`_ | | | - `isbn13Message`_ | | | - `bothIsbnMessage`_ | +| | - `payload`_ | +----------------+----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Isbn` | +----------------+----------------------------------------------------------------------+ @@ -146,4 +147,6 @@ bothIsbnMessage The message that will be shown if the `type`_ option is ``null`` and the given value does not pass any of the ISBN checks. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`International Standard Book Number (ISBN)`: http://en.wikipedia.org/wiki/Isbn diff --git a/reference/constraints/Issn.rst b/reference/constraints/Issn.rst index 0c200a73490..172e4829365 100644 --- a/reference/constraints/Issn.rst +++ b/reference/constraints/Issn.rst @@ -12,6 +12,7 @@ Validates that a value is a valid `International Standard Serial Number (ISSN)`_ | Options | - `message`_ | | | - `caseSensitive`_ | | | - `requireHyphen`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Issn` | +----------------+-----------------------------------------------------------------------+ @@ -103,5 +104,7 @@ requireHyphen The validator will allow non hyphenated ISSN values by default. When switching this to ``true``, the validator requires a hyphenated ISSN value. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`International Standard Serial Number (ISSN)`: http://en.wikipedia.org/wiki/Issn diff --git a/reference/constraints/Language.rst b/reference/constraints/Language.rst index 617d554a508..bfbc9422e55 100644 --- a/reference/constraints/Language.rst +++ b/reference/constraints/Language.rst @@ -8,6 +8,7 @@ Validates that a value is a valid language *Unicode language identifier* | Applies to | :ref:`property or method ` | +----------------+------------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Language` | +----------------+------------------------------------------------------------------------+ @@ -82,3 +83,5 @@ message **type**: ``string`` **default**: ``This value is not a valid language.`` This message is shown if the string is not a valid language code. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Length.rst b/reference/constraints/Length.rst index 6c1023c15aa..8d345cdb79d 100644 --- a/reference/constraints/Length.rst +++ b/reference/constraints/Length.rst @@ -12,6 +12,7 @@ Validates that a given string length is *between* some minimum and maximum value | | - `minMessage`_ | | | - `maxMessage`_ | | | - `exactMessage`_ | +| | - `payload`_ | +----------------+----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Length` | +----------------+----------------------------------------------------------------------+ @@ -149,3 +150,5 @@ exactMessage The message that will be shown if min and max values are equal and the underlying value's length is not exactly this value. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/LessThan.rst b/reference/constraints/LessThan.rst index ea5be3c6675..b29ae942c4e 100644 --- a/reference/constraints/LessThan.rst +++ b/reference/constraints/LessThan.rst @@ -14,6 +14,7 @@ than another value, see :doc:`/reference/constraints/GreaterThan`. +----------------+------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\LessThan` | +----------------+------------------------------------------------------------------------+ @@ -101,3 +102,5 @@ message This is the message that will be shown if the value is not less than the comparison value. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/LessThanOrEqual.rst b/reference/constraints/LessThanOrEqual.rst index a936ee76ba8..72990a33ab6 100644 --- a/reference/constraints/LessThanOrEqual.rst +++ b/reference/constraints/LessThanOrEqual.rst @@ -13,6 +13,7 @@ options. To force that a value is less than another value, see +----------------+-------------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+-------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\LessThanOrEqual` | +----------------+-------------------------------------------------------------------------------+ @@ -100,3 +101,5 @@ message This is the message that will be shown if the value is not less than or equal to the comparison value. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Locale.rst b/reference/constraints/Locale.rst index cf411c11ecb..8b2ad74201a 100644 --- a/reference/constraints/Locale.rst +++ b/reference/constraints/Locale.rst @@ -11,6 +11,7 @@ the `ISO 3166-1 alpha-2`_ *country* code (e.g. ``fr_FR`` for French/France). | Applies to | :ref:`property or method ` | +----------------+------------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Locale` | +----------------+------------------------------------------------------------------------+ @@ -86,5 +87,7 @@ message This message is shown if the string is not a valid locale. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`ISO 639-1`: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes .. _`ISO 3166-1 alpha-2`: http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes diff --git a/reference/constraints/Luhn.rst b/reference/constraints/Luhn.rst index 0dca2831300..a437f8b8546 100644 --- a/reference/constraints/Luhn.rst +++ b/reference/constraints/Luhn.rst @@ -9,6 +9,7 @@ payment gateway. | Applies to | :ref:`property or method ` | +----------------+-----------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Luhn` | +----------------+-----------------------------------------------------------------------+ @@ -94,4 +95,6 @@ message The default message supplied when the value does not pass the Luhn check. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`Luhn algorithm`: http://en.wikipedia.org/wiki/Luhn_algorithm diff --git a/reference/constraints/NotBlank.rst b/reference/constraints/NotBlank.rst index 8de6034b48c..b56aa7eceb8 100644 --- a/reference/constraints/NotBlank.rst +++ b/reference/constraints/NotBlank.rst @@ -9,6 +9,7 @@ and also not equal to ``null``. To force that a value is simply not equal to | Applies to | :ref:`property or method ` | +----------------+------------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\NotBlank` | +----------------+------------------------------------------------------------------------+ @@ -86,3 +87,5 @@ message **type**: ``string`` **default**: ``This value should not be blank.`` This is the message that will be shown if the value is blank. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/NotEqualTo.rst b/reference/constraints/NotEqualTo.rst index 1ea36a08994..ec225f5b5c9 100644 --- a/reference/constraints/NotEqualTo.rst +++ b/reference/constraints/NotEqualTo.rst @@ -19,6 +19,7 @@ options. To force that a value is equal, see +----------------+-------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+-------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\NotEqualTo` | +----------------+-------------------------------------------------------------------------+ @@ -105,3 +106,5 @@ message **type**: ``string`` **default**: ``This value should not be equal to {{ compared_value }}.`` This is the message that will be shown if the value is equal. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/NotIdenticalTo.rst b/reference/constraints/NotIdenticalTo.rst index 63e6b0462dd..7d2ef918fe9 100644 --- a/reference/constraints/NotIdenticalTo.rst +++ b/reference/constraints/NotIdenticalTo.rst @@ -19,6 +19,7 @@ options. To force that a value is identical, see +----------------+-----------------------------------------------------------------------------+ | Options | - `value`_ | | | - `message`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\NotIdenticalTo` | +----------------+-----------------------------------------------------------------------------+ @@ -105,3 +106,5 @@ message **type**: ``string`` **default**: ``This value should not be identical to {{ compared_value_type }} {{ compared_value }}.`` This is the message that will be shown if the value is not equal. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/NotNull.rst b/reference/constraints/NotNull.rst index 668aa5dfd1b..096ff6c13a3 100644 --- a/reference/constraints/NotNull.rst +++ b/reference/constraints/NotNull.rst @@ -9,6 +9,7 @@ constraint. | Applies to | :ref:`property or method ` | +----------------+-----------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\NotNull` | +----------------+-----------------------------------------------------------------------+ @@ -86,3 +87,5 @@ message **type**: ``string`` **default**: ``This value should not be null.`` This is the message that will be shown if the value is ``null``. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Null.rst b/reference/constraints/Null.rst index 38baf3d1929..246ae34af83 100644 --- a/reference/constraints/Null.rst +++ b/reference/constraints/Null.rst @@ -9,6 +9,7 @@ constraint. To ensure that a property is not null, see :doc:`/reference/constrai | Applies to | :ref:`property or method ` | +----------------+-----------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Null` | +----------------+-----------------------------------------------------------------------+ @@ -91,3 +92,5 @@ message **type**: ``string`` **default**: ``This value should be null.`` This is the message that will be shown if the value is not ``null``. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Range.rst b/reference/constraints/Range.rst index 03781307ff2..2d68e6cd1af 100644 --- a/reference/constraints/Range.rst +++ b/reference/constraints/Range.rst @@ -11,6 +11,7 @@ Validates that a given number is *between* some minimum and maximum number. | | - `minMessage`_ | | | - `maxMessage`_ | | | - `invalidMessage`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Range` | +----------------+---------------------------------------------------------------------+ @@ -141,4 +142,6 @@ invalidMessage The message that will be shown if the underlying value is not a number (per the `is_numeric`_ PHP function). +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`is_numeric`: http://www.php.net/manual/en/function.is-numeric.php diff --git a/reference/constraints/Regex.rst b/reference/constraints/Regex.rst index fbd12230830..42eb325dbe7 100644 --- a/reference/constraints/Regex.rst +++ b/reference/constraints/Regex.rst @@ -10,6 +10,7 @@ Validates that a value matches a regular expression. | | - `htmlPattern`_ | | | - `match`_ | | | - `message`_ | +| | - `payload`_ | +----------------+-----------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Regex` | +----------------+-----------------------------------------------------------------------+ @@ -274,3 +275,5 @@ message **type**: ``string`` **default**: ``This value is not valid.`` This is the message that will be shown if this validator fails. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Time.rst b/reference/constraints/Time.rst index 3e9540801b8..d1d77ea4754 100644 --- a/reference/constraints/Time.rst +++ b/reference/constraints/Time.rst @@ -9,6 +9,7 @@ a valid "HH:MM:SS" format. | Applies to | :ref:`property or method ` | +----------------+------------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Time` | +----------------+------------------------------------------------------------------------+ @@ -35,7 +36,7 @@ of the day when the event starts: // src/Acme/EventBundle/Entity/Event.php namespace Acme\EventBundle\Entity; - + use Symfony\Component\Validator\Constraints as Assert; class Event @@ -62,10 +63,10 @@ of the day when the event starts: .. code-block:: php - + // src/Acme/EventBundle/Entity/Event.php namespace Acme\EventBundle\Entity; - + use Symfony\Component\Validator\Mapping\ClassMetadata; use Symfony\Component\Validator\Constraints as Assert; @@ -86,3 +87,5 @@ message **type**: ``string`` **default**: ``This value is not a valid time.`` This message is shown if the underlying data is not a valid time. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/True.rst b/reference/constraints/True.rst index 8edef81ad93..980ea8bf4da 100644 --- a/reference/constraints/True.rst +++ b/reference/constraints/True.rst @@ -11,6 +11,7 @@ Also see :doc:`False `. | Applies to | :ref:`property or method ` | +----------------+---------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\True` | +----------------+---------------------------------------------------------------------+ @@ -131,3 +132,5 @@ message **type**: ``string`` **default**: ``This value should be true.`` This message is shown if the underlying data is not true. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Type.rst b/reference/constraints/Type.rst index 629ca6a9431..96894fc7c3d 100644 --- a/reference/constraints/Type.rst +++ b/reference/constraints/Type.rst @@ -10,6 +10,7 @@ to validate this. +----------------+---------------------------------------------------------------------+ | Options | - :ref:`type ` | | | - `message`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Type` | +----------------+---------------------------------------------------------------------+ @@ -135,3 +136,5 @@ message **type**: ``string`` **default**: ``This value should be of type {{ type }}.`` The message if the underlying data is not of the given type. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/UniqueEntity.rst b/reference/constraints/UniqueEntity.rst index c622244a0e4..d830d96e5df 100644 --- a/reference/constraints/UniqueEntity.rst +++ b/reference/constraints/UniqueEntity.rst @@ -14,6 +14,7 @@ using an email address that already exists in the system. | | - `repositoryMethod`_ | | | - `errorPath`_ | | | - `ignoreNull`_ | +| | - `payload`_ | +----------------+-------------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Bridge\\Doctrine\\Validator\\Constraints\\UniqueEntity` | +----------------+-------------------------------------------------------------------------------------+ @@ -260,3 +261,5 @@ If this option is set to ``true``, then the constraint will allow multiple entities to have a ``null`` value for a field without failing validation. If set to ``false``, only one ``null`` value is allowed - if a second entity also has a ``null`` value, validation would fail. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Url.rst b/reference/constraints/Url.rst index 42ea1f1da2c..a5d2da48812 100644 --- a/reference/constraints/Url.rst +++ b/reference/constraints/Url.rst @@ -8,6 +8,7 @@ Validates that a value is a valid URL string. +----------------+---------------------------------------------------------------------+ | Options | - `message`_ | | | - `protocols`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Url` | +----------------+---------------------------------------------------------------------+ @@ -91,3 +92,5 @@ protocols The protocols that will be considered to be valid. For example, if you also needed ``ftp://`` type URLs to be valid, you'd redefine the ``protocols`` array, listing ``http``, ``https``, and also ``ftp``. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/UserPassword.rst b/reference/constraints/UserPassword.rst index dee677b1d78..80f5a5df4ba 100644 --- a/reference/constraints/UserPassword.rst +++ b/reference/constraints/UserPassword.rst @@ -14,6 +14,7 @@ but needs to enter their old password for security. | Applies to | :ref:`property or method ` | +----------------+--------------------------------------------------------------------------------------------+ | Options | - `message`_ | +| | - `payload`_ | +----------------+--------------------------------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Security\\Core\\Validator\\Constraints\\UserPassword` | +----------------+--------------------------------------------------------------------------------------------+ @@ -101,3 +102,5 @@ message This is the message that's displayed when the underlying string does *not* match the current user's password. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/Uuid.rst b/reference/constraints/Uuid.rst index 4db4fc8ceab..83ca0b3bcdf 100644 --- a/reference/constraints/Uuid.rst +++ b/reference/constraints/Uuid.rst @@ -15,6 +15,7 @@ UUID versions can also be restricted using a whitelist. | Options | - `message`_ | | | - `strict`_ | | | - `versions`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Uuid` | +----------------+---------------------------------------------------------------------+ @@ -120,6 +121,8 @@ The following PHP constants can also be used: All five versions are allowed by default. +.. include:: /reference/constraints/_payload-option.rst.inc + .. _`Universally unique identifier (UUID)`: http://en.wikipedia.org/wiki/Universally_unique_identifier .. _`RFC 4122`: http://tools.ietf.org/html/rfc4122 .. _`UUID versions`: http://en.wikipedia.org/wiki/Universally_unique_identifier#Variants_and_versions diff --git a/reference/constraints/Valid.rst b/reference/constraints/Valid.rst index 629f5a2d6cb..56b1d511637 100644 --- a/reference/constraints/Valid.rst +++ b/reference/constraints/Valid.rst @@ -10,6 +10,7 @@ object and all sub-objects associated with it. +----------------+---------------------------------------------------------------------+ | Options | - `traverse`_ | | | - `deep`_ | +| | - `payload`_ | +----------------+---------------------------------------------------------------------+ | Class | :class:`Symfony\\Component\\Validator\\Constraints\\Valid` | +----------------+---------------------------------------------------------------------+ @@ -275,3 +276,5 @@ deep If this constraint is applied to a property that holds an array of objects, then each object in that array will be validated recursively if this option is set to ``true``. + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/_payload-option.rst.inc b/reference/constraints/_payload-option.rst.inc new file mode 100644 index 00000000000..5ffe4f8664a --- /dev/null +++ b/reference/constraints/_payload-option.rst.inc @@ -0,0 +1,16 @@ +payload +~~~~~~~ + +**type**: ``mixed`` **default**: ``null`` + +.. versionadded:: 2.6 + The ``payload`` option was introduced in Symfony 2.6. + +This option can be used to attach arbitrary domain-specific data to a constraint. +The configured payload is not used by the Validator component, but its processing +is completely up to. + +For example, you may want to used +:doc:`several error levels ` to present failed +constraint differently in the front-end depending on the severity of the +error.