|
| 1 | +.. index:: |
| 2 | + single: Validation; Error Levels |
| 3 | + single: Validation; Payload |
| 4 | + |
| 5 | +How to Handle Different Error Levels |
| 6 | +==================================== |
| 7 | + |
| 8 | +Sometimes, you may want to display constraint validation error messages differently |
| 9 | +based on some rules. For example, you have a registration form for new users |
| 10 | +where they enter some personal information and choose their authentication |
| 11 | +credentials. They would have to choose a username and a secure password, |
| 12 | +but providing bank account information would be optional. Nonetheless, you |
| 13 | +want to make sure that these optional data, if entered, are still valid, |
| 14 | +but display them differently. |
| 15 | + |
| 16 | +The process to achieve this behavior consists of two steps: |
| 17 | + |
| 18 | +#. Apply different error levels to the validation constraints; |
| 19 | +#. Customize your error messages depending on the configured error level. |
| 20 | + |
| 21 | +1. Assigning the Error Level |
| 22 | +---------------------------- |
| 23 | + |
| 24 | +.. versionadded:: 2.6 |
| 25 | + The ``payload`` option was introduced in Symfony 2.6. |
| 26 | + |
| 27 | +Use the ``payload`` option to configure the error level for each constraint: |
| 28 | + |
| 29 | +.. configuration-block:: |
| 30 | + |
| 31 | + .. code-block:: php-annotations |
| 32 | +
|
| 33 | + // src/AppBundle/Entity/User.php |
| 34 | + namespace AppBundle\Entity; |
| 35 | +
|
| 36 | + use Symfony\Component\Validator\Constraints as Assert; |
| 37 | +
|
| 38 | + class User |
| 39 | + { |
| 40 | + /** |
| 41 | + * @Assert\NotBlank(payload = {severity = "error"}) |
| 42 | + */ |
| 43 | + protected $username; |
| 44 | +
|
| 45 | + /** |
| 46 | + * @Assert\NotBlank(payload = {severity = "error"}) |
| 47 | + */ |
| 48 | + protected $password; |
| 49 | +
|
| 50 | + /** |
| 51 | + * @Assert\Iban(payload = {severity = "warning"}) |
| 52 | + */ |
| 53 | + protected $bankAccountNumber; |
| 54 | + } |
| 55 | +
|
| 56 | + .. code-block:: yaml |
| 57 | +
|
| 58 | + # src/AppBundle/Resources/config/validation.yml |
| 59 | + AppBundle\Entity\User: |
| 60 | + properties: |
| 61 | + username: |
| 62 | + - NotBlank: |
| 63 | + payload: |
| 64 | + severity: error |
| 65 | + password: |
| 66 | + - NotBlank: |
| 67 | + payload: |
| 68 | + severity: error |
| 69 | + bankAccountNumber: |
| 70 | + - Iban: |
| 71 | + payload: |
| 72 | + severity: warning |
| 73 | +
|
| 74 | + .. code-block:: xml |
| 75 | +
|
| 76 | + <!-- src/AppBundle/Resources/config/validation.xml --> |
| 77 | + <?xml version="1.0" encoding="UTF-8" ?> |
| 78 | + <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping" |
| 79 | + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| 80 | + xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> |
| 81 | +
|
| 82 | + <class name="AppBundle\Entity\User"> |
| 83 | + <property name="username"> |
| 84 | + <constraint name="NotBlank"> |
| 85 | + <option name="payload"> |
| 86 | + <value key="severity">error</value> |
| 87 | + </option> |
| 88 | + </constraint> |
| 89 | + </property> |
| 90 | + <property name="password"> |
| 91 | + <constraint name="NotBlank"> |
| 92 | + <option name="payload"> |
| 93 | + <value key="severity">error</value> |
| 94 | + </option> |
| 95 | + </constraint> |
| 96 | + </property> |
| 97 | + <property name="bankAccountNumber"> |
| 98 | + <constraint name="Iban"> |
| 99 | + <option name="payload"> |
| 100 | + <value key="severity">warning</value> |
| 101 | + </option> |
| 102 | + </constraint> |
| 103 | + </property> |
| 104 | + </class> |
| 105 | + </constraint-mapping> |
| 106 | +
|
| 107 | + .. code-block:: php |
| 108 | +
|
| 109 | + // src/AppBundle/Entity/User.php |
| 110 | + namespace AppBundle\Entity; |
| 111 | +
|
| 112 | + use Symfony\Component\Validator\Mapping\ClassMetadata; |
| 113 | + use Symfony\Component\Validator\Constraints as Assert; |
| 114 | +
|
| 115 | + class User |
| 116 | + { |
| 117 | + public static function loadValidatorMetadata(ClassMetadata $metadata) |
| 118 | + { |
| 119 | + $metadata->addPropertyConstraint('username', new Assert\NotBlank(array( |
| 120 | + 'payload' => array('severity' => 'error'), |
| 121 | + ))); |
| 122 | + $metadata->addPropertyConstraint('password', new Assert\NotBlank(array( |
| 123 | + 'payload' => array('severity' => 'error'), |
| 124 | + ))); |
| 125 | + $metadata->addPropertyConstraint('bankAccountNumber', new Assert\Iban(array( |
| 126 | + 'payload' => array('severity' => 'warning'), |
| 127 | + ))); |
| 128 | + } |
| 129 | + } |
| 130 | +
|
| 131 | +2. Customize the Error Message Template |
| 132 | +--------------------------------------- |
| 133 | + |
| 134 | +.. versionadded:: 2.6 |
| 135 | + The ``getConstraint()`` method in the ``ConstraintViolation`` class was |
| 136 | + introduced in Symfony 2.6. |
| 137 | + |
| 138 | +When validating the ``User`` object failed, you can retrieve the constraint |
| 139 | +that caused a particular failure using the |
| 140 | +:method:`Symfony\\Component\\Validator\\ConstraintViolation::getConstraint` |
| 141 | +method. Each constraint exposes the attached payload as a public property:: |
| 142 | + |
| 143 | + // a constraint validation failure, instance of |
| 144 | + // Symfony\Component\Validator\ConstraintViolation |
| 145 | + $constraintViolation = ...; |
| 146 | + $constraint = $constraintViolation->getConstraint(); |
| 147 | + $severity = isset($constraint->payload['severity']) ? $constraint->payload['severity'] : null; |
| 148 | + |
| 149 | +For example, you can leverage this to customize the ``form_errors`` block |
| 150 | +such that the severity is added as an additional HTML class: |
| 151 | + |
| 152 | +.. code-block:: html+jinja |
| 153 | + |
| 154 | + {%- block form_errors -%} |
| 155 | + {%- if errors|length > 0 -%} |
| 156 | + <ul> |
| 157 | + {%- for error in errors -%} |
| 158 | + {% if error.cause.constraint.payload.severity is defined %} |
| 159 | + {% set severity = error.cause.constraint.payload.severity %} |
| 160 | + {% endif %} |
| 161 | + <li{% if severity is defined %} class="{{ severity }}"{% endif %}>{{ error.message }}</li> |
| 162 | + {%- endfor -%} |
| 163 | + </ul> |
| 164 | + {%- endif -%} |
| 165 | + {%- endblock form_errors -%} |
0 commit comments