Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit ad85015

Browse filesBrowse files
xabbuhxabbuh
committed
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
2 parents c8a76e3 + 9f370c6 commit ad85015
Copy full SHA for ad85015

File tree

8 files changed

+112
-67
lines changed
Filter options

8 files changed

+112
-67
lines changed

‎book/installation.rst

Copy file name to clipboardExpand all lines: book/installation.rst
+6Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,12 @@ If there are any issues, correct them now before moving on.
229229
configuration (e.g. commonly httpd.conf or apache2.conf for Apache) and setting
230230
its user to be the same as your CLI user (e.g. for Apache, update the ``User``
231231
and ``Group`` values).
232+
233+
.. caution::
234+
235+
If used in a production environment, be sure this user only has limited privileges
236+
(no access to private data or servers, launch of unsafe binaries, etc.)
237+
as a compromised server would give to the hacker those privileges.
232238

233239
**2. Using ACL on a system that supports chmod +a (MacOS X)**
234240

‎book/templating.rst

Copy file name to clipboardExpand all lines: book/templating.rst
+16-43Lines changed: 16 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1074,46 +1074,12 @@ assets won't be loaded from cache after being deployed. For example, ``/images/l
10741074
look like ``/images/logo.png?v2``. For more information, see the :ref:`reference-framework-assets-version`
10751075
configuration option.
10761076

1077-
.. _`book-templating-version-by-asset`:
1077+
If you need absolute URLs for assets, use the ``absolute_url()`` Twig function
1078+
as follows:
10781079

1079-
If you need to set a version for a specific asset, you can set the ``version`` argument
1080-
if you are using Twig (or the fourth argument if you are using PHP) to the desired version:
1080+
.. code-block:: html+jinja
10811081

1082-
.. configuration-block::
1083-
1084-
.. code-block:: html+jinja
1085-
1086-
<img src="{{ asset('images/logo.png', version='3.0') }}" alt="Symfony!" />
1087-
1088-
.. code-block:: html+php
1089-
1090-
<img src="<?php echo $view['assets']->getUrl(
1091-
'images/logo.png',
1092-
null,
1093-
false,
1094-
'3.0'
1095-
) ?>" alt="Symfony!" />
1096-
1097-
If you don't give a version or pass ``null``, the default package version
1098-
(from :ref:`reference-framework-assets-version`) will be used. If you pass ``false``,
1099-
versioned URL will be deactivated for this asset.
1100-
1101-
If you need absolute URLs for assets, you can use the ``absolute_url`` function
1102-
if you are using Twig (or the third argument if you are using PHP) to ``true``:
1103-
1104-
.. configuration-block::
1105-
1106-
.. code-block:: html+jinja
1107-
1108-
<img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />
1109-
1110-
.. code-block:: html+php
1111-
1112-
<img src="<?php echo $view['assets']->getUrl(
1113-
'images/logo.png',
1114-
null,
1115-
true
1116-
) ?>" alt="Symfony!" />
1082+
<img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />
11171083

11181084
.. index::
11191085
single: Templating; Including stylesheets and JavaScripts
@@ -1239,15 +1205,22 @@ instance which will give you access to some application specific variables
12391205
automatically:
12401206

12411207
``app.security`` (deprecated as of 2.6)
1242-
The security context.
1208+
The :class:`Symfony\\Component\\Security\\Core\\SecurityContext` object or
1209+
``null`` if there is none.
12431210
``app.user``
1244-
The current user object.
1211+
The representation of the current user or ``null`` if there is none. The
1212+
value stored in this variable can be a :class:`Symfony\\Component\\Security\\Core\\User\\UserInterface`
1213+
object, any other object which implements a ``__toString()`` method or even
1214+
a regular string.
12451215
``app.request``
1246-
The request object.
1216+
The :class:`Symfony\\Component\\HttpFoundation\\Request` object that represents
1217+
the current request (depending on your application, this can be a sub-request
1218+
or a regular request, as explained later).
12471219
``app.session``
1248-
The session object.
1220+
The :class:`Symfony\\Component\\HttpFoundation\\Session\\Session` object that
1221+
represents the current user's session or ``null`` if there is none.
12491222
``app.environment``
1250-
The current environment (dev, prod, etc).
1223+
The name of the current environment (``dev``, ``prod``, etc).
12511224
``app.debug``
12521225
True if in debug mode. False otherwise.
12531226

