Deprecate help option in FieldDescription

.phpstan/phpstan-baseline.neon

@@ -90,6 +90,12 @@ parameters:
             count: 1
             path: ../src/Translator/Extractor/JMSTranslatorBundle/AdminExtractor.php
 
+        -
+            # NEXT_MAJOR: Remove this error
+            message: "#^Call to an undefined method Sonata\\\\AdminBundle\\\\Admin\\\\FieldDescriptionInterface\\:\\:setHelp\\(\\)\\.$#"
+            count: 1
+            path: ../src/Form/FormMapper.php
+
 # next 6 errors are due to not installed Doctrine ORM\ODM
         -
             message: "#^Class Doctrine\\\\ODM\\\\MongoDB\\\\PersistentCollection not found\\.$#"

UPGRADE-3.x.md

@@ -1,6 +1,27 @@
 UPGRADE 3.x
 ===========
 
+## Deprecated `help` option in field description
+
+You MUST use Symfony's [`help`](https://symfony.com/doc/4.4/reference/forms/types/form.html#help) option instead.
+
+Before:
+```php
+$formMapper
+    ->add('field', null, [
+        'help' => 'Help text <small>Please!</small>',
+    ]);
+```
+
+After:
+```php
+$formMapper
+    ->add('field', null, [
+        'help' => 'Help text <small>Please!</small>',
+        'help_html' => true,
+    ]);
+```
+
 UPGRADE FROM 3.71 to 3.72
 =========================
 

docs/cookbook/recipe_image_previews.rst

@@ -22,14 +22,14 @@ Pre-requisites
 The recipe
 ----------
 
-SonataAdmin lets us put raw HTML into the 'help' option for any given form field.
+You can use Symfony 'help' and 'help_html' options to put raw HTML into any given form field.
 We are going to use this functionality to embed an image tag when an image exists.
 
 To do this we need to:
 
 - get access to the ``Image`` instance from within ``ImageAdmin``
 - create an image tag based on the Image's URL
-- add a 'help' option to a field on the Image form to display the image tag
+- add a 'help' and 'help_html' option to a field on the Image form to display the image tag
 
 For the sake of this example we will use some basic CSS to restrict the size of
 the preview image (we are not going to generate and save special thumbnails).
@@ -48,19 +48,20 @@ we are manipulating form fields we do this from within ``ImageAdmin::configureFo
             // get the current Image instance
             $image = $this->getSubject();
 
-            // use $fileFieldOptions so we can add other options to the field
-            $fileFieldOptions = ['required' => false];
+            // use $fileFormOptions so we can add other options to the field
+            $fileFormOptions = ['required' => false];
             if ($image && ($webPath = $image->getWebPath())) {
                 // get the container so the full path to the image can be set
                 $container = $this->getConfigurationPool()->getContainer();
                 $fullPath = $container->get('request_stack')->getCurrentRequest()->getBasePath().'/'.$webPath;
 
                 // add a 'help' option containing the preview's img tag
-                $fileFieldOptions['help'] = '<img src="'.$fullPath.'" class="admin-preview"/>';
+                $fileFormOptions['help'] = '<img src="'.$fullPath.'" class="admin-preview"/>';
+                $fileFormOptions['help_html'] = true;
             }
 
             $formMapper
-                ->add('file', 'file', $fileFieldOptions)
+                ->add('file', 'file', $fileFormOptions)
             ;
         }
     }
@@ -77,7 +78,7 @@ We then use CSS to restrict the max size of the image:
 And that is all there is to it!
 
 However, this method does not work when the ``ImageAdmin`` can be embedded in other
-Admins using the ``sonata_type_admin`` field type. For that we need...
+Admins using the ``Sonata\\AdminBundle\\Form\\Type\\AdminType`` field type. For that we need...
 
 Advanced example - works with embedded Admins
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -105,15 +106,16 @@ Admin class is embedded and use a different method::
                 $image = $this->getSubject();
             }
 
-            // use $fileFieldOptions so we can add other options to the field
-            $fileFieldOptions = ['required' => false];
+            // use $fileFormOptions so we can add other options to the field
+            $fileFormOptions = ['required' => false];
             if ($image && ($webPath = $image->getWebPath())) {
                 // add a 'help' option containing the preview's img tag
-                $fileFieldOptions['help'] = '<img src="'.$webPath.'" class="admin-preview"/>';
+                $fileFormOptions['help'] = '<img src="'.$webPath.'" class="admin-preview"/>';
+                $fileFormOptions['help_html'] = true;
             }
 
             $formMapper
-                ->add('file', 'file', $fileFieldOptions)
+                ->add('file', 'file', $fileFormOptions)
             ;
         }
     }

