diff --git a/form/form_customization.rst b/form/form_customization.rst
index be20db2005a..0596a0968bc 100644
--- a/form/form_customization.rst
+++ b/form/form_customization.rst
@@ -304,53 +304,10 @@ different than the one of your main form. Just specify both your themes:
{% form_theme form.a_child_form 'form/fields_child.html.twig' %}
-Form Theming in PHP
--------------------
+.. _referencing-base-form-blocks-twig-specific:
-When using PHP as a templating engine, the only method to customize a fragment
-is to create a new template file - this is similar to the second method used by
-Twig.
-
-The template file must be named after the fragment. You must create a ``integer_widget.html.php``
-file in order to customize the ``integer_widget`` fragment.
-
-.. code-block:: html+php
-
-
-
-
-Now that you've created the customized form template, you need to tell Symfony
-to use it. Inside the template where you're actually rendering your form,
-tell Symfony to use the theme via the ``setTheme()`` helper method::
-
- setTheme($form, array(':form')); ?>
-
- widget($form['age']) ?>
-
-When the ``form.age`` widget is rendered, Symfony will use the customized
-``integer_widget.html.php`` template and the ``input`` tag will be wrapped in
-the ``div`` element.
-
-If you want to apply a theme to a specific child form, pass it to the ``setTheme()``
-method::
-
- setTheme($form['child'], ':form'); ?>
-
-.. note::
-
- The ``:form`` syntax is based on the functional names for templates:
- ``Bundle:Directory``. As the form directory lives in the
- ``app/Resources/views`` directory, the ``Bundle`` part is empty, resulting
- in ``:form``.
-
-Referencing base Form Blocks (Twig specific)
---------------------------------------------
+Referencing base Form Blocks
+----------------------------
So far, to override a particular form block, the best method is to copy
the default block from `form_div_layout.html.twig`_, paste it into a different template,
@@ -406,6 +363,8 @@ the base block by using the ``parent()`` Twig function:
templating engine. You have to manually copy the content from the base block
to your new template file.
+.. _twig:
+
Making Application-wide Customizations
--------------------------------------
@@ -413,9 +372,6 @@ If you'd like a certain form customization to be global to your application,
you can accomplish this by making the form customizations in an external
template and then importing it inside your application configuration.
-Twig
-~~~~
-
By using the following configuration, any customized form blocks inside the
``form/fields.html.twig`` template will be used globally when a form is
rendered.
@@ -512,125 +468,6 @@ your template file rather than adding the template as a resource:
Note that the ``form`` variable in the above code is the form view variable
that you passed to your template.
-PHP
-~~~
-
-By using the following configuration, any customized form fragments inside the
-``app/Resources/views/Form`` folder will be used globally when a
-form is rendered.
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/config.yml
- framework:
- templating:
- form:
- resources:
- - 'AppBundle:Form'
- # ...
-
- .. code-block:: xml
-
-
-
-
-
-
-
-
- AppBundle:Form
-
-
-
-
-
-
- .. code-block:: php
-
- // app/config/config.php
- // PHP
- $container->loadFromExtension('framework', array(
- 'templating' => array(
- 'form' => array(
- 'resources' => array(
- 'AppBundle:Form',
- ),
- ),
- ),
-
- // ...
- ));
-
-By default, the PHP engine uses a *div* layout when rendering forms. Some people,
-however, may prefer to render forms in a *table* layout. Use the ``FrameworkBundle:FormTable``
-resource to use such a layout:
-
-.. configuration-block::
-
- .. code-block:: yaml
-
- # app/config/config.yml
- framework:
- templating:
- form:
- resources:
- - 'FrameworkBundle:FormTable'
-
- .. code-block:: xml
-
-
-
-
-
-
-
-
- FrameworkBundle:FormTable
-
-
-
-
-
-
- .. code-block:: php
-
- // app/config/config.php
- $container->loadFromExtension('framework', array(
- 'templating' => array(
- 'form' => array(
- 'resources' => array(
- 'FrameworkBundle:FormTable',
- ),
- ),
- ),
-
- // ...
- ));
-
-If you only want to make the change in one template, add the following line to
-your template file rather than adding the template as a resource:
-
-.. code-block:: html+php
-
- setTheme($form, array('FrameworkBundle:FormTable')); ?>
-
-Note that the ``$form`` variable in the above code is the form view variable
-that you passed to your template.
-
How to Customize an individual Field
------------------------------------
@@ -866,7 +703,7 @@ Adding a "Required" Asterisk to Field Labels
If you want to denote all of your required fields with a required asterisk (``*``),
you can do this by customizing the ``form_label`` fragment.
-In Twig, if you're making the form customization inside the same template as your
+If you're making the form customization inside the same template as your
form, modify the ``use`` tag and add the following:
.. code-block:: html+twig
@@ -881,7 +718,7 @@ form, modify the ``use`` tag and add the following:
{% endif %}
{% endblock %}
-In Twig, if you're making the form customization inside a separate template, use
+If you're making the form customization inside a separate template, use
the following:
.. code-block:: html+twig
@@ -896,24 +733,6 @@ the following:
{% endif %}
{% endblock %}
-When using PHP as a templating engine you have to copy the content from the
-original template:
-
-.. code-block:: html+php
-
-
-
-
-
-
- humanize($name); } ?>
-
-
-
-
- *
-
-
.. tip::
See :ref:`form-theming-methods` for how to apply this customization.
@@ -934,7 +753,7 @@ Adding "help" Messages
You can also customize your form widgets to have an optional "help" message.
-In Twig, if you're making the form customization inside the same template as your
+If you're making the form customization inside the same template as your
form, modify the ``use`` tag and add the following:
.. code-block:: html+twig
@@ -949,7 +768,7 @@ form, modify the ``use`` tag and add the following:
{% endif %}
{% endblock %}
-In Twig, if you're making the form customization inside a separate template, use
+If you're making the form customization inside a separate template, use
the following:
.. code-block:: html+twig
@@ -964,25 +783,6 @@ the following:
{% endif %}
{% endblock %}
-When using PHP as a templating engine you have to copy the content from the
-original template:
-
-.. code-block:: html+php
-
-
-
-
- value="escape($value) ?>"
- block($form, 'widget_attributes') ?>
- />
-
-
-
- escape($help) ?>
-
-
To render a help message below a field, pass in a ``help`` variable:
.. code-block:: twig
diff --git a/templating/PHP.rst b/templating/PHP.rst
index 86b1d5abc79..1c4b31fc96b 100644
--- a/templating/PHP.rst
+++ b/templating/PHP.rst
@@ -382,4 +382,220 @@ instance, to output something in a JavaScript script, use the ``js`` context::
escape($var, 'js') ?>
+Form Theming in PHP
+-------------------
+
+When using PHP as a templating engine, the only method to customize a fragment
+is to create a new template file - this is similar to the second method used by
+Twig.
+
+The template file must be named after the fragment. You must create a ``integer_widget.html.php``
+file in order to customize the ``integer_widget`` fragment.
+
+.. code-block:: html+php
+
+
+
+
+Now that you've created the customized form template, you need to tell Symfony
+to use it. Inside the template where you're actually rendering your form,
+tell Symfony to use the theme via the ``setTheme()`` helper method::
+
+ setTheme($form, array(':form')); ?>
+
+ widget($form['age']) ?>
+
+When the ``form.age`` widget is rendered, Symfony will use the customized
+``integer_widget.html.php`` template and the ``input`` tag will be wrapped in
+the ``div`` element.
+
+If you want to apply a theme to a specific child form, pass it to the ``setTheme()``
+method::
+
+ setTheme($form['child'], ':form'); ?>
+
+.. note::
+
+ The ``:form`` syntax is based on the functional names for templates:
+ ``Bundle:Directory``. As the form directory lives in the
+ ``app/Resources/views`` directory, the ``Bundle`` part is empty, resulting
+ in ``:form``.
+
+Making Application-wide Customizations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you'd like a certain form customization to be global to your application,
+you can accomplish this by making the form customizations in an external
+template and then importing it inside your application configuration.
+
+By using the following configuration, any customized form fragments inside the
+``app/Resources/views/Form`` folder will be used globally when a
+form is rendered.
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/config.yml
+ framework:
+ templating:
+ form:
+ resources:
+ - 'AppBundle:Form'
+ # ...
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+ AppBundle:Form
+
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/config.php
+ // PHP
+ $container->loadFromExtension('framework', array(
+ 'templating' => array(
+ 'form' => array(
+ 'resources' => array(
+ 'AppBundle:Form',
+ ),
+ ),
+ ),
+
+ // ...
+ ));
+
+By default, the PHP engine uses a *div* layout when rendering forms. Some people,
+however, may prefer to render forms in a *table* layout. Use the ``FrameworkBundle:FormTable``
+resource to use such a layout:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/config.yml
+ framework:
+ templating:
+ form:
+ resources:
+ - 'FrameworkBundle:FormTable'
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+ FrameworkBundle:FormTable
+
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/config.php
+ $container->loadFromExtension('framework', array(
+ 'templating' => array(
+ 'form' => array(
+ 'resources' => array(
+ 'FrameworkBundle:FormTable',
+ ),
+ ),
+ ),
+
+ // ...
+ ));
+
+If you only want to make the change in one template, add the following line to
+your template file rather than adding the template as a resource:
+
+.. code-block:: html+php
+
+ setTheme($form, array('FrameworkBundle:FormTable')); ?>
+
+Note that the ``$form`` variable in the above code is the form view variable
+that you passed to your template.
+
+Adding a "Required" Asterisk to Field Labels
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to denote all of your required fields with a required asterisk
+(``*``), you can do this by customizing the ``form_label`` fragment.
+
+When using PHP as a templating engine you have to copy the content from the
+original template:
+
+.. code-block:: html+php
+
+
+
+
+
+
+ humanize($name); } ?>
+
+
+
+
+ *
+
+
+Adding "help" Messages
+~~~~~~~~~~~~~~~~~~~~~~
+
+You can also customize your form widgets to have an optional "help" message.
+
+When using PHP as a templating engine you have to copy the content from the
+original template:
+
+.. code-block:: html+php
+
+
+
+
+ value="escape($value) ?>"
+ block($form, 'widget_attributes') ?>
+ />
+
+
+
+ escape($help) ?>
+
+
.. _`@Template`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/view