Block prefix ambiguity

book/forms.rst

@@ -241,7 +241,7 @@ your controller::
             'form' => $form->createView(),
         ));
     }
-    
+
 .. caution::
 
     Be aware that the ``createView()`` method should be called *after* ``handleRequest``
@@ -680,7 +680,7 @@ the documentation for each type.
     is left blank. If you don't want this behavior, either
     :ref:`disable HTML5 validation <book-forms-html5-validation-disable>`
     or set the ``required`` option on your field to ``false``::
-    
+
         ->add('dueDate', 'date', array(
             'widget' => 'single_text',
             'required' => false
@@ -1122,6 +1122,24 @@ the choice is ultimately up to you.
             ));
         }
 
+.. caution::
+
+    When the name of your form class matches any registered field type that has
+    its own theme fragment, your form won't be rendered correctly. A form
+    ``AppBundle\\Form\\Type\\PasswordType`` to change a user password for
+    instance will be mistaken for the built-in ``PasswordType`` field type and
+    will be rendered incorrectly using the ``password_widget`` theme fragment.
+    You can still use the class name of your choice by overriding the
+    ``getBlockPrefix`` method of your form class::
+
+        public function getBlockPrefix()
+        {
+            return 'app_bundle_password';
+        }
+
+    Read the chapter ":doc:`/cookbook/form/create_custom_field_type.html`" for
+    more information.
+
 .. tip::
 
     When mapping forms to objects, all fields are mapped. Any fields on the
@@ -1947,18 +1965,17 @@ HTML form so that the user can modify that data. The second goal of a form is to
 take the data submitted by the user and to re-apply it to the object.
 
 There's still much more to learn about the powerful world of forms, such as
-how to handle
-:doc:`file uploads with Doctrine </cookbook/doctrine/file_uploads>` or how
-to create a form where a dynamic number of sub-forms can be added (e.g. a
-todo list where you can keep adding more fields via JavaScript before submitting).
+how to handle :doc:`file uploads </cookbook/controller/upload_file>` or how to
+create a form where a dynamic number of sub-forms can be added (e.g. a todo
+list where you can keep adding more fields via JavaScript before submitting).
 See the cookbook for these topics. Also, be sure to lean on the
 :doc:`field type reference documentation </reference/forms/types>`, which
 includes examples of how to use each field type and its options.
 
 Learn more from the Cookbook
 ----------------------------
 
-* :doc:`/cookbook/doctrine/file_uploads`
+* :doc:`/cookbook/controller/upload_file`
 * :doc:`File Field Reference </reference/forms/types/file>`
 * :doc:`Creating Custom Field Types </cookbook/form/create_custom_field_type>`
 * :doc:`/cookbook/form/form_customization`