‎components/dependency_injection/parentservices.rst

Copy file name to clipboardExpand all lines: components/dependency_injection/parentservices.rst
+5-5Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ The service config for these classes would look something like this:
6767
- [setEmailFormatter, ['@my_email_formatter']]
6868
6969
greeting_card_manager:
70-
class: 'GreetingCardManager'
70+
class: GreetingCardManager
7171
calls:
7272
- [setMailer, ['@my_mailer']]
7373
- [setEmailFormatter, ['@my_email_formatter']]
@@ -196,11 +196,11 @@ a parent for a service.
196196
- [setEmailFormatter, ['@my_email_formatter']]
197197
198198
newsletter_manager:
199-
class: "NewsletterManager"
199+
class: NewsletterManager
200200
parent: mail_manager
201201
202202
greeting_card_manager:
203-
class: "GreetingCardManager"
203+
class: GreetingCardManager
204204
parent: mail_manager
205205
206206
.. code-block:: xml
@@ -324,13 +324,13 @@ to the ``NewsletterManager`` class, the config would look like this:
324324
- [setEmailFormatter, ['@my_email_formatter']]
325325
326326
newsletter_manager:
327-
class: 'NewsletterManager'
327+
class: NewsletterManager
328328
parent: mail_manager
329329
calls:
330330
- [setMailer, ['@my_alternative_mailer']]
331331
332332
greeting_card_manager:
333-
class: 'GreetingCardManager'
333+
class: GreetingCardManager
334334
parent: mail_manager
335335
336336
.. code-block:: xml

‎components/http_foundation/trusting_proxies.rst

Copy file name to clipboardExpand all lines: components/http_foundation/trusting_proxies.rst
+15-6Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ Trusting Proxies
1111

1212
If you find yourself behind some sort of proxy - like a load balancer - then
1313
certain header information may be sent to you using special ``X-Forwarded-*``
14-
headers. For example, the ``Host`` HTTP header is usually used to return
15-
the requested host. But when you're behind a proxy, the true host may be
16-
stored in a ``X-Forwarded-Host`` header.
14+
headers or the ``Forwarded`` header. For example, the ``Host`` HTTP header is
15+
usually used to return the requested host. But when you're behind a proxy,
16+
the actual host may be stored in an ``X-Forwarded-Host`` header.
1717

1818
Since HTTP headers can be spoofed, Symfony does *not* trust these proxy
1919
headers by default. If you are behind a proxy, you should manually whitelist
@@ -30,11 +30,19 @@ your proxy.
3030
// only trust proxy headers coming from this IP addresses
3131
Request::setTrustedProxies(array('192.0.0.1', '10.0.0.0/8'));
3232
33+
You should also make sure that your proxy filters unauthorized use of these
34+
headers, e.g. if a proxy natively uses the ``X-Forwarded-For`` header, it
35+
should not allow clients to send ``Forwarded`` headers to Symfony.
36+
37+
If your proxy does not filter headers appropriately, you need to configure
38+
Symfony not to trust the headers your proxy does not filter (see below).
39+
3340
Configuring Header Names
3441
------------------------
3542

3643
By default, the following proxy headers are trusted:
3744

45+
* ``Forwarded`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
3846
* ``X-Forwarded-For`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
3947
* ``X-Forwarded-Host`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getHost`;
4048
* ``X-Forwarded-Port`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getPort`;
@@ -43,6 +51,7 @@ By default, the following proxy headers are trusted:
4351
If your reverse proxy uses a different header name for any of these, you
4452
can configure that header name via :method:`Symfony\\Component\\HttpFoundation\\Request::setTrustedHeaderName`::
4553

