Merge branch '3.4'

* 3.4: (27 commits)
  [#8549] update ordered list syntax
  Minor tweaks
  Add default_path option reference
  [Form] Add debug:form command to debug page
  Added option to disable type enforcement in serializer
  Explained the possibility of defining custom deprecation messages
  [config] Add a note about deprecated a node
  [#8471] minor reword
  Explained the DomCrawler charset guessing mechanism
  Added a bundle deprecation notice in other articles
  [#8497] fix typo
  Updated Guard article for the GuardAuthenticatorInterface deprecation
  Deprecate auto picking the first provider
  Explain the new ColorType a bit more
  Explain the new TelType a bit more
  add doc for new tel and color types
  Update tags.rst
  Update tags.rst
  Update tags.rst
  Update tags.rst
  ...

Author: xabbuh

bundles/override.rst

@@ -5,7 +5,8 @@ How to Override any Part of a Bundle
 ====================================
 
 This document is a quick reference for how to override different parts of
-third-party bundles.
+third-party bundles without using :doc:`/bundles/inheritance`, which is
+deprecated since Symfony 3.4.
 
 .. tip::
 
@@ -18,10 +19,7 @@ third-party bundles.
 Templates
 ---------
 
-For information on overriding templates, see
-
-* :doc:`/templating/overriding`.
-* :doc:`/bundles/inheritance`
+See :doc:`/templating/overriding`.
 
 Routing
 -------
@@ -37,10 +35,10 @@ that routing file into your application, modify it, and import it instead.
 Controllers
 -----------
 
-Assuming the third-party bundle involved uses non-service controllers (which
-is almost always the case), you can easily override controllers via bundle
-inheritance. For more information, see :doc:`/bundles/inheritance`.
 If the controller is a service, see the next section on how to override it.
+Otherwise, define a new route + controller with the same path associated to the
+controller you want to override (and make sure that the new route is loaded
+before the bundle one).
 
 Services & Configuration
 ------------------------
@@ -152,13 +150,4 @@ Translations are not related to bundles, but to domains. That means that you
 can override the translations from any translation file, as long as it is in
 :ref:`the correct domain <using-message-domains>`.
 
-.. caution::
-
-    Translation files are not aware of :doc:`bundle inheritance </bundles/inheritance>`.
-    If you want to override translations from the parent bundle or another bundle,
-    make sure that the bundle containing *your* translations is loaded after any
-    bundle whose translations you're overriding. This is done in ``AppKernel``.
-
-    Finally, translations located in ``app/Resources/translations`` will override
-    all the other translations since those files are always loaded last.
 .. _`the Doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides

components/config/definition.rst

@@ -424,6 +424,29 @@ has a certain value:
         ->end()
     ;
 
+Deprecating the Option
+----------------------
+
+You can deprecate options using the
+:method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::setDeprecated`
+method::
+
+    $rootNode
+        ->children()
+            ->integerNode('old_option')
+                // this outputs the following generic deprecation message:
+                // The child node "old_option" at path "..." is deprecated.
+                ->setDeprecated()
+
+                // you can also pass a custom deprecation message (%node% and %path% placeholders are available):
+                ->setDeprecated('The "%node%" option is deprecated. Use "new_config_option" instead.')
+            ->end()
+        ->end()
+    ;
+
+If you use the Web Debug Toolbar, these deprecation notices are shown when the
+configuration is rebuilt.
+
 Documenting the Option
 ----------------------
 

components/dom_crawler.rst

@@ -237,10 +237,19 @@ The crawler supports multiple ways of adding the content::
 
 .. note::
 
-    When dealing with character sets other than ISO-8859-1, always add HTML
-    content using the :method:`Symfony\\Component\\DomCrawler\\Crawler::addHtmlContent`
-    method where you can specify the second parameter to be your target character
-    set.
+    The :method:`Symfony\\Component\\DomCrawler\\Crawler::addHtmlContent` and
+    :method:`Symfony\\Component\\DomCrawler\\Crawler::addXmlContent` methods
+    default to UTF-8 encoding but you can change this behavior with their second
+    optional argument.
+
+    The :method:`Symfony\\Component\\DomCrawler\\Crawler::addContent` method
+    guesses the best charset according to the given contents and defaults to
+    ``ISO-8859-1`` in case no charset can be guessed.
+
+    .. versionadded:: 3.4
+        The charset guessing mechanism of the ``addContent()`` method was
+        introduced in Symfony 3.4. In previous Symfony versions, the ``ISO-8859-1``
+        charset was always used.
 
 As the Crawler's implementation is based on the DOM extension, it is also able
 to interact with native :phpclass:`DOMDocument`, :phpclass:`DOMNodeList`
@@ -397,13 +406,13 @@ a :class:`Symfony\\Component\\DomCrawler\\Form` object that represents the
 form that the button lives in::
 
     // button example: <button id="my-super-button" type="submit">My super button</button>
-    
+
     // you can get button by its label
     $form = $crawler->selectButton('My super button')->form();
-    
+
     // or by button id (#my-super-button) if the button doesn't have a label
     $form = $crawler->selectButton('my-super-button')->form();
-    
+
     // or you can filter the whole form, for example a form has a class attribute: <form class="form-vertical" method="POST">
     $crawler->filter('.form-vertical')->form();
 

components/finder.rst

@@ -69,7 +69,12 @@ the Finder instance.
 Criteria
 --------
 
-There are lots of ways to filter and sort your results.
+There are lots of ways to filter and sort your results. You can also use the
+:method:`Symfony\\Component\\Finder\\Finder::hasResults` method to check if
+there's any file or directory matching the search criteria.
+
+.. versionadded:: 3.4
+    The ``hasResults()`` method was introduced in Symfony 3.4.
 
 Location
 ~~~~~~~~

components/serializer.rst

@@ -877,7 +877,7 @@ parameter of the ``ObjectNormalizer``::
         public $bar;
     }
 
-    $normalizer = new ObjectNormalizer(null, null, null, new ReflectionExtractor()); //
+    $normalizer = new ObjectNormalizer(null, null, null, new ReflectionExtractor());
     $serializer = new Serializer(array(new DateTimeNormalizer(), $normalizer));
 
     $obj = $serializer->denormalize(
@@ -892,7 +892,9 @@ parameter of the ``ObjectNormalizer``::
 When a ``PropertyTypeExtractor`` is available, the normalizer will also check that the data to denormalize
 matches the type of the property (even for primitive types). For instance, if a ``string`` is provided, but
 the type of the property is ``int``, an :class:`Symfony\\Component\\Serializer\\Exception\\UnexpectedValueException`
-will be thrown.
+will be thrown. The type enforcement of the properties can be disabled by setting
+the serializer context option ``ObjectNormalizer::DISABLE_TYPE_ENFORCEMENT``
+to ``true``.
 
 Learn more
 ----------

debug/debugging.rst

@@ -27,6 +27,9 @@ that can help you visualize and find the information.
 
 ``debug:config``
     Shows all configured bundles, their class and their alias.
+    
+``debug:form``
+    Displays information about form types and their options.
 
 ``debug:event-dispatcher``
     Displays information about all the registered listeners in the event dispatcher.

form/form_customization.rst

@@ -113,10 +113,17 @@ fragment needed to render every part of a form:
 * `bootstrap_3_horizontal_layout.html.twig`_, it's similar to the previous theme,
   but the CSS classes applied are the ones used to display the forms horizontally
   (i.e. the label and the widget in the same row).
+* `bootstrap_4_layout.html.twig`_, same as ``bootstrap_3_layout.html.twig``, but
+  updated for `Bootstrap 4 CSS framework`_ styles.
+* `bootstrap_4_horizontal_layout.html.twig`_, same as ``bootstrap_3_horizontal_layout.html.twig``
+  but updated for Bootstrap 4 styles.
 * `foundation_5_layout.html.twig`_, wraps each form field inside a ``<div>`` element
   with the appropriate CSS classes to apply the default `Foundation CSS framework`_
   styles.
 
+.. versionadded:: 3.4
+    The Bootstrap 4 form themes were introduced in Symfony 3.4.
+
 .. caution::
 
     When you use the Bootstrap form themes and render the fields manually,
@@ -211,7 +218,7 @@ this folder.
     In this example, the customized fragment name is ``integer_widget`` because
     you want to override the HTML ``widget`` for all ``integer`` field types. If
     you need to customize ``textarea`` fields, you would customize ``textarea_widget``.
-    
+
     The ``integer`` part comes from the class name: ``IntegerType`` becomes ``integer``,
     based on a standard.
 
@@ -1174,6 +1181,9 @@ more details about this concept in Twig, see :ref:`twig-reference-form-variables
 .. _`form_table_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_table_layout.html.twig
 .. _`bootstrap_3_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_layout.html.twig
 .. _`bootstrap_3_horizontal_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_horizontal_layout.html.twig
-.. _`Bootstrap 3 CSS framework`: http://getbootstrap.com/
+.. _`bootstrap_4_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_layout.html.twig
+.. _`bootstrap_4_horizontal_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_4_horizontal_layout.html.twig
+.. _`Bootstrap 3 CSS framework`: https://getbootstrap.com/docs/3.3/
+.. _`Bootstrap 4 CSS framework`: https://getbootstrap.com/docs/4.0/
 .. _`foundation_5_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/foundation_5_layout.html.twig
 .. _`Foundation CSS framework`: http://foundation.zurb.com/

reference/configuration/twig.rst

@@ -20,6 +20,8 @@ TwigBundle Configuration ("twig")
                 # Bootstrap:
                 - bootstrap_3_layout.html.twig
                 - bootstrap_3_horizontal_layout.html.twig
+                - bootstrap_4_layout.html.twig
+                - bootstrap_4_horizontal_layout.html.twig
 
                 # Foundation
                 - foundation_5_layout.html.twig
@@ -52,6 +54,7 @@ TwigBundle Configuration ("twig")
             strict_variables:          ~
             auto_reload:               ~
             optimizations:             ~
+            default_path: '%kernel.project_dir%/templates'
             paths:
                 '%kernel.project_dir%/vendor/acme/foo-bar/templates': foo_bar
 
@@ -85,13 +88,14 @@ TwigBundle Configuration ("twig")
                 debug="%kernel.debug%"
                 strict-variables="false"
                 optimizations="true"
+                default-path="%kernel.project_dir%/templates"
             >
                 <twig:form-theme>form_div_layout.html.twig</twig:form-theme> <!-- Default -->
                 <twig:form-theme>form.html.twig</twig:form-theme>
 
                 <twig:global key="foo" id="bar" type="service" />
                 <twig:global key="pi">3.14</twig:global>
-                
+
                 <twig:date format="d.m.Y, H:i:s" interval-format="%d days" timezone="Asia/Tokyo" />
                 <twig:number-format decimals="2" decimal-point="," thousands-separator="." />
 
@@ -134,6 +138,7 @@ TwigBundle Configuration ("twig")
                 'decimal_point' => ',',
                 'thousands_separator' => '.',
             ),
+            'default_path' => '%kernel.project_dir%/templates',
         ));
 
 .. caution::
@@ -336,6 +341,16 @@ on. Set it to ``0`` to disable all the optimizations. You can even enable or
 disable these optimizations selectively, as explained in the Twig documentation
 about `the optimizer extension`_.
 
+default_path
+~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``'%kernel.project_dir%/templates'``
+
+.. versionadded:: 3.4
+    The ``default_path`` option was introduced in Symfony 3.4.
+
+The default directory where Symfony will look for Twig templates.
+
 .. _config-twig-paths:
 
 paths
@@ -344,9 +359,13 @@ paths
 **type**: ``array`` **default**: ``null``
 
 This option defines the directories where Symfony will look for Twig templates
-in addition to the default locations (``app/Resources/views/`` and the bundles'
-``Resources/views/`` directories). This is useful to integrate the templates
-included in some library or package used by your application.
+in addition to the default locations. Symfony looks for the templates in the
+following order:
+
+#. The directories defined in this option;
+#. The ``Resources/views/`` directories of the bundles used in the application;
+#. The ``src/Resources/views/`` directory of the application;
+#. The directory defined in the ``default_path`` option.
 
 The values of the ``paths`` option are defined as ``key: value`` pairs where the
 ``value`` part can be ``null``. For example:

reference/forms/types.rst

@@ -19,6 +19,8 @@ Form Types Reference
    types/search
    types/url
    types/range
+   types/tel
+   types/color
 
    types/choice
    types/entity

reference/forms/types/color.rst

@@ -0,0 +1,68 @@
+.. index::
+   single: Forms; Fields; ColorType
+
+ColorType Field
+===============
+
+The ``ColorType`` field is a text field that is rendered using the HTML5
+``<input type="color">`` tag. Depending on each browser, the behavior of this
+form field can vary substantially. Some browsers display it as a simple text
+field, while others display a native color picker.
+
+The value of the underlying ``<input type="color">`` field is always a
+7-character string specifying an RGB color in lower case hexadecimal notation.
+That's why it's not possible to select semi-transparent colors with this
+element.
+
++-------------+---------------------------------------------------------------------+
+| Rendered as | ``input`` ``color`` field (a text box)                              |
++-------------+---------------------------------------------------------------------+
+| Inherited   | - `data`_                                                           |
+| options     | - `disabled`_                                                       |
+|             | - `empty_data`_                                                     |
+|             | - `error_bubbling`_                                                 |
+|             | - `error_mapping`_                                                  |
+|             | - `label`_                                                          |
+|             | - `label_attr`_                                                     |
+|             | - `label_format`_                                                   |
+|             | - `mapped`_                                                         |
+|             | - `required`_                                                       |
+|             | - `trim`_                                                           |
++-------------+---------------------------------------------------------------------+
+| Parent type | :doc:`TextType </reference/forms/types/text>`                       |
++-------------+---------------------------------------------------------------------+
+| Class       | :class:`Symfony\\Component\\Form\\Extension\\Core\\Type\\ColorType` |
++-------------+---------------------------------------------------------------------+
+
+Inherited Options
+-----------------
+
+These options inherit from the :doc:`FormType </reference/forms/types/form>`:
+
+.. include:: /reference/forms/types/options/data.rst.inc
+
+.. include:: /reference/forms/types/options/disabled.rst.inc
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :end-before: DEFAULT_PLACEHOLDER
+
+The default value is ``''`` (the empty string).
+
+.. include:: /reference/forms/types/options/empty_data.rst.inc
+    :start-after: DEFAULT_PLACEHOLDER
+
+.. include:: /reference/forms/types/options/error_bubbling.rst.inc
+
+.. include:: /reference/forms/types/options/error_mapping.rst.inc
+
+.. include:: /reference/forms/types/options/label.rst.inc
+
+.. include:: /reference/forms/types/options/label_attr.rst.inc
+
+.. include:: /reference/forms/types/options/label_format.rst.inc
+
+.. include:: /reference/forms/types/options/mapped.rst.inc
+
+.. include:: /reference/forms/types/options/required.rst.inc
+
+.. include:: /reference/forms/types/options/trim.rst.inc