Merge branch '5.2' into 5.x

javiereguiluz · javiereguiluz · commit c095889f7ace · 2020-12-30T17:14:46.000+01:00
* 5.2:
  Fixing function name
  Shortening the text some more
  Shortening the text and adding link to jQuery
  Allow to configure trusted proxies and headers using config options
  Replace link to getConfiguration method
  Add Firebase notifier to documentation
diff --git a/bundles/configuration.rst b/bundles/configuration.rst
@@ -330,7 +330,7 @@ As long as your bundle's configuration is located in the standard location
 (``YourBundle\DependencyInjection\Configuration``) and does not have
 a constructor it will work automatically. If you
 have something different, your ``Extension`` class must override the
-:method:`Extension::getConfiguration() <Symfony\\Component\\HttpKernel\\DependencyInjection\\Extension::getConfiguration>`
+:method:`Extension::getConfiguration() <Symfony\\Component\\DependencyInjection\\Extension\\Extension::getConfiguration>`
 method and return an instance of your ``Configuration``.
 
 Supporting XML
diff --git a/deployment/proxies.rst b/deployment/proxies.rst
@@ -22,28 +22,69 @@ Solution: ``setTrustedProxies()``
 ---------------------------------
 
 To fix this, you need to tell Symfony which reverse proxy IP addresses to trust
-and what headers your reverse proxy uses to send information::
-
-    // public/index.php
-
-    // ...
-    $request = Request::createFromGlobals();
-
-    // tell Symfony about your reverse proxy
-    Request::setTrustedProxies(
-        // the IP address (or range) of your proxy
-        ['192.0.0.1', '10.0.0.0/8'],
-
-        // trust *all* "X-Forwarded-*" headers
-        Request::HEADER_X_FORWARDED_FOR | Request::HEADER_X_FORWARDED_HOST | Request::HEADER_X_FORWARDED_PORT | Request::HEADER_X_FORWARDED_PROTO
-
-        // or, if your proxy instead uses the "Forwarded" header
-        // Request::HEADER_FORWARDED
-
-        // or, if you're using a well-known proxy
-        // Request::HEADER_X_FORWARDED_AWS_ELB
-        // Request::HEADER_X_FORWARDED_TRAEFIK
-    );
+and what headers your reverse proxy uses to send information:
+
+.. configuration-block::
+
+    .. config-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            # ...
+            // the IP address (or range) of your proxy
+            trusted_proxies: '192.0.0.1,10.0.0.0/8'
+            // trust *all* "X-Forwarded-*" headers (the ! prefix means to not trust those headers)
+            trusted_headers: ['x-forwarded-all', '!x-forwarded-host', '!x-forwarded-prefix']
+            // or, if your proxy instead uses the "Forwarded" header
+            trusted_headers: ['forwarded', '!x-forwarded-host', '!x-forwarded-prefix']
+            // or, if you're using a wellknown proxy
+            trusted_headers: [!php/const Symfony\\Component\\HttpFoundation\\Request::HEADER_X_FORWARDED_AWS_ELB, '!x-forwarded-host', '!x-forwarded-prefix']
+            trusted_headers: [!php/const Symfony\\Component\\HttpFoundation\\Request::HEADER_X_FORWARDED_TRAEFIK, '!x-forwarded-host', '!x-forwarded-prefix']
+
+    .. config-block:: xml
+
+        <!-- config/packages/framework.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony
+                https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <!-- the IP address (or range) of your proxy -->
+                <framework:trusted-proxies>192.0.0.1,10.0.0.0/8</framework:trusted-proxies>
+
+                <!-- trust *all* "X-Forwarded-*" headers (the ! prefix means to not trust those headers) -->
+                <framework:trusted-header>x-forwarded-all</framework:trusted-header>
+                <framework:trusted-header>!x-forwarded-host</framework:trusted-header>
+                <framework:trusted-header>!x-forwarded-prefix</framework:trusted-header>
+
+                <!-- or, if your proxy instead uses the "Forwarded" header -->
+                <framework:trusted-header>forwarded</framework:trusted-header>
+                <framework:trusted-header>!x-forwarded-host</framework:trusted-header>
+                <framework:trusted-header>!x-forwarded-prefix</framework:trusted-header>
+            </framework:config>
+        </container>
+
+    .. config-block:: php
+
+        // config/packages/framework.php
+        use Symfony\Component\HttpFoundation\Request;
+
+        $container->loadFromExtension('framework', [
+            // the IP address (or range) of your proxy
+            'trusted_proxies' => '192.0.0.1,10.0.0.0/8',
+            // trust *all* "X-Forwarded-*" headers (the ! prefix means to not trust those headers)
+            'trusted_headers' => ['x-forwarded-all', '!x-forwarded-host', '!x-forwarded-prefix'],
+            // or, if your proxy instead uses the "Forwarded" header
+            'trusted_headers' => ['forwarded', '!x-forwarded-host', '!x-forwarded-prefix'],
+            // or, if you're using a wellknown proxy
+            'trusted_headers' => [Request::HEADER_X_FORWARDED_AWS_ELB, '!x-forwarded-host', '!x-forwarded-prefix'],
+            'trusted_headers' => [Request::HEADER_X_FORWARDED_TRAEFIK, '!x-forwarded-host', '!x-forwarded-prefix'],
+        ]);
 
 .. deprecated:: 5.2
 
