feature symfony#8510 Added doc entry for delete_empty form option with callable (hiddewie, javiereguiluz)

This PR was merged into the 3.4 branch.

Discussion
----------

Added doc entry for delete_empty form option with callable

Fix symfony#8244.

I hope the explanation is clear enough. Now it is just an addition to the existing text. The piece of code is taken from the tests (adapted slightly for simplicity).

Commits
-------

0373a97 Processed xabbuh comments
3f1a814 Minor rewords
1722628 Added doc entry for delete_empty form option with callable

Author: weaverryan

reference/forms/types/collection.rst

@@ -270,10 +270,10 @@ For more information, see :ref:`form-collections-remove`.
 delete_empty
 ~~~~~~~~~~~~
 
-**type**: ``Boolean`` **default**: ``false``
+**type**: ``Boolean`` or ``callable`` **default**: ``false``
 
 If you want to explicitly remove entirely empty collection entries from your
-form you have to set this option to true. However, existing collection entries
+form you have to set this option to ``true``. However, existing collection entries
 will only be deleted if you have the allow_delete_ option enabled. Otherwise
 the empty values will be kept.
 
@@ -286,6 +286,28 @@ the empty values will be kept.
     Read about the :ref:`form's empty_data option <reference-form-option-empty-data>`
     to learn why this is necessary.
 
+A value is deleted from the collection only if the normalized value is ``null``.
+However, you can also set the option value to a callable, which will be executed
+for each value in the submitted collection. If the callable returns ``true``,
+the value is removed from the collection. For example::
+
+    use Symfony\Component\Form\Extension\Core\Type\CollectionType;
+    // ...
+
+    $builder->add('users', CollectionType::class, array(
+        // ...
+        'delete_empty' => function (User $user = null) {
+            return null === $user || empty($user->getFirstName());
+        },
+    ));
+
+Using a callable is particularly useful in case of compound form types, which
+may define complex conditions for considering them empty.
+
+.. versionadded:: 3.4
+    Support for using a callable for the ``delete_empty`` option was introduced
+    in Symfony 3.4.
+
 entry_options
 ~~~~~~~~~~~~~