From d2910ec152e9f3caa57d57832dfff7407116dc53 Mon Sep 17 00:00:00 2001 From: naitsirch Date: Thu, 18 Oct 2018 16:29:26 +0200 Subject: [PATCH 1/3] Added description for the "validation_groups" option As requested in #4401 a description of the "validation_groups" option of the base ``FormType`` is added. --- reference/forms/types/form.rst | 3 ++ .../types/options/validation_groups.rst.inc | 51 +++++++++++++++++++ 2 files changed, 54 insertions(+) create mode 100644 reference/forms/types/options/validation_groups.rst.inc diff --git a/reference/forms/types/form.rst b/reference/forms/types/form.rst index fe6b80f1ca9..52aefbad70c 100644 --- a/reference/forms/types/form.rst +++ b/reference/forms/types/form.rst @@ -34,6 +34,7 @@ on all types for which ``FormType`` is the parent. | | - `read_only`_ (deprecated as of 2.8) | | | - `required`_ | | | - `trim`_ | +| | - `validation_groups`_ | +-----------+--------------------------------------------------------------------+ | Inherited | - `attr`_ | | options | - `auto_initialize`_ | @@ -146,6 +147,8 @@ The actual default value of this option depends on other field options: .. include:: /reference/forms/types/options/trim.rst.inc +.. include:: /reference/forms/types/options/validation_groups.rst.inc + Inherited Options ----------------- diff --git a/reference/forms/types/options/validation_groups.rst.inc b/reference/forms/types/options/validation_groups.rst.inc new file mode 100644 index 00000000000..85d64f5c0ea --- /dev/null +++ b/reference/forms/types/options/validation_groups.rst.inc @@ -0,0 +1,51 @@ +validation_groups +~~~~~~~~~~~~~~~~~ + +**type**: ``array``, ``string``, ``callable`` or ``null`` **default**: ``null`` + +This option is only valid on the root form and is used to specify which +groups will be used by the validator. + +For ``null`` the validator will just use the ``Default`` group. + +If you specify the groups as array or string they will used by the validator +as they are:: + + public function configureOptions(OptionsResolver $resolver) + { + $resolver->setDefaults(array( + 'validation_groups' => 'Registration', + )); + } + +This is equivalent to passing the group as array:: + + 'validation_groups' => array('Registration'), + +If the validation groups depend on the form's data a callable may be passed to +the option. Symfony then will pass the form when calling it:: + + use Symfony\Component\Form\FormInterface; + + // ... + public function configureOptions(OptionsResolver $resolver) + { + $resolver->setDefaults(array( + 'validation_groups' => function (FormInterface $form) { + $entity = $form->getData(); + return $entity->getValidationGroups(); + }, + )); + } + +The class that the form is used for may look like this:: + + class Account + { + public function getValidationGroups() + { + return $this->isUser() ? array('User') : array('Company'); + } + } + +You can read more about this in :doc:`/form/data_based_validation`. From 11e85cbab24941d701613f6af304ac79974880ba Mon Sep 17 00:00:00 2001 From: naitsirch Date: Tue, 13 Nov 2018 15:51:48 +0100 Subject: [PATCH 2/3] Added doc about usage of GroupSequence and links to related articles for form option 'validation_groups' --- .../types/options/validation_groups.rst.inc | 46 +++++++++++++++++-- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/reference/forms/types/options/validation_groups.rst.inc b/reference/forms/types/options/validation_groups.rst.inc index 85d64f5c0ea..0b5bc1c2041 100644 --- a/reference/forms/types/options/validation_groups.rst.inc +++ b/reference/forms/types/options/validation_groups.rst.inc @@ -1,7 +1,7 @@ validation_groups ~~~~~~~~~~~~~~~~~ -**type**: ``array``, ``string``, ``callable`` or ``null`` **default**: ``null`` +**type**: ``array``, ``string``, ``callable``, :class:`Symfony\\Component\\Validator\\Constraints\\GroupSequence` or ``null`` **default**: ``null`` This option is only valid on the root form and is used to specify which groups will be used by the validator. @@ -22,10 +22,13 @@ This is equivalent to passing the group as array:: 'validation_groups' => array('Registration'), +The form's data will be :doc:`validated agains all groups `. + If the validation groups depend on the form's data a callable may be passed to -the option. Symfony then will pass the form when calling it:: +the option. Symfony will then pass the form when calling it:: use Symfony\Component\Form\FormInterface; + use Symfony\Component\OptionsResolver\OptionsResolver; // ... public function configureOptions(OptionsResolver $resolver) @@ -48,4 +51,41 @@ The class that the form is used for may look like this:: } } -You can read more about this in :doc:`/form/data_based_validation`. +.. seealso:: + + You can read more about this in :doc:`/form/data_based_validation`. + +.. note:: + + When your form contains multiple submit buttons, you can change the + validation group depending on :doc:`which button is used` + to submit the form. + + If you need advanced logic to determine the validation groups have + a look at :doc:`/form/validation_group_service_resolver`. + +In some cases, you want to validate your groups by steps. To do this, you +can pass a :class:`Symfony\\Component\\Validator\\Constraints\\GroupSequence` +to this option. This enables you to validate against multiple groups, +like when you pass multiple groups in an array, but with the difference that +a group is only validated if the previous groups pass without errors. +Here's an example:: + + use Symfony\Component\Validator\Constraints\GroupSequence; + use Symfony\Component\Form\AbstractType; + // ... + + class MyType extends AbstractType + { + // ... + public function configureOptions(OptionsResolver $resolver) + { + $resolver->setDefaults([ + 'validation_groups' => new GroupSequence(['First', 'Second']), + ]); + } + } + +.. seealso:: + + Read the article :doc:`/validation/sequence_provider` to find out more about this. From 6185a261f96beda0dcae7b4d38072b124fe09a78 Mon Sep 17 00:00:00 2001 From: naitsirch Date: Thu, 15 Nov 2018 14:49:36 +0100 Subject: [PATCH 3/3] Some improvements on validation_groups option --- .../types/options/validation_groups.rst.inc | 21 ++++++------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/reference/forms/types/options/validation_groups.rst.inc b/reference/forms/types/options/validation_groups.rst.inc index 0b5bc1c2041..491376a9004 100644 --- a/reference/forms/types/options/validation_groups.rst.inc +++ b/reference/forms/types/options/validation_groups.rst.inc @@ -8,8 +8,8 @@ groups will be used by the validator. For ``null`` the validator will just use the ``Default`` group. -If you specify the groups as array or string they will used by the validator -as they are:: +If you specify the groups as an array or string they will be used by the +validator as they are:: public function configureOptions(OptionsResolver $resolver) { @@ -22,7 +22,7 @@ This is equivalent to passing the group as array:: 'validation_groups' => array('Registration'), -The form's data will be :doc:`validated agains all groups `. +The form's data will be :doc:`validated against all given groups `. If the validation groups depend on the form's data a callable may be passed to the option. Symfony will then pass the form when calling it:: @@ -36,21 +36,12 @@ the option. Symfony will then pass the form when calling it:: $resolver->setDefaults(array( 'validation_groups' => function (FormInterface $form) { $entity = $form->getData(); - return $entity->getValidationGroups(); + + return $entity->isUser() ? array('User') : array('Company'); }, )); } -The class that the form is used for may look like this:: - - class Account - { - public function getValidationGroups() - { - return $this->isUser() ? array('User') : array('Company'); - } - } - .. seealso:: You can read more about this in :doc:`/form/data_based_validation`. @@ -64,7 +55,7 @@ The class that the form is used for may look like this:: If you need advanced logic to determine the validation groups have a look at :doc:`/form/validation_group_service_resolver`. -In some cases, you want to validate your groups by steps. To do this, you +In some cases, you want to validate your groups step by step. To do this, you can pass a :class:`Symfony\\Component\\Validator\\Constraints\\GroupSequence` to this option. This enables you to validate against multiple groups, like when you pass multiple groups in an array, but with the difference that