@@ -61,6 +102,13 @@ The Request object has several ``Request::HEADER_*`` constants that control exac
 *which* headers from your reverse proxy are trusted. The argument is a bit field,
 so you can also pass your own value (e.g. ``0b00110``).
 
+.. versionadded:: 5.2
+
+    The feature to configure trusted proxies and headers with ``trusted_proxies``
+    and ``trusted_headers`` options was introduced in Symfony 5.2. In earlier
+    Symfony versions you needed to use the ``Request::setTrustedProxies()``
+    method in the ``public/index.php`` file.
+
 But what if the IP of my Reverse Proxy Changes Constantly!
 ----------------------------------------------------------
 
@@ -74,17 +122,17 @@ In this case, you'll need to - *very carefully* - trust *all* proxies.
 #. Once you've guaranteed that traffic will only come from your trusted reverse
    proxies, configure Symfony to *always* trust incoming request::
 
-       // public/index.php
+    .. config-block:: yaml
 
-       // ...
-       Request::setTrustedProxies(
-           // trust *all* requests (the 'REMOTE_ADDR' string is replaced at
-           // run time by $_SERVER['REMOTE_ADDR'])
-           ['127.0.0.1', 'REMOTE_ADDR'],
+        # config/packages/framework.yaml
+        framework:
+            # ...
+            // trust *all* requests (the 'REMOTE_ADDR' string is replaced at
+            // run time by $_SERVER['REMOTE_ADDR'])
+            trusted_proxies: '127.0.0.1,REMOTE_ADDR'
 
-           // if you're using ELB, otherwise use a constant from above
-           Request::HEADER_X_FORWARDED_AWS_ELB
-       );
+            // if you're using ELB, otherwise use another Request::HEADER-* constant
+            trusted_headers: [!php/const Symfony\\Component\\HttpFoundation\\Request::HEADER_X_FORWARDED_AWS_ELB, '!x-forwarded-host', '!x-forwarded-prefix']
 
 That's it! It's critical that you prevent traffic from all non-trusted sources.
 If you allow outside traffic, they could "spoof" their true IP address and
@@ -100,6 +148,12 @@ other information.
         # .env
         TRUSTED_PROXIES=127.0.0.1,REMOTE_ADDR
 
+    .. config-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            # ...
+            trusted_proxies: '%env(TRUSTED_PROXIES)%'
 
 If you are also using a reverse proxy on top of your load balancer (e.g.
 `CloudFront`_), calling ``$request->server->get('REMOTE_ADDR')`` won't be
