Merge branch '3.4' into 4.0

javiereguiluz · javiereguiluz · commit f52e138807d1 · 2018-07-09T17:53:00.000+02:00
* 3.4: [symfony#9803] fix minor typos [symfony#9836] fix a minor typo Fix the page title for the mbstring polyfill update Twig documentation links Update licence hint for JMS serializer Update external_resources.rst Add traits to BC policy Mention the DoctrineTestBundle for tests that interact with the database Added the missing versionadded directive Remove duplicate `use` keyword Add missing RuntimeExtensionInterface Document Twig test "rootform"
diff --git a/best_practices/configuration.rst b/best_practices/configuration.rst
@@ -183,4 +183,4 @@ just one or two words to describe the purpose of the parameter:
 Next: :doc:`/best_practices/business-logic`
 
 .. _`feature toggles`: https://en.wikipedia.org/wiki/Feature_toggle
-.. _`constant() function`: http://twig.sensiolabs.org/doc/functions/constant.html
+.. _`constant() function`: https://twig.symfony.com/doc/2.x/functions/constant.html
diff --git a/best_practices/templates.rst b/best_practices/templates.rst
@@ -118,5 +118,5 @@ be used as a Twig extension.
 
 Next: :doc:`/best_practices/forms`
 
-.. _`Twig`: http://twig.sensiolabs.org/
+.. _`Twig`: https://twig.symfony.com/
 .. _`Parsedown`: http://parsedown.org/
diff --git a/components/form.rst b/components/form.rst
@@ -757,5 +757,5 @@ Learn more
     /form/*
 
 .. _Packagist: https://packagist.org/packages/symfony/form
-.. _Twig: http://twig.sensiolabs.org
-.. _`Twig Configuration`: http://twig.sensiolabs.org/doc/intro.html
+.. _Twig: https://twig.symfony.com
+.. _`Twig Configuration`: https://twig.symfony.com/doc/2.x/intro.html
diff --git a/components/polyfill_mbstring.rst b/components/polyfill_mbstring.rst
@@ -3,8 +3,8 @@
     single: Mbstring
     single: Components; Polyfill
 
-The Symfony Polyfill / Intl Mbstring Component
-==============================================
+The Symfony Polyfill / Mbstring Component
+=========================================
 
     This component provides a partial, native PHP implementation for the
     ``mbstring`` PHP extension.
diff --git a/components/serializer.rst b/components/serializer.rst
@@ -1024,7 +1024,7 @@ Learn more
 .. seealso::
 
     A popular alternative to the Symfony Serializer Component is the third-party
-    library, `JMS serializer`_ (released under the Apache license, so incompatible with GPLv2 projects).
+    library, `JMS serializer`_ (versions before `v1.12.0` were released under the Apache license, so incompatible with GPLv2 projects).
 
 .. _`PSR-1 standard`: https://www.php-fig.org/psr/psr-1/
 .. _`JMS serializer`: https://github.com/schmittjoh/serializer
diff --git a/contributing/code/bc.rst b/contributing/code/bc.rst
@@ -143,6 +143,41 @@ covered by our backward compatibility promise:
 | Access a private property (via Reflection)    | No                          |
 +-----------------------------------------------+-----------------------------+
 
+Using our Traits
+~~~~~~~~~~~~~~~~
+
+All traits provided by Symfony may be used in your classes.
+
+.. caution::
+
+    The exception to this rule are traits tagged with ``@internal``. Such
+    traits should not be used.
+
+To be on the safe side, check the following table to know which use cases are
+covered by our backward compatibility promise:
+
++-----------------------------------------------+-----------------------------+
+| Use Case                                      | Backward Compatibility      |
++===============================================+=============================+
+| **If you...**                                 | **Then we guarantee BC...** |
++-----------------------------------------------+-----------------------------+
+| Use a trait                                   | Yes                         |
++-----------------------------------------------+-----------------------------+
+| **If you use the trait and...**               | **Then we guarantee BC...** |
++-----------------------------------------------+-----------------------------+
+| Use it to implement an interface              | Yes                         |
++-----------------------------------------------+-----------------------------+
+| Use it to implement an abstract method        | Yes                         |
++-----------------------------------------------+-----------------------------+
+| Use it to extend a parent class               | Yes                         |
++-----------------------------------------------+-----------------------------+
+| Use it to define an abstract class            | Yes                         |
++-----------------------------------------------+-----------------------------+
+| Use a public, protected or private property   | Yes                         |
++-----------------------------------------------+-----------------------------+
+| Use a public, protected or private method     | Yes                         |
++-----------------------------------------------+-----------------------------+
+
 Working on Symfony Code
 -----------------------
 
@@ -178,6 +213,9 @@ Change argument type                            No
 Add return type                                 No
 Remove return type                              No [9]_
 Change return type                              No
+**Static Methods**
+Turn non static into static                     No
+Turn static into non static                     No
 **Constants**
 Add constant                                    Yes
 Remove constant                                 No
@@ -209,21 +247,28 @@ Move to parent class                                Yes
 Add protected property                              Yes
 Remove protected property                           No [7]_
 Reduce visibility                                   No [7]_
+Make public                                         No [7]_
 Move to parent class                                Yes
 **Private Properties**
 Add private property                                Yes
+Make public or protected                            Yes
 Remove private property                             Yes
 **Constructors**
 Add constructor without mandatory arguments         Yes [1]_
 Remove constructor                                  No
 Reduce visibility of a public constructor           No
 Reduce visibility of a protected constructor        No [7]_
 Move to parent class                                Yes
+**Destructors**
+Add destructor                                      Yes
+Remove destructor                                   No
+Move to parent class                                Yes
 **Public Methods**
 Add public method                                   Yes
 Remove public method                                No
 Change name                                         No
 Reduce visibility                                   No
+Make final                                          No [6]_
 Move to parent class                                Yes
 Add argument without a default value                No
 Add argument with a default value                   No [7]_ [8]_
@@ -241,6 +286,8 @@ Add protected method                                Yes
 Remove protected method                             No [7]_
 Change name                                         No [7]_
 Reduce visibility                                   No [7]_
+Make final                                          No [6]_
+Make public                                         No [7]_ [8]_
 Move to parent class                                Yes
 Add argument without a default value                No [7]_
 Add argument with a default value                   No [7]_ [8]_
@@ -257,6 +304,7 @@ Change return type                                  No [7]_ [8]_
 Add private method                                  Yes
 Remove private method                               Yes
 Change name                                         Yes
+Make public or protected                            Yes
 Add argument without a default value                Yes
 Add argument with a default value                   Yes
 Remove argument                                     Yes
@@ -268,7 +316,7 @@ Change argument type                                Yes
 Add return type                                     Yes
 Remove return type                                  Yes
 Change return type                                  Yes
-**Static Methods**
+**Static Methods and Properties**
 Turn non static into static                         No [7]_ [8]_
 Turn static into non static                         No
 **Constants**
@@ -277,6 +325,91 @@ Remove constant                                     No
 Change value of a constant                          Yes [1]_ [5]_
 ==================================================  ==============
 
+Changing Traits
+~~~~~~~~~~~~~~~
+
+This table tells you which changes you are allowed to do when working on
+Symfony's traits:
+
+==================================================  ==============
+Type of Change                                      Change Allowed
+==================================================  ==============
+Remove entirely                                     No
+Change name or namespace                            No
+Use another trait                                   Yes
+**Public Properties**
+Add public property                                 Yes
+Remove public property                              No
+Reduce visibility                                   No
+Move to a used trait                                Yes
+**Protected Properties**
+Add protected property                              Yes
+Remove protected property                           No
+Reduce visibility                                   No
+Make public                                         No
+Move to a used trait                                Yes
+**Private Properties**
+Add private property                                Yes
+Remove private property                             No
+Make public or protected                            Yes
+Move to a used trait                                Yes
+**Constructors and destructors**
+Have constructor or destructor                      No
+**Public Methods**
+Add public method                                   Yes
+Remove public method                                No
+Change name                                         No
+Reduce visibility                                   No
+Make final                                          No [6]_
+Move to used trait                                  Yes
+Add argument without a default value                No
+Add argument with a default value                   No
+Remove argument                                     No
+Add default value to an argument                    No
+Remove default value of an argument                 No
+Add type hint to an argument                        No
+Remove type hint of an argument                     No
+Change argument type                                No
+Change return type                                  No
+**Protected Methods**
+Add protected method                                Yes
+Remove protected method                             No
+Change name                                         No
+Reduce visibility                                   No
+Make final                                          No [6]_
+Make public                                         No [8]_
+Move to used trait                                  Yes
+Add argument without a default value                No
+Add argument with a default value                   No
+Remove argument                                     No
+Add default value to an argument                    No
+Remove default value of an argument                 No
+Add type hint to an argument                        No
+Remove type hint of an argument                     No
+Change argument type                                No
+Change return type                                  No
+**Private Methods**
+Add private method                                  Yes
+Remove private method                               No
+Change name                                         No
+Make public or protected                            Yes
+Move to used trait                                  Yes
+Add argument without a default value                No
+Add argument with a default value                   No
+Remove argument                                     No
+Add default value to an argument                    No
+Remove default value of an argument                 No
+Add type hint to an argument                        No
+Remove type hint of an argument                     No
+Change argument type                                No
+Add return type                                     No
+Remove return type                                  No
+Change return type                                  No
+**Static Methods and Properties**
+Turn non static into static                         No
+Turn static into non static                         No
+==================================================  ==============
+
 .. [1] Should be avoided. When done, this change must be documented in the
        UPGRADE file.
 
diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst
@@ -174,7 +174,7 @@ In addition, documentation follows these rules:
   * himself or herself, use themselves
 
 .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
-.. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html
+.. _`Twig Coding Standards`: https://twig.symfony.com/doc/2.x/coding_standards.html
 .. _`reserved by the IANA`: http://tools.ietf.org/html/rfc2606#section-3
 .. _`American English`: https://en.wikipedia.org/wiki/American_English
 .. _`American English Oxford Dictionary`: http://en.oxforddictionaries.com/definition/american_english/
diff --git a/create_framework/http_foundation.rst b/create_framework/http_foundation.rst
@@ -288,7 +288,7 @@ component is the start of better interoperability between all frameworks and
 applications using it (like `Symfony`_, `Drupal 8`_, `phpBB 3`_, `ezPublish
 5`_, `Laravel`_, `Silex`_ and `more`_).
 
-.. _`Twig`: http://twig.sensiolabs.org/
+.. _`Twig`: https://twig.symfony.com/
 .. _`HTTP specification`: https://tools.ietf.org/wg/httpbis/
 .. _`audited`: https://symfony.com/blog/symfony2-security-audit
 .. _`Symfony`: https://symfony.com/
diff --git a/introduction/from_flat_php_to_symfony2.rst b/introduction/from_flat_php_to_symfony2.rst
@@ -709,5 +709,5 @@ A good selection of `Symfony community tools`_ can be found on GitHub.
 .. _`download Composer`: https://getcomposer.org/download/
 .. _`Validator`: https://github.com/symfony/validator
 .. _`Varnish`: https://www.varnish-cache.org/
-.. _`Twig`: http://twig.sensiolabs.org
+.. _`Twig`: https://twig.symfony.com
 .. _`Symfony community tools`: https://github.com/search?q=topic%3Asymfony-bundle&type=Repositories
diff --git a/page_creation.rst b/page_creation.rst
@@ -352,7 +352,7 @@ Go Deeper with HTTP & Framework Fundamentals
 
     introduction/*
 
-.. _`Twig`: http://twig.sensiolabs.org
+.. _`Twig`: https://twig.symfony.com
 .. _`Composer`: https://getcomposer.org
 .. _`Stellar Development with Symfony`: https://knpuniversity.com/screencast/symfony/setup
 .. _`symfony.sh`: https://symfony.sh/
diff --git a/reference/configuration/twig.rst b/reference/configuration/twig.rst
@@ -366,4 +366,4 @@ If set to ``true``, Symfony shows an exception whenever a Twig variable,
 attribute or method doesn't exist. If set to ``false`` these errors are ignored
 and the non-existing values are replaced by ``null``.
 
-.. _`the optimizer extension`: http://twig.sensiolabs.org/doc/api.html#optimizer-extension
+.. _`the optimizer extension`: https://twig.symfony.com/doc/2.x/api.html#optimizer-extension
diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst
@@ -1183,8 +1183,8 @@ Then, tag it with the ``validator.initializer`` tag (it has no options).
 For an example, see the ``DoctrineInitializer`` class inside the Doctrine
 Bridge.
 
-.. _`Twig's documentation`: http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension
+.. _`Twig's documentation`: https://twig.symfony.com/doc/2.x/advanced.html#creating-an-extension
 .. _`Twig official extension repository`: https://github.com/fabpot/Twig-extensions
 .. _`KernelEvents`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/KernelEvents.php
 .. _`SwiftMailer's Plugin Documentation`: http://swiftmailer.org/docs/plugins.html
-.. _`Twig Loader`: http://twig.sensiolabs.org/doc/api.html#loaders
+.. _`Twig Loader`: https://twig.symfony.com/doc/2.x/api.html#loaders
diff --git a/reference/forms/twig_reference.rst b/reference/forms/twig_reference.rst
@@ -199,6 +199,28 @@ array).
 
     <option {% if choice is selectedchoice(value) %} selected="selected"{% endif %} ...>
 
+.. _form-twig-rootform:
+
+rootform
+~~~~~~~~
+
+This test will check if the current ``form`` does not have a parent form view.
+
+.. code-block:: twig
+
+    {# DON'T DO THIS: this simple check can't differentiate between a form having
+       a parent form view and a form defining a normal form field called 'parent' #}
+
+    {% if form.parent is null %}
+        {{ form_errors(form) }}
+    {% endif %}
+
+   {# DO THIS: this check is always reliable, even if the form defines a field called 'parent' #}
+
+    {% if form is rootform %}
+        {{ form_errors(form) }}
+    {% endif %}
+
 .. _`twig-reference-form-variables`:
 
 More about Form Variables
@@ -359,4 +381,4 @@ done by using a public ``vars`` property on the
 +------------------------+-------------------------------------------------------------------------------------+
 
 .. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
-.. _`the Twig documentation`: http://twig.sensiolabs.org/doc/templates.html#test-operator
+.. _`the Twig documentation`: https://twig.symfony.com/doc/2.x/templates.html#test-operator
diff --git a/reference/twig_reference.rst b/reference/twig_reference.rst
@@ -723,6 +723,20 @@ selectedchoice
 Checks if ``selectedValue`` was checked for the provided choice field. Using
 this test is the most effective way.
 
+rootform
+~~~~~~~~
+
+.. code-block:: twig
+
+    {% if form is rootform %}
+
+``form``
+    **type**: ``FormView``
+
+Checks if the given ``form`` does not have a parent form view. This is the only
+safe way of testing it because checking if the form contains a field called
+``parent`` is not reliable.
+
 Global Variables
 ----------------
 
@@ -746,7 +760,7 @@ The available attributes are:
   object representing the security token
 * ``app.flashes``, returns flash messages from the session
 
-.. _`Twig Reference`: http://twig.sensiolabs.org/documentation#reference
+.. _`Twig Reference`: https://twig.symfony.com/doc/2.x/#reference
 .. _`Twig Extensions repository`: https://github.com/twigphp/Twig-extensions
 .. _`Twig Extensions documentation`: http://twig-extensions.readthedocs.io/en/latest/
 .. _`Twig Bridge`: https://github.com/symfony/symfony/tree/master/src/Symfony/Bridge/Twig/Extension
diff --git a/routing/external_resources.rst b/routing/external_resources.rst
@@ -98,7 +98,7 @@ suppose you want to prefix all application routes with ``/site`` (e.g.
 
     .. code-block:: php-annotations
 
-        use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+        use Symfony\Component\Routing\Annotation\Route;
 
         /**
          * @Route("/site")
diff --git a/setup/_update_dep_errors.rst.inc b/setup/_update_dep_errors.rst.inc
@@ -21,9 +21,9 @@ Or, you may have deeper issues where different libraries depend on conflicting
 versions of other libraries. Check your error message to debug.
 
 Another issue that may happen is that the project dependencies can be installed
-in your local computer but not on the remote server. This usually happens when
+on your local computer but not on the remote server. This usually happens when
 the PHP versions are different on each machine. The solution is to add the
-`platform`_ config option in your `composer.json` file to define the highest
-PHP version allowed for the dependencies (set it to server's PHP version).
+`platform`_ config option to your `composer.json` file to define the highest
+PHP version allowed for the dependencies (set it to the server's PHP version).
 
 .. _`platform`: https://getcomposer.org/doc/06-config.md#platform
diff --git a/templating.rst b/templating.rst
@@ -808,11 +808,11 @@ Learn more
 
     /templating/*
 
-.. _`Twig`: http://twig.sensiolabs.org
-.. _`tags`: http://twig.sensiolabs.org/doc/tags/index.html
-.. _`filters`: http://twig.sensiolabs.org/doc/filters/index.html
-.. _`functions`: http://twig.sensiolabs.org/doc/functions/index.html
-.. _`add your own extensions`: http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension
-.. _`with_context`: http://twig.sensiolabs.org/doc/functions/include.html
-.. _`include() function`: http://twig.sensiolabs.org/doc/functions/include.html
-.. _`{% include %} tag`: http://twig.sensiolabs.org/doc/tags/include.html
+.. _`Twig`: https://twig.symfony.com
+.. _`tags`: https://twig.symfony.com/doc/2.x/tags/index.html
+.. _`filters`: https://twig.symfony.com/doc/2.x/filters/index.html
+.. _`functions`: https://twig.symfony.com/doc/2.x/functions/index.html
+.. _`add your own extensions`: https://twig.symfony.com/doc/2.x/advanced.html#creating-an-extension
+.. _`with_context`: https://twig.symfony.com/doc/2.x/functions/include.html
+.. _`include() function`: https://twig.symfony.com/doc/2.x/functions/include.html
+.. _`{% include %} tag`: https://twig.symfony.com/doc/2.x/tags/include.html
diff --git a/templating/escaping.rst b/templating/escaping.rst
diff --git a/templating/twig_extension.rst b/templating/twig_extension.rst
diff --git a/testing/database.rst b/testing/database.rst
diff --git a/testing/profiling.rst b/testing/profiling.rst
