Merge branch '2.7' into 2.8

* 2.7:
  [#6526] some minor tweaks
  Documented how to configure Symfony correctly with regards to the Forwarded header
  Improved the description of the Twig global variables
  Add a warning about using same user for cli and web server
  Correctly document new twig functions
  Updated Twig template to take into account asset() function changes
  [DependencyInjection] Unquote services FQCN in parent-services examples

Author: xabbuh

book/installation.rst

@@ -229,6 +229,12 @@ If there are any issues, correct them now before moving on.
     configuration (e.g. commonly httpd.conf or apache2.conf for Apache) and setting
     its user to be the same as your CLI user (e.g. for Apache, update the ``User``
     and ``Group`` values).
+    
+    .. caution::
+    
+        If used in a production environment, be sure this user only has limited privileges
+        (no access to private data or servers, launch of unsafe binaries, etc.)
+        as a compromised server would give to the hacker those privileges.
 
     **2. Using ACL on a system that supports chmod +a (MacOS X)**
 

book/templating.rst

@@ -1074,46 +1074,12 @@ assets won't be loaded from cache after being deployed. For example, ``/images/l
 look like ``/images/logo.png?v2``. For more information, see the :ref:`reference-framework-assets-version`
 configuration option.
 
-.. _`book-templating-version-by-asset`:
+If you need absolute URLs for assets, use the ``absolute_url()`` Twig function
+as follows:
 
-If you need to set a version for a specific asset, you can set the ``version`` argument
-if you are using Twig (or the fourth argument if you are using PHP) to the desired version:
+.. code-block:: html+jinja
 
-.. configuration-block::
-
-    .. code-block:: html+jinja
-
-        <img src="{{ asset('images/logo.png', version='3.0') }}" alt="Symfony!" />
-
-    .. code-block:: html+php
-
-        <img src="<?php echo $view['assets']->getUrl(
-            'images/logo.png',
-            null,
-            false,
-            '3.0'
-        ) ?>" alt="Symfony!" />
-
-If you don't give a version or pass ``null``, the default package version
-(from :ref:`reference-framework-assets-version`) will be used. If you pass ``false``,
-versioned URL will be deactivated for this asset.
-
-If you need absolute URLs for assets, you can use the ``absolute_url`` function
-if you are using Twig (or the third argument if you are using PHP) to ``true``:
-
-.. configuration-block::
-
-    .. code-block:: html+jinja
-
-        <img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />
-
-    .. code-block:: html+php
-
-        <img src="<?php echo $view['assets']->getUrl(
-            'images/logo.png',
-            null,
-            true
-        ) ?>" alt="Symfony!" />
+    <img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />
 
 .. index::
    single: Templating; Including stylesheets and JavaScripts
@@ -1239,15 +1205,22 @@ instance which will give you access to some application specific variables
 automatically:
 
 ``app.security`` (deprecated as of 2.6)
-    The security context.
+    The :class:`Symfony\\Component\\Security\\Core\\SecurityContext` object or
+    ``null`` if there is none.
 ``app.user``
-    The current user object.
+    The representation of the current user or ``null`` if there is none. The
+    value stored in this variable can be a :class:`Symfony\\Component\\Security\\Core\\User\\UserInterface`
+    object, any other object which implements a ``__toString()`` method or even
+    a regular string.
 ``app.request``
-    The request object.
+    The :class:`Symfony\\Component\\HttpFoundation\\Request` object that represents
+    the current request (depending on your application, this can be a sub-request
+    or a regular request, as explained later).
 ``app.session``
-    The session object.
+    The :class:`Symfony\\Component\\HttpFoundation\\Session\\Session` object that
+    represents the current user's session or ``null`` if there is none.
 ``app.environment``
-    The current environment (dev, prod, etc).
+    The name of the current environment (``dev``, ``prod``, etc).
 ``app.debug``
     True if in debug mode. False otherwise.
 

components/dependency_injection/parentservices.rst

@@ -67,7 +67,7 @@ The service config for these classes would look something like this:
                     - [setEmailFormatter, ['@my_email_formatter']]
 
             greeting_card_manager:
-                class: 'GreetingCardManager'
+                class: GreetingCardManager
                 calls:
                     - [setMailer, ['@my_mailer']]
                     - [setEmailFormatter, ['@my_email_formatter']]
@@ -196,11 +196,11 @@ a parent for a service.
                     - [setEmailFormatter, ['@my_email_formatter']]
 
             newsletter_manager:
-                class:  "NewsletterManager"
+                class:  NewsletterManager
                 parent: mail_manager
 
             greeting_card_manager:
-                class:  "GreetingCardManager"
+                class:  GreetingCardManager
                 parent: mail_manager
 
     .. code-block:: xml
@@ -324,13 +324,13 @@ to the ``NewsletterManager`` class, the config would look like this:
                     - [setEmailFormatter, ['@my_email_formatter']]
 
             newsletter_manager:
-                class:  'NewsletterManager'
+                class:  NewsletterManager
                 parent: mail_manager
                 calls:
                     - [setMailer, ['@my_alternative_mailer']]
 
             greeting_card_manager:
-                class:  'GreetingCardManager'
+                class:  GreetingCardManager
                 parent: mail_manager
 
     .. code-block:: xml

components/http_foundation/trusting_proxies.rst

@@ -11,9 +11,9 @@ Trusting Proxies
 
 If you find yourself behind some sort of proxy - like a load balancer - then
 certain header information may be sent to you using special ``X-Forwarded-*``
-headers. For example, the ``Host`` HTTP header is usually used to return
-the requested host. But when you're behind a proxy, the true host may be
-stored in a ``X-Forwarded-Host`` header.
+headers or the ``Forwarded`` header. For example, the ``Host`` HTTP header is
+usually used to return the requested host. But when you're behind a proxy,
+the actual host may be stored in an ``X-Forwarded-Host`` header.
 
 Since HTTP headers can be spoofed, Symfony does *not* trust these proxy
 headers by default. If you are behind a proxy, you should manually whitelist
@@ -30,11 +30,19 @@ your proxy.
     // only trust proxy headers coming from this IP addresses
     Request::setTrustedProxies(array('192.0.0.1', '10.0.0.0/8'));
 
+You should also make sure that your proxy filters unauthorized use of these
+headers, e.g. if a proxy natively uses the ``X-Forwarded-For`` header, it
+should not allow clients to send ``Forwarded`` headers to Symfony.
+
+If your proxy does not filter headers appropriately, you need to configure
+Symfony not to trust the headers your proxy does not filter (see below).
+
 Configuring Header Names
 ------------------------
 
 By default, the following proxy headers are trusted:
 
+* ``Forwarded`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
 * ``X-Forwarded-For`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
 * ``X-Forwarded-Host`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getHost`;
 * ``X-Forwarded-Port`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getPort`;
@@ -43,6 +51,7 @@ By default, the following proxy headers are trusted:
 If your reverse proxy uses a different header name for any of these, you
 can configure that header name via :method:`Symfony\\Component\\HttpFoundation\\Request::setTrustedHeaderName`::
 
+    Request::setTrustedHeaderName(Request::HEADER_FORWARDED, 'X-Forwarded');
     Request::setTrustedHeaderName(Request::HEADER_CLIENT_IP, 'X-Proxy-For');
     Request::setTrustedHeaderName(Request::HEADER_CLIENT_HOST, 'X-Proxy-Host');
     Request::setTrustedHeaderName(Request::HEADER_CLIENT_PORT, 'X-Proxy-Port');
@@ -51,9 +60,9 @@ can configure that header name via :method:`Symfony\\Component\\HttpFoundation\\
 Not Trusting certain Headers
 ----------------------------
 
-By default, if you whitelist your proxy's IP address, then all four headers
+By default, if you whitelist your proxy's IP address, then all five headers
 listed above are trusted. If you need to trust some of these headers but
 not others, you can do that as well::
 
-    // disables trusting the ``X-Forwarded-Proto`` header, the default header is used
-    Request::setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, '');
+    // disables trusting the ``Forwarded`` header
+    Request::setTrustedHeaderName(Request::HEADER_FORWARDED, null);

cookbook/cache/varnish.rst

@@ -24,6 +24,21 @@ Remember to configure :ref:`framework.trusted_proxies <reference-framework-trust
 in the Symfony configuration so that Varnish is seen as a trusted proxy and the
 :ref:`X-Forwarded <varnish-x-forwarded-headers>` headers are used.
 
+Varnish, in its default configuration, sends the ``X-Forwarded-For`` header but
+does not filter out the ``Forwarded`` header. If you have access to the Varnish
+configuration file, you can configure Varnish to remove the ``Forwarded``
+header:
+
+.. code-block:: varnish4
+
+    sub vcl_recv {
+        remove req.http.Forwarded;
+    }
+
+If you do not have access to your Varnish configuration, you can instead
+configure Symfony to distrust the ``Forwarded`` header as detailed in
+:ref:`the cookbook <cookbook-request-untrust-header>`.
+
 .. _varnish-x-forwarded-headers:
 
 Routing and X-FORWARDED Headers

cookbook/request/load_balancer_reverse_proxy.rst