@@ -111,11 +165,13 @@ trusted proxies.
 Custom Headers When Using a Reverse Proxy
 -----------------------------------------
 
-Some reverse proxies (like `CloudFront`_ with ``CloudFront-Forwarded-Proto``) may force you to use a custom header.
-For instance you have ``Custom-Forwarded-Proto`` instead of ``X-Forwarded-Proto``.
+Some reverse proxies (like `CloudFront`_ with ``CloudFront-Forwarded-Proto``)
+may force you to use a custom header. For instance you have
+``Custom-Forwarded-Proto`` instead of ``X-Forwarded-Proto``.
 
-In this case, you'll need to set the header ``X-Forwarded-Proto`` with the value of
-``Custom-Forwarded-Proto`` early enough in your application, i.e. before handling the request::
+In this case, you'll need to set the header ``X-Forwarded-Proto`` with the value
+of ``Custom-Forwarded-Proto`` early enough in your application, i.e. before
+handling the request::
 
     // public/index.php
 
diff --git a/form/form_collections.rst b/form/form_collections.rst
@@ -245,7 +245,7 @@ the following ``data-prototype`` attribute to the existing ``<ul>`` in your temp
 
     <ul class="tags" data-prototype="{{ form_widget(form.tags.vars.prototype)|e('html_attr') }}"></ul>
 
-Now add a button just next to the ``<ul>`` to dynamically add a new tag
+Now add a button just next to the ``<ul>`` to dynamically add a new tag:
 
 .. code-block:: html+twig
 
@@ -280,13 +280,13 @@ On the rendered page, the result will look something like this:
     the ``data-prototype`` attribute is automatically added to the containing ``div``,
     and you need to adjust the following JavaScript accordingly.
 
-The goal of this section will be to use JavaScript to read this attribute
-and dynamically add new tag forms when the user clicks the "Add a tag" button.
-This example uses jQuery and assumes you have it included somewhere on your page.
+Now add some JavaScript to read this attribute and dynamically add new tag forms
+when the user clicks the "Add a tag" link. This example uses `jQuery`_ and
+assumes you have it included somewhere on your page (e.g. using Symfony's
+:doc:`Webpack Encore </frontend>`).
 
-Add a ``script`` tag somewhere on your page so you can start writing some
-JavaScript. In this script, bind to the "click" event of the "Add a tag"
-button so you can add a new tag form (``addFormToCollection()`` will be show next):
+Add a ``<script>`` tag somewhere on your page to include the required
+functionality with JavaScript:
 
 .. code-block:: javascript
 
@@ -304,14 +304,11 @@ button so you can add a new tag form (``addFormToCollection()`` will be show nex
         })
     });
 
-The ``addTagForm()`` function's job will be to use the ``data-prototype`` attribute
-to dynamically add a new form when this link is clicked. The ``data-prototype``
-HTML contains the tag ``text`` input element with a name of ``task[tags][__name__][name]``
-and id of ``task_tags___name___name``. The ``__name__`` is a little "placeholder",
-which you'll replace with a unique, incrementing number (e.g. ``task[tags][3][name]``).
-
-The actual code needed to make this all work can vary quite a bit, but here's
-one example:
+The ``addFormToCollection()`` function's job will be to use the ``data-prototype``
+attribute to dynamically add a new form when this link is clicked. The ``data-prototype``
+HTML contains the tag's ``text`` input element with a name of ``task[tags][__name__][name]``
+and id of ``task_tags___name___name``. The ``__name__`` is a placeholder, which
+you'll replace with a unique, incrementing number (e.g. ``task[tags][3][name]``):
 
 .. code-block:: javascript
 
@@ -344,11 +341,6 @@ one example:
         $collectionHolder.append($newFormLi)
     }
 
