From dca465594767d77a36e33f830869dbaff96317de Mon Sep 17 00:00:00 2001 From: Christian Flothmann Date: Wed, 31 Dec 2014 15:45:09 +0100 Subject: [PATCH] document the validation payload option --- cookbook/map.rst.inc | 1 + cookbook/validation/index.rst | 1 + cookbook/validation/severity.rst | 165 ++++++++++++++++++ reference/constraints/All.rst | 3 + reference/constraints/Blank.rst | 3 + reference/constraints/Callback.rst | 3 + reference/constraints/CardScheme.rst | 3 + reference/constraints/Choice.rst | 15 +- reference/constraints/Collection.rst | 3 + reference/constraints/Count.rst | 3 + reference/constraints/Country.rst | 3 + reference/constraints/Currency.rst | 3 + reference/constraints/Date.rst | 3 + reference/constraints/DateTime.rst | 3 + reference/constraints/Email.rst | 5 +- reference/constraints/EqualTo.rst | 3 + reference/constraints/Expression.rst | 3 + reference/constraints/False.rst | 3 + reference/constraints/File.rst | 2 + reference/constraints/GreaterThan.rst | 3 + reference/constraints/GreaterThanOrEqual.rst | 3 + reference/constraints/Iban.rst | 3 + reference/constraints/IdenticalTo.rst | 3 + reference/constraints/Ip.rst | 3 + reference/constraints/Isbn.rst | 3 + reference/constraints/Issn.rst | 3 + reference/constraints/Language.rst | 3 + reference/constraints/Length.rst | 3 + reference/constraints/LessThan.rst | 3 + reference/constraints/LessThanOrEqual.rst | 3 + reference/constraints/Locale.rst | 3 + reference/constraints/Luhn.rst | 3 + reference/constraints/NotBlank.rst | 3 + reference/constraints/NotEqualTo.rst | 3 + reference/constraints/NotIdenticalTo.rst | 3 + reference/constraints/NotNull.rst | 3 + reference/constraints/Null.rst | 3 + reference/constraints/Range.rst | 3 + reference/constraints/Regex.rst | 3 + reference/constraints/Time.rst | 9 +- reference/constraints/True.rst | 3 + reference/constraints/Type.rst | 3 + reference/constraints/UniqueEntity.rst | 3 + reference/constraints/Url.rst | 3 + reference/constraints/UserPassword.rst | 3 + reference/constraints/Uuid.rst | 3 + reference/constraints/Valid.rst | 3 + reference/constraints/_payload-option.rst.inc | 16 ++ 48 files changed, 324 insertions(+), 10 deletions(-) create mode 100644 cookbook/validation/severity.rst create mode 100644 reference/constraints/_payload-option.rst.inc 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..5d28135852a --- /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:: 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:: 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:: 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. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy