Deprecate sonata_help from form types

BitScout · Feb 11, 2020 · 0e348f4 · 0e348f4
1 parent 6ccf232
commit 0e348f4
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 43 deletions.
diff --git a/UPGRADE-3.x.md b/UPGRADE-3.x.md
@@ -1,6 +1,31 @@
 UPGRADE 3.x
 ===========
 
+## Deprecated `sonata_help` option in form types
+
+You should use Symfony's [`help`](https://symfony.com/doc/4.4/reference/forms/types/form.html#help) option instead.
+
+Before:
+```php
+$formMapper
+    ->add('field', null, [
+        'sonata_help' => 'Help text',
+    ])
+;
+```
+
+After:
+```php
+$formMapper
+    ->add('field', null, [
+        'help' => 'Help text',
+    ])
+;
+```
+
+UPGRADE FROM 3.56 to 3.57
+=========================
+
 ## Deprecated the use of string names to reference filters in favor of the FQCN of the filter.
 
 Before:

diff --git a/docs/reference/form_help_message.rst b/docs/reference/form_help_message.rst
@@ -130,34 +130,6 @@ This Extension for example adds a note field to some entities which use a custom
         }
     }
 
-Help messages in a sub-field
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: php
-
-    // src/Admin/PostAdmin.php
-
-    use Sonata\Form\Type\ImmutableArrayType;
-    use Symfony\Component\Form\Extension\Core\Type\TextareaType;
-    use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
-
-    final class PostAdmin extends AbstractAdmin
-    {
-        protected function configureFormFields(FormMapper $formMapper)
-        {
-            $formMapper
-                ->add('enabled')
-                ->add('settings', ImmutableArrayType::class, [
-                    'keys' => [
-                        ['content', TextareaType::class, [
-                            'sonata_help' => 'Set the content'
-                        ]],
-                        ['public', CheckboxType::class, []],
-                    ]
-                ])
-            ;
-        }
-    }
 
 Advanced usage
 ^^^^^^^^^^^^^^

diff --git a/src/Form/Extension/Field/Type/FormTypeFieldExtension.php b/src/Form/Extension/Field/Type/FormTypeFieldExtension.php
@@ -60,6 +60,7 @@ public function buildForm(FormBuilderInterface $builder, array $options)
         ];
 
         $builder->setAttribute('sonata_admin_enabled', false);