-.. note::
-
-    It is better to separate your JavaScript in real JavaScript files than
-    to write it inside the HTML as is done here.
-
 Now, each time a user clicks the ``Add a tag`` link, a new sub form will
 appear on the page. When the form is submitted, any new tag forms will be converted
 into new ``Tag`` objects and added to the ``tags`` property of the ``Task`` object.
@@ -572,7 +564,7 @@ First, add a "delete this tag" link to each tag form:
         // ... the rest of the block from above
     });
 
-    function addTagForm() {
+    function addFormToCollection() {
         // ...
 
         // add a delete link to the new form
@@ -684,6 +676,7 @@ the relationship between the removed ``Tag`` and ``Task`` object.
     the `symfony-collection`_ package based on jQuery for the rest of browsers.
 
 .. _`Owning Side and Inverse Side`: https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/unitofwork-associations.html
+.. _`jQuery`: http://jquery.com/
 .. _`JSFiddle`: http://jsfiddle.net/847Kf/4/
 .. _`@a2lix/symfony-collection`: https://github.com/a2lix/symfony-collection
 .. _`symfony-collection`: https://github.com/ninsuo/symfony-collection
diff --git a/notifier.rst b/notifier.rst
@@ -145,6 +145,7 @@ integration with these chat services:
 Service     Package                           DSN
 ==========  ================================  ===========================================================================
 Discord     ``symfony/discord-notifier``      ``discord://TOKEN@default?webhook_id=ID``
+Firebase    ``symfony/firebase-notifier``     ``firebase://USERNAME:PASSWORD@default``
 GoogleChat  ``symfony/google-chat-notifier``  ``googlechat://ACCESS_KEY:ACCESS_TOKEN@default/SPACE?threadKey=THREAD_KEY``
 LinkedIn    ``symfony/linked-in-notifier``    ``linkedin://TOKEN:USER_ID@default``
 Mattermost  ``symfony/mattermost-notifier``   ``mattermost://ACCESS_TOKEN@HOST/PATH?channel=CHANNEL``
@@ -156,7 +157,9 @@ Zulip       ``symfony/zulip-notifier``        ``zulip://EMAIL:TOKEN@HOST?channel
 
 .. versionadded:: 5.1
 
-    The Mattermost and RocketChat integrations were introduced in Symfony 5.1.
+    The Firebase, Mattermost and RocketChat integrations were introduced in Symfony
+    5.1. The Slack DSN changed in Symfony 5.1 to use Slack Incoming
+    Webhooks instead of legacy tokens.
 
 .. versionadded:: 5.2
 
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -284,6 +284,7 @@ Configuration
   * `logging`_
   * :ref:`paths <reference-translator-paths>`
 
+* `trusted_headers`_
 * `trusted_hosts`_
 * `trusted_proxies`_
 * `validation`_
@@ -380,12 +381,32 @@ named ``kernel.http_method_override``.
         $request = Request::createFromGlobals();
         // ...
 
+.. _reference-framework-trusted-headers:
+
+trusted_headers
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 5.2
+
+    The ``trusted_headers`` option was introduced in Symfony 5.2.
+
+The ``trusted_headers`` option is needed to configure which client information
+should be trusted (e.g. their host) when running Symfony behind a load balancer
+or a reverse proxy. See :doc:`/deployment/proxies`.
+
 .. _reference-framework-trusted-proxies:
 
 trusted_proxies
 ~~~~~~~~~~~~~~~
 
-The ``trusted_proxies`` option was removed in Symfony 3.3. See :doc:`/deployment/proxies`.
+.. versionadded:: 5.2
+
+    The ``trusted_headers`` option was reintroduced in Symfony 5.2 (it had been
+    removed in Symfony 3.3).
+
+The ``trusted_proxies`` option is needed to get precise information about the
+client (e.g. their IP address) when running Symfony behind a load balancer or a
+reverse proxy. See :doc:`/deployment/proxies`.
 
 ide
 ~~~