54+
Request::setTrustedHeaderName(Request::HEADER_FORWARDED, 'X-Forwarded');
4655
Request::setTrustedHeaderName(Request::HEADER_CLIENT_IP, 'X-Proxy-For');
4756
Request::setTrustedHeaderName(Request::HEADER_CLIENT_HOST, 'X-Proxy-Host');
4857
Request::setTrustedHeaderName(Request::HEADER_CLIENT_PORT, 'X-Proxy-Port');
@@ -51,9 +60,9 @@ can configure that header name via :method:`Symfony\\Component\\HttpFoundation\\
5160
Not Trusting certain Headers
5261
----------------------------
5362

54-
By default, if you whitelist your proxy's IP address, then all four headers
63+
By default, if you whitelist your proxy's IP address, then all five headers
5564
listed above are trusted. If you need to trust some of these headers but
5665
not others, you can do that as well::
5766

58-
// disables trusting the ``X-Forwarded-Proto`` header, the default header is used
59-
Request::setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, '');
67+
// disables trusting the ``Forwarded`` header
68+
Request::setTrustedHeaderName(Request::HEADER_FORWARDED, null);

‎cookbook/cache/varnish.rst

Copy file name to clipboardExpand all lines: cookbook/cache/varnish.rst
+15Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,21 @@ Remember to configure :ref:`framework.trusted_proxies <reference-framework-trust
2424
in the Symfony configuration so that Varnish is seen as a trusted proxy and the
2525
:ref:`X-Forwarded <varnish-x-forwarded-headers>` headers are used.
2626

27+
Varnish, in its default configuration, sends the ``X-Forwarded-For`` header but
28+
does not filter out the ``Forwarded`` header. If you have access to the Varnish
29+
configuration file, you can configure Varnish to remove the ``Forwarded``
30+
header:
31+
32+
.. code-block:: varnish4
33+
34+
sub vcl_recv {
35+
remove req.http.Forwarded;
36+
}
37+
38+
If you do not have access to your Varnish configuration, you can instead
39+
configure Symfony to distrust the ``Forwarded`` header as detailed in
40+
:ref:`the cookbook <cookbook-request-untrust-header>`.
41+
2742
.. _varnish-x-forwarded-headers:
2843

2944
Routing and X-FORWARDED Headers

‎cookbook/request/load_balancer_reverse_proxy.rst

Copy file name to clipboardExpand all lines: cookbook/request/load_balancer_reverse_proxy.rst
+28-1Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ via HTTPS, the client's port and the hostname being requested.
2323
Solution: trusted_proxies
2424
-------------------------
2525

26-
This is no problem, but you *do* need to tell Symfony that this is happening
26+
This is no problem, but you *do* need to tell Symfony what is happening
2727
and which reverse proxy IP addresses will be doing this type of thing:
2828

2929
.. configuration-block::
@@ -62,6 +62,10 @@ the IP address ``192.0.0.1`` or matches the range of IP addresses that use
6262
the CIDR notation ``10.0.0.0/8``. For more details, see the
6363
:ref:`framework.trusted_proxies <reference-framework-trusted-proxies>` option.
6464

65+
You are also saying that you trust that the proxy does not send conflicting
66+
headers, e.g. sending both ``X-Forwarded-For`` and ``Forwarded`` in the same
67+
request.
68+
6569
That's it! Symfony will now look for the correct headers to get information
6670
like the client's IP address, host, port and whether the request is
6771
using HTTPS.
@@ -95,6 +99,29 @@ That's it! It's critical that you prevent traffic from all non-trusted sources.
9599
If you allow outside traffic, they could "spoof" their true IP address and
96100
other information.
97101

