minor #12278 Added a new section to explain how to pass options to forms (javiereguiluz)

javiereguiluz · javiereguiluz · commit 3611e3ef2a04 · 2019-09-06T12:09:26.000+02:00
This PR was merged into the 4.3 branch. Discussion ---------- Added a new section to explain how to pass options to forms Fixes #9138. I know this could be applicable to 3.4 too ... but 3.4 and the rest of docs diverged too much in this forms article, so let's do this in 4.3 and higher. Commits ------- fce9051 Added a new section to explain how to pass options to forms
diff --git a/forms.rst b/forms.rst
@@ -540,6 +540,82 @@ powerful feature.
 Other Common Form Features
 --------------------------
 
+Passing Options to Forms
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you :ref:`create forms in classes <creating-forms-in-classes>`, when building
+the form in the controller you can pass custom options to it as the third optional
+argument of ``createForm()``::
+
+    // src/Controller/TaskController.php
+    use App\Form\Type\TaskType;
+    // ...
+
+    class TaskController extends AbstractController
+    {
+        public function new()
+        {
+            $task = new Task();
+            // use some PHP logic to decide if this form field is required or not
+            $dueDateIsRequired = ...
+
+            $form = $this->createForm(TaskType::class, $task, [
+                'require_due_date' => $dueDateIsRequired,
+            ]);
+
+            // ...
+        }
+    }
+
+If you try to use the form now, you'll see an error message: *The option
+"require_due_date" does not exist.* That's because forms must declare all the
+options they accept using the ``configureOptions()`` method::
+
+    // src/Form/Type/TaskType.php
+    use Symfony\Component\OptionsResolver\OptionsResolver;
+    // ...
+
+    class TaskType extends AbstractType
+    {
+        // ...
+
+        public function configureOptions(OptionsResolver $resolver)
+        {
+            $resolver->setDefaults([
+                // ...,
+                'require_due_date' => false,
+            ]);
+
+            // you can also define the allowed types, allowed values and
+            // any other feature supported by the OptionsResolver component
+            $resolver->setAllowedTypes('require_due_date', 'bool');
+        }
+    }
+
+Now you can use this new form option inside the ``buildForm()`` method::
+
+    // src/Form/Type/TaskType.php
+    namespace App\Form\Type;
+
+    use Symfony\Component\Form\AbstractType;
+    use Symfony\Component\Form\Extension\Core\Type\DateType;
+    use Symfony\Component\Form\FormBuilderInterface;
+
+    class TaskType extends AbstractType
+    {
+        public function buildForm(FormBuilderInterface $builder, array $options)
+        {
+            $builder
+                // ...
+                ->add('dueDate', DateType::class, [
+                    'required' => $options['require_due_date'],
+                ])
+            ;
+        }
+
+        // ...
+    }
+
 Form Type Options
 ~~~~~~~~~~~~~~~~~
 