@@ -23,7 +23,7 @@ via HTTPS, the client's port and the hostname being requested.
 Solution: trusted_proxies
 -------------------------
 
-This is no problem, but you *do* need to tell Symfony that this is happening
+This is no problem, but you *do* need to tell Symfony what is happening
 and which reverse proxy IP addresses will be doing this type of thing:
 
 .. configuration-block::
@@ -62,6 +62,10 @@ the IP address ``192.0.0.1`` or matches the range of IP addresses that use
 the CIDR notation ``10.0.0.0/8``. For more details, see the
 :ref:`framework.trusted_proxies <reference-framework-trusted-proxies>` option.
 
+You are also saying that you trust that the proxy does not send conflicting
+headers, e.g. sending both ``X-Forwarded-For`` and ``Forwarded`` in the same
+request.
+
 That's it! Symfony will now look for the correct headers to get information
 like the client's IP address, host, port and whether the request is
 using HTTPS.
@@ -95,6 +99,29 @@ 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
 other information.
 
+.. _cookbook-request-untrust-header:
+
+My Reverse Proxy Sends X-Forwarded-For but Does not Filter the Forwarded Header
+-------------------------------------------------------------------------------
+
+Many popular proxy implementations do not yet support the ``Forwarded`` header
+and do not filter it by default. Ideally, you would configure this in your
+proxy. If this is not possible, you can tell Symfony to distrust the ``Forwarded``
+header, while still trusting your proxy's ``X-Forwarded-For`` header.
+
+This is done inside of your front controller::
+
+       // web/app.php
+
+       // ...
+       Request::setTrustedHeaderName(Request::HEADER_FORWARDED, null);
+
+       $response = $kernel->handle($request);
+       // ...
+
+Configuring the proxy server trust is very important, as not doing so will
+allow malicious users to "spoof" their IP address.
+
 My Reverse Proxy Uses Non-Standard (not X-Forwarded) Headers
 ------------------------------------------------------------
 

reference/configuration/framework.rst

@@ -1082,10 +1082,6 @@ Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use
 this feature, you **must** manually increment the ``version`` value
 before each deployment so that the query parameters change.
 
-It's also possible to set the version value on an asset-by-asset basis (instead
-of using the global version - e.g. ``v2`` - set here). See
-:ref:`Versioning by Asset <book-templating-version-by-asset>` for details.
-
 You can also control how the query string works via the `version_format`_
 option.
 

reference/twig_reference.rst

@@ -111,7 +111,8 @@ asset
 
 Returns a public path to ``path``, which takes into account the base path
 set for the package and the URL path. More information in
-:ref:`book-templating-assets`. For asset versioning, see :ref:`reference-framework-assets-version`.
+:ref:`book-templating-assets`. For asset versioning, see
+:ref:`reference-framework-assets-version`.
 
 assets_version
 ~~~~~~~~~~~~~~
@@ -362,34 +363,52 @@ information in :ref:`book-templating-pages`.
 absolute_url
 ~~~~~~~~~~~~
 
+.. versionadded:: 2.7
+    The ``absolute_url()`` function was introduced in Symfony 2.7.
+
 .. code-block:: jinja
 
     {{ absolute_url(path) }}
 
 ``path``
     **type**: ``string``
 
-Returns the absolute URL for the given absolute path. This is useful to convert
-an existing path:
+Returns the absolute URL from the passed relative path. For example, assume
+you're on the following page in your app:
+``http://example.com/products/hover-board``.
 
 .. code-block:: jinja
 
-    {{ absolute_url(asset(path)) }}
+    {{ absolute_url('/human.txt') }}
+    {# http://example.com/human.txt #}
+
+    {{ absolute_url('products_icon.png') }}
+    {# http://example.com/products/products_icon.png #}
 
 relative_path
 ~~~~~~~~~~~~~
 
+.. versionadded:: 2.7
+    The ``relative_path()`` function was introduced in Symfony 2.7.
+
 .. code-block:: jinja
 
     {{ relative_path(path) }}
 
 ``path``
     **type**: ``string``
 
-Returns a relative path for the given absolute path (based on the current
-request path). For instance, if the current path is
-``/article/news/welcome.html``, the relative path for ``/article/image.png`` is
-``../images.png``.
+Returns the relative path from the passed absolute URL. For example, assume
+you're on the following page in your app:
+``http://example.com/products/hover-board``.
+
+.. code-block:: jinja
+
+    {{ relative_path('http://example.com/human.txt') }}
+    {# ../human.txt #}
+
+    {{ relative_path('http://example.com/products/products_icon.png') }}
+    {# products_icon.png #}
 
 expression
 ~~~~~~~~~~