102+
.. _cookbook-request-untrust-header:
103+
104+
My Reverse Proxy Sends X-Forwarded-For but Does not Filter the Forwarded Header
105+
-------------------------------------------------------------------------------
106+
107+
Many popular proxy implementations do not yet support the ``Forwarded`` header
108+
and do not filter it by default. Ideally, you would configure this in your
109+
proxy. If this is not possible, you can tell Symfony to distrust the ``Forwarded``
110+
header, while still trusting your proxy's ``X-Forwarded-For`` header.
111+
112+
This is done inside of your front controller::
113+
114+
// web/app.php
115+
116+
// ...
117+
Request::setTrustedHeaderName(Request::HEADER_FORWARDED, null);
118+
119+
$response = $kernel->handle($request);
120+
// ...
121+
122+
Configuring the proxy server trust is very important, as not doing so will
123+
allow malicious users to "spoof" their IP address.
124+
98125
My Reverse Proxy Uses Non-Standard (not X-Forwarded) Headers
99126
------------------------------------------------------------
100127

‎reference/configuration/framework.rst

Copy file name to clipboardExpand all lines: reference/configuration/framework.rst
-4Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1082,10 +1082,6 @@ Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use
10821082
this feature, you **must** manually increment the ``version`` value
10831083
before each deployment so that the query parameters change.
10841084

1085-
It's also possible to set the version value on an asset-by-asset basis (instead
1086-
of using the global version - e.g. ``v2`` - set here). See
1087-
:ref:`Versioning by Asset <book-templating-version-by-asset>` for details.
1088-
10891085
You can also control how the query string works via the `version_format`_
10901086
option.
10911087

‎reference/twig_reference.rst

Copy file name to clipboardExpand all lines: reference/twig_reference.rst
+27-8Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,8 @@ asset
111111

112112
Returns a public path to ``path``, which takes into account the base path
113113
set for the package and the URL path. More information in
114-
:ref:`book-templating-assets`. For asset versioning, see :ref:`reference-framework-assets-version`.
114+
:ref:`book-templating-assets`. For asset versioning, see
115+
:ref:`reference-framework-assets-version`.
115116

116117
assets_version
117118
~~~~~~~~~~~~~~
@@ -362,34 +363,52 @@ information in :ref:`book-templating-pages`.
362363
absolute_url
363364
~~~~~~~~~~~~
364365

366+
.. versionadded:: 2.7
367+
The ``absolute_url()`` function was introduced in Symfony 2.7.
368+
365369
.. code-block:: jinja
366370
367371
{{ absolute_url(path) }}
368372
369373
``path``
370374
**type**: ``string``
371375

372-
Returns the absolute URL for the given absolute path. This is useful to convert
373-
an existing path:
376+
Returns the absolute URL from the passed relative path. For example, assume
377+
you're on the following page in your app:
378+
``http://example.com/products/hover-board``.
374379

375380
.. code-block:: jinja
376381
377-
{{ absolute_url(asset(path)) }}
382+
{{ absolute_url('/human.txt') }}
383+
{# http://example.com/human.txt #}
384+
385+
{{ absolute_url('products_icon.png') }}
386+
{# http://example.com/products/products_icon.png #}
378387
379388
relative_path
380389
~~~~~~~~~~~~~
381390

391+
.. versionadded:: 2.7
392+
The ``relative_path()`` function was introduced in Symfony 2.7.
393+
382394
.. code-block:: jinja
383395
384396
{{ relative_path(path) }}
385397
386398
``path``
387399
**type**: ``string``
388400

389-
Returns a relative path for the given absolute path (based on the current
390-
request path). For instance, if the current path is
391-
``/article/news/welcome.html``, the relative path for ``/article/image.png`` is
392-
``../images.png``.
401+
Returns the relative path from the passed absolute URL. For example, assume
402+
you're on the following page in your app:
403+
``http://example.com/products/hover-board``.
404+
405+
.. code-block:: jinja
406+
407+
{{ relative_path('http://example.com/human.txt') }}
408+
{# ../human.txt #}
409+
410+
{{ relative_path('http://example.com/products/products_icon.png') }}
411+
{# products_icon.png #}
393412
394413
expression
395414
~~~~~~~~~~

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.