docs/reference/form_help_message.rst

@@ -4,10 +4,9 @@ Form Help Messages and Descriptions
 Help Messages
 -------------
 
-Help messages are short notes that are rendered together with form fields.
+You can use `Symfony 'help' option`_ to add help messages that are rendered together with form fields.
 They are generally used to show additional information so the user can complete
-the form element faster and more accurately. The text is not escaped,
-so HTML can be used.
+the form element faster and more accurately.
 
 Example
 ^^^^^^^
@@ -37,100 +36,6 @@ Example
    :align: center
    :alt: Example of the two form fields with help messages.
 
-Alternative Ways To Define Help Messages
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-All at once::
-
-    // src/Admin/PostAdmin.php
-
-    final class PostAdmin extends AbstractAdmin
-    {
-        protected function configureFormFields(FormMapper $formMapper)
-        {
-            $formMapper
-                ->with('General')
-                    ->add('title')
-                    ->add('keywords')
-                    ->setHelps([
-                        'title' => 'Set the title of a web page',
-                        'keywords' => 'Set the keywords of a web page',
-                    ])
-                ->end()
-            ;
-        }
-    }
-
-or step by step::
-
-    // src/Admin/PostAdmin.php
-
-    final class PostAdmin extends AbstractAdmin
-    {
-        protected function configureFormFields(FormMapper $formMapper)
-        {
-            $formMapper
-                ->with('General')
-                    ->add('title')
-                    ->add('keywords')
-                    ->setHelp('title', 'Set the title of a web page')
-                    ->setHelp('keywords', 'Set the keywords of a web page')
-                ->end()
-            ;
-        }
-    }
-
-This can be very useful if you want to apply general help messages via an ``AdminExtension``.
-This Extension for example adds a note field to some entities which use a custom trait::
-
-    namespace App\Admin\Extension;
-
-    use Sonata\AdminBundle\Admin\AbstractAdminExtension;
-    use Sonata\AdminBundle\Datagrid\DatagridMapper;
-    use Sonata\AdminBundle\Form\FormMapper;
-    use Sonata\AdminBundle\Show\ShowMapper;
-
-    final class NoteAdminExtension extends AbstractAdminExtension
-    {
-        // add this field to the datagrid every time its available
-        /**
-         * @param DatagridMapper $datagridMapper
-         */
-        protected function configureDatagridFilters(DatagridMapper $datagridMapper)
-        {
-            $datagridMapper
-                ->add('note')
-            ;
-        }
-
-        // here we don't add the field, because we would like to define
-        // the place manually in the admin. But if the filed is available,
-        // we want to add the following help message to the field.
-        /**
-         * @param FormMapper $formMapper
-         */
-        protected function configureFormFields(FormMapper $formMapper)
-        {
-            $formMapper
-                ->addHelp('note', 'Use this field for an internal note.')
-            ;
-        }
-
-        // if the field exists, add it in a special tab on the show view.
-        /**
-         * @param ShowMapper $showMapper
-         */
-        protected function configureShowFields(ShowMapper $showMapper)
-        {
-            $showMapper
-                ->with('Internal')
-                    ->add('note')
-                ->end()
-            ;
-        }
-    }
-
-
 Advanced usage
 ^^^^^^^^^^^^^^
 
@@ -170,3 +75,5 @@ Example
             ;
         }
     }
+
+.. _`Symfony 'help' option`: https://symfony.com/doc/4.4/reference/forms/types/form.html#help

src/Admin/BaseFieldDescription.php

@@ -180,9 +180,17 @@ public function setOptions(array $options)
             unset($options['template']);
         }
 
+        // NEXT_MAJOR: Remove this block.
         // set help if provided
         if (isset($options['help'])) {
-            $this->setHelp($options['help']);
+            @trigger_error(sprintf(
+                'Passing "help" option to "%s()" is deprecated since sonata-project/admin-bundle 3.x'
+                .' and the option will be removed in 4.0.'
+                .' Use Symfony Form "help" option instead.',
+                __METHOD__
+            ), E_USER_DEPRECATED);
+
+            $this->setHelp($options['help'], 'sonata_deprecation_mute');
             unset($options['help']);
         }
 