+        // NEXT_MAJOR: Remove this line
         $builder->setAttribute('sonata_help', false);
 
         if ($options['sonata_field_description'] instanceof FieldDescriptionInterface) {
@@ -82,6 +83,7 @@ public function buildForm(FormBuilderInterface $builder, array $options)
     public function buildView(FormView $view, FormInterface $form, array $options)
     {
         $sonataAdmin = $form->getConfig()->getAttribute('sonata_admin');
+        // NEXT_MAJOR: Remove this line
         $sonataAdminHelp = $options['sonata_help'] ?? null;
 
         /*
@@ -110,6 +112,7 @@ public function buildView(FormView $view, FormInterface $form, array $options)
                 'class' => false,
                 'options' => $this->options,
             ];
+            // NEXT_MAJOR: Remove this line
             $view->vars['sonata_help'] = $sonataAdminHelp;
             $view->vars['sonata_admin_code'] = $view->parent->vars['sonata_admin_code'];
 
@@ -150,6 +153,7 @@ public function buildView(FormView $view, FormInterface $form, array $options)
             $view->vars['sonata_admin_enabled'] = false;
         }
 
+        // NEXT_MAJOR: Remove this line
         $view->vars['sonata_help'] = $sonataAdminHelp;
         $view->vars['sonata_admin'] = $sonataAdmin;
     }
@@ -176,14 +180,20 @@ public function setDefaultOptions(OptionsResolverInterface $resolver)
 
     public function configureOptions(OptionsResolver $resolver)
     {
-        $resolver->setDefaults([
+        $resolver
+            ->setDefaults([
             'sonata_admin' => null,
             'sonata_field_description' => null,
 
             // be compatible with mopa if not installed, avoid generating an exception for invalid option
             'label_render' => true,
+            // NEXT_MAJOR: Remove this property and the deprecation message
             'sonata_help' => null,
-        ]);
+        ])
+            ->setDeprecated(
+                'sonata_help',
+                'The "sonata_help" option is deprecated since sonata-project/admin-bundle 3.x, to be removed in 4.0. Use "help" instead.'
+            );
     }
 
     /**

diff --git a/src/Resources/views/Form/form_admin_fields.html.twig b/src/Resources/views/Form/form_admin_fields.html.twig
@@ -23,7 +23,9 @@ file that was distributed with this source code.
     {% endif %}
 {%- endblock form_errors %}
 
+{# NEXT_MAJOR: Remove this block and all the calls made to this block #}
 {% block sonata_help %}
+{% deprecated 'The "sonata_help" option is deprecated since sonata-project/admin-bundle 3.x, to be removed in 4.0. Use "help" instead.' %}
 {% apply spaceless %}
 {% if sonata_help is defined and sonata_help %}
     <span class="help-block sonata-ba-field-widget-help">{{ sonata_help|raw }}</span>

diff --git a/tests/Form/Extension/Field/Type/FormTypeFieldExtensionTest.php b/tests/Form/Extension/Field/Type/FormTypeFieldExtensionTest.php
@@ -44,11 +44,9 @@ public function testDefaultOptions(): void
 
         $this->assertArrayHasKey('sonata_admin', $options);
         $this->assertArrayHasKey('sonata_field_description', $options);
-        $this->assertArrayHasKey('sonata_help', $options);
 
         $this->assertNull($options['sonata_admin']);
         $this->assertNull($options['sonata_field_description']);
-        $this->assertNull($options['sonata_help']);
     }
 
     public function testbuildViewWithNoSonataAdminArray(): void
@@ -111,9 +109,7 @@ public function testbuildViewWithWithSonataAdmin(): void
         $formView->vars['block_prefixes'] = ['form', 'field', 'text', '_s50b26aa76cb96_username'];
 
         $extension = new FormTypeFieldExtension([], []);
-        $extension->buildView($formView, $form, [
-            'sonata_help' => 'help text',
-        ]);
+        $extension->buildView($formView, $form, []);
 
         $this->assertArrayHasKey('block_prefixes', $formView->vars);
         $this->assertArrayHasKey('sonata_admin_enabled', $formView->vars);
@@ -130,7 +126,6 @@ public function testbuildViewWithWithSonataAdmin(): void
 
         $this->assertSame($expected, $formView->vars['block_prefixes']);
         $this->assertTrue($formView->vars['sonata_admin_enabled']);
-        $this->assertSame('help text', $formView->vars['sonata_help']);
     }
 
     public function testbuildViewWithNestedForm(): void
@@ -154,9 +149,7 @@ public function testbuildViewWithNestedForm(): void
         $formView->vars['block_prefixes'] = ['form', 'field', 'text', '_s50b26aa76cb96_settings_format'];
 
         $extension = new FormTypeFieldExtension([], []);
-        $extension->buildView($formView, $form, [
-            'sonata_help' => 'help text',
-        ]);
+        $extension->buildView($formView, $form, []);
 
         $this->assertArrayHasKey('block_prefixes', $formView->vars);
         $this->assertArrayHasKey('sonata_admin_enabled', $formView->vars);
@@ -185,7 +178,8 @@ public function testbuildViewWithNestedForm(): void
                  'class' => false,
                  'options' => [],
             ],
-            'sonata_help' => 'help text',
+            // NEXT_MAJOR: Remove this line
+            'sonata_help' => null,
             'sonata_admin_code' => 'parent_code',
         ];
 
@@ -202,12 +196,29 @@ public function testbuildViewWithNestedFormWithNoParent(): void
         $form = new Form($config);
 
         $extension = new FormTypeFieldExtension([], []);
-        $extension->buildView($formView, $form, [
-            'sonata_help' => 'help text',
-        ]);
+        $extension->buildView($formView, $form, []);
 
         $this->assertArrayNotHasKey('block_prefixes', $formView->vars);
         $this->assertArrayHasKey('sonata_admin_enabled', $formView->vars);
         $this->assertArrayHasKey('sonata_admin', $formView->vars);
     }
+
+    /**
+     * @group legacy
+     */
+    public function testSonataHelp(): void
+    {
+        $extension = new FormTypeFieldExtension([], []);
+        $optionResolver = new OptionsResolver();
+        $extension->configureOptions($optionResolver);
+
+        $defaultOptions = $optionResolver->resolve();
+
+        $this->assertArrayHasKey('sonata_help', $defaultOptions);
+        $this->assertNull($defaultOptions['sonata_help']);
+
+        $optionsWithSonataHelp = $optionResolver->resolve(['sonata_help' => 'Sonata help message']);
+
+        $this->assertSame('Sonata help message', $optionsWithSonataHelp['sonata_help']);
+    }
 }