@@ -448,15 +456,33 @@ public static function camelize($property)
     /**
      * Defines the help message.
      *
+     * NEXT_MAJOR: Remove this method.
+     *
+     * @deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0. Use Symfony Form "help" option instead.
+     *
      * @param string $help
      */
     public function setHelp($help)
     {
+        if ('sonata_deprecation_mute' !== (\func_get_args()[1] ?? null)) {
+            @trigger_error(sprintf(
+                'The "%s()" method is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.'
+                .' Use Symfony Form "help" option instead.',
+                __METHOD__
+            ), E_USER_DEPRECATED);
+        }
+
         $this->help = $help;
     }
 
     public function getHelp()
     {
+        @trigger_error(sprintf(
+            'The "%s()" method is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.'
+            .' Use Symfony Form "help" option instead.',
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         return $this->help;
     }
 

src/Admin/FieldDescriptionInterface.php

@@ -20,7 +20,6 @@
  * @method bool        hasAdmin()
  * @method bool        hasParent()
  * @method bool        hasAssociationAdmin()
- * @method void        setHelp(string $help)
  */
 interface FieldDescriptionInterface
 {
@@ -300,10 +299,4 @@ public function getSortParentAssociationMapping();
      * @return mixed
      */
     public function getFieldValue($object, $fieldName);
-
-//    NEXT_MAJOR: uncomment this method in 4.0
-//    /**
-//     * Defines the help message.
-//     */
-//    public function setHelp(string $help): void;
 }

src/Form/FormMapper.php

@@ -136,9 +136,19 @@ public function add($name, $type = null, array $options = [], array $fieldDescri
                 $options['label'] = $this->admin->getLabelTranslatorStrategy()->getLabel($name, 'form', 'label');
             }
 
+            // NEXT_MAJOR: Remove this block.
             if (isset($options['help'])) {
-                $fieldDescription->setHelp($options['help']);
-                unset($options['help']);
+                $containsHtml = $options['help'] !== strip_tags($options['help']);
+
+                if (!isset($options['help_html']) && $containsHtml) {
+                    @trigger_error(
+                        'Using HTML syntax within the "help" option and not setting the "help_html" option to "true" is deprecated'
+                        .' since sonata-project/admin-bundle 3.x and it will not work in version 4.0.',
+                        E_USER_DEPRECATED
+                    );
+
+                    $options['help_html'] = true;
+                }
             }
         }
 
@@ -241,24 +251,46 @@ public function create($name, $type = null, array $options = [])
     }
 
     /**
+     * NEXT_MAJOR: Remove this method.
+     *
+     * @deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0. Use Symfony Form "help" option instead.
+     *
      * @return FormMapper
      */
     public function setHelps(array $helps = [])
     {
+        @trigger_error(sprintf(
+            'The "%s()" method is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.'
+            .' Use Symfony Form "help" option instead.',
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
         foreach ($helps as $name => $help) {
-            $this->addHelp($name, $help);
+            $this->addHelp($name, $help, 'sonata_deprecation_mute');
         }
 
         return $this;
     }
 
     /**
+     * NEXT_MAJOR: Remove this method.
+     *
+     * @deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0. Use Symfony Form "help" option instead.
+     *
      * @return FormMapper
      */
     public function addHelp($name, $help)
     {
+        if ('sonata_deprecation_mute' !== (\func_get_args()[2] ?? null)) {
+            @trigger_error(sprintf(
+                'The "%s()" method is deprecated since sonata-project/admin-bundle 3.x and will be removed in version 4.0.'
+                .' Use Symfony Form "help" option instead.',
+                __METHOD__
+            ), E_USER_DEPRECATED);
+        }
+
         if ($this->admin->hasFormFieldDescription($name)) {
-            $this->admin->getFormFieldDescription($name)->setHelp($help);
+            $this->admin->getFormFieldDescription($name)->setHelp($help, 'sonata_deprecation_mute');
         }
 
         return $this;

src/Resources/views/CRUD/Association/edit_one_to_many_inline_table.html.twig

@@ -48,9 +48,13 @@ file that was distributed with this source code.
                         {% if sonata_admin.field_description.associationadmin.formfielddescriptions[field_name] is defined %}
                             {{ form_widget(nested_field) }}
 
+                            {# NEXT_MAJOR: Remove this block #}
                             {% if sonata_admin.field_description.associationadmin.formfielddescriptions[field_name].help %}
                                 <span class="help-block">
                                     {%- block help %}
+                                        {% if nested_field.help is empty %}
+                                            {% deprecated 'The "help" option is deprecated in field description since sonata-project/admin-bundle 3.x, to be removed in 4.0. Use Symfony Form "help" option instead.' %}
+                                        {% endif %}
                                         {{- sonata_admin.field_description.associationadmin.formfielddescriptions[field_name].help|trans(
                                             {},
                                             sonata_admin.field_description.associationadmin.formfielddescriptions[field_name].translationDomain
@@ -59,6 +63,8 @@ file that was distributed with this source code.
                                 </span>
                             {% endif %}
 
+                            {{ form_help(nested_field) }}
+
                             {% set dummy = nested_group_field.setrendered %}
                         {% else %}
                             {% if field_name == '_delete' %}