8000 Merge branch '2.8' into 3.0 · symfony/symfony-docs@3891d6b · GitHub
[go: up one dir, main page]
Skip to content

Commit 3891d6b

Browse files
xabbuhxabbuh
committed
Merge branch '2.8' into 3.0
* 2.8: [#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 [DomCrawler] Removed references to CssSelector [DependencyInjection] Unquote services FQCN in parent-services examples [DependencyInjection] Unquote services FQCN in autowiring examples
2 parents a59f2d5 + ad85015 commit 3891d6b

File tree

10 files changed

+113
-78
lines changed

10 files changed

+113
-78
lines changed

‎book/installation.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -236,6 +236,12 @@ If there are any issues, correct them now before moving on.
236236
configuration (e.g. commonly httpd.conf or apache2.conf for Apache) and setting
237237
its user to be the same as your CLI user (e.g. for Apache, update the ``User``
238238
and ``Group`` values).
239+
240+
.. caution::
241+
242+
If used in a production environment, be sure this user only has limited privileges
243+
(no access to private data or servers, launch of unsafe binaries, etc.)
244+
as a compromised server would give to the hacker those privileges.
239245

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

‎book/templating.rst

Lines changed: 14 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1057,46 +1057,12 @@ assets won't be loaded from cache after being deployed. For example, ``/images/l
10571057
look like ``/images/logo.png?v2``. For more information, see the :ref:`reference-framework-assets-version`
10581058
configuration option.
10591059

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

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

1065-
.. configuration-block::
1066-
1067-
.. code-block:: html+jinja
1068-
1069-
<img src="{{ asset('images/logo.png', version='3.0') }}" alt="Symfony!" />
1070-
1071-
.. code-block:: html+php
1072-
1073-
<img src="<?php echo $view['assets']->getUrl(
1074-
'images/logo.png',
1075-
null,
1076-
false,
1077-
'3.0'
1078-
) ?>" alt="Symfony!" />
1079-
1080-
If you don't give a version or pass ``null``, the default package version
1081-
(from :ref:`reference-framework-assets-version`) will be used. If you pass ``false``,
1082-
versioned URL will be deactivated for this asset.
1083-
1084-
If you need absolute URLs for assets, you can use the ``absolute_url`` function
1085-
if you are using Twig (or the third argument if you are using PHP) to ``true``:
1086-
1087-
.. configuration-block::
1088-
1089-
.. code-block:: html+jinja
1090-
1091-
<img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />
1092-
1093-
.. code-block:: html+php
1094-
1095-
<img src="<?php echo $view['assets']->getUrl(
1096-
'images/logo.png',
1097-
null,
1098-
true
1099-
) ?>" alt="Symfony!" />
1065+
<img src="{{ absolute_url(asset('images/logo.png')) }}" alt="Symfony!" />
11001066

11011067
.. index::
11021068
single: Templating; Including stylesheets and JavaScripts
@@ -1222,13 +1188,19 @@ instance which will give you access to some application specific variables
12221188
automatically:
12231189

12241190
``app.user``
1225-
The current user object.
1191+
The representation of the current user or ``null`` if there is none. The
1192+
value stored in this variable can be a :class:`Symfony\\Component\\Security\\Core\\User\\UserInterface`
1193+
object, any other object which implements a ``__toString()`` method or even
1194+
a regular string.
12261195
``app.request``
1227-
The request object.
1196+
The :class:`Symfony\\Component\\HttpFoundation\\Request` object that represents
1197+
the current request (depending on your application, this can be a sub-request
1198+
or a regular request, as explained later).
12281199
``app.session``
1229-
The session object.
1200+
The :class:`Symfony\\Component\\HttpFoundation\\Session\\Session` object that
1201+
represents the current user's session or ``null`` if there is none.
12301202
``app.environment``
1231-
The current environment (dev, prod, etc).
1203+
The name of the current environment (``dev``, ``prod``, etc).
12321204
``app.debug``
12331205
True if in debug mode. False otherwise.
12341206

‎components/dependency_injection/autowiring.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ service is marked as autowired:
6262
# app/config/services.yml
6363
services:
6464
twitter_client:
65-
class: 'AppBundle\TwitterClient'
65+
class: AppBundle\TwitterClient
6666
autowire: true
6767
6868
.. code-block:: xml
@@ -200,10 +200,10 @@ subsystem isn't able to find itself the interface implementation to register:
200200
# app/config/services.yml
201201
services:
202202
rot13_transformer:
203-
class: 'AppBundle\Rot13Transformer'
203+
class: AppBundle\Rot13Transformer
204204
205205
twitter_client:
206-
class: 'AppBundle\TwitterClient'
206+
class: AppBundle\TwitterClient
207207
autowire: true
208208
209209
.. code-block:: xml

‎components/dependency_injection/parentservices.rst

Lines 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
@@ -323,13 +323,13 @@ to the ``NewsletterManager`` class, the config would look like this:
323323
- [setEmailFormatter, ['@my_email_formatter']]
324324
325325
newsletter_manager:
326-
class: 'NewsletterManager'
326+
class: NewsletterManager
327327
parent: mail_manager
328328
calls:
329329
- [setMailer, ['@my_alternative_mailer']]
330330
331331
greeting_card_manager:
332-
class: 'GreetingCardManager'
332+
class: GreetingCardManager
333333
parent: mail_manager
334334
335335
.. code-block:: xml

‎components/dom_crawler.rst

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -129,9 +129,6 @@ aliases both with :method:`Symfony\\Component\\DomCrawler\\Crawler::filterXPath`
129129

130130
and :method:`Symfony\\Component\\DomCrawler\\Crawler::filter`::
131131

132-
use Symfony\Component\CssSelector\CssSelector;
133-
134-
CssSelector::disableHtmlExtension();
135132
$crawler = $crawler->filter('default|entry media|group yt|aspectRatio');
136133

137134
.. note::
@@ -150,12 +147,6 @@ Namespaces can be explicitly registered with the
150147
$crawler->registerNamespace('m', 'http://search.yahoo.com/mrss/');
151148
$crawler = $crawler->filterXPath('//m:group//yt:aspectRatio');
152149

153-
.. caution::
154-
155-
To query XML with a CSS selector, the HTML extension needs to be disabled with
156-
:method:`CssSelector::disableHtmlExtension <Symfony\\Component\\CssSelector\\CssSelector::disableHtmlExtension>`
157-
to avoid converting the selector to lowercase.
158-
159150
Node Traversing
160151
~~~~~~~~~~~~~~~
161152

‎components/http_foundation/trusting_proxies.rst

Lines 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
@@ -26,11 +26,19 @@ your proxy.
2626
// only trust proxy headers coming from this IP addresses
2727
Request::setTrustedProxies(array('192.0.0.1', '10.0.0.0/8'));
2828
29+
You should also make sure that your proxy filters unauthorized use of these
30+
headers, e.g. if a proxy natively uses the ``X-Forwarded-For`` header, it
31+
should not allow clients to send ``Forwarded`` headers to Symfony.
32+
33+
If your proxy does not filter headers appropriately, you need to configure
34+
Symfony not to trust the headers your proxy does not filter (see below).
35+
2936
Configuring Header Names
3037
------------------------
3138

3239
By default, the following proxy headers are trusted:
3340

41+
* ``Forwarded`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
3442
* ``X-Forwarded-For`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
3543
* ``X-Forwarded-Host`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getHost`;
3644
* ``X-Forwarded-Port`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getPort`;
@@ -39,6 +47,7 @@ By default, the following proxy headers are trusted:
3947
If your reverse proxy uses a different header name for any of these, you
4048
can configure that header name via :method:`Symfony\\Component\\HttpFoundation\\Request::setTrustedHeaderName`::
4149

50+
Request::setTrustedHeaderName(Request::HEADER_FORWARDED, 'X-Forwarded');
4251
Request::setTrustedHeaderName(Request::HEADER_CLIENT_IP, 'X-Proxy-For');
4352
Request::setTrustedHeaderName(Request::HEADER_CLIENT_HOST, 'X-Proxy-Host');
4453
Request::setTrustedHeaderName(Request::HEADER_CLIENT_PORT, 'X-Proxy-Port');
@@ -47,9 +56,9 @@ can configure that header name via :method:`Symfony\\Component\\HttpFoundation\\
4756
Not Trusting certain Headers
4857
----------------------------
4958

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

54-
// disables trusting the ``X-Forwarded-Proto`` header, the default header is used
55-
Request::setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, '');
63+
// disables trusting the ``Forwarded`` header
64+
Request::setTrustedHeaderName(Request::HEADER_FORWARDED, null);

‎cookbook/cache/varnish.rst

Lines 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

Lines changed: 28 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ via HTTPS, the client's port and the hostname being requested.
2020
Solution: trusted_proxies
2121
-------------------------
2222

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

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

62+
You are also saying that you trust that the proxy does not send conflicting
63+
headers, e.g. sending both ``X-Forwarded-For`` and ``Forwarded`` in the same
64+
request.
65+
6266
That's it! Symfony will now look for the correct headers to get information
6367
like the client's IP address, host, port and whether the request is
6468
using HTTPS.
@@ -92,6 +96,29 @@ That's it! It's critical that you prevent traffic from all non-trusted sources.
9296
If you allow outside traffic, they could "spoof" their true IP address and
9397
other information.
9498

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

‎reference/configuration/framework.rst

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1052,10 +1052,6 @@ Now, the same asset will be rendered as ``/images/logo.png?v2`` If you use
10521052
this feature, you **must** manually increment the ``version`` value
10531053
before each deployment so that the query parameters change.
10541054

1055-
It's also possible to set the version value on an asset-by-asset basis (instead
1056-
of using the global version - e.g. ``v2`` - set here). See
1057-
:ref:`Versioning by Asset <book-templating-version-by-asset>` for details.
1058-
10591055
You can also control how the query string works via the `version_format`_
10601056
option.
10611057

‎reference/twig_reference.rst

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,8 @@ asset
107107

108108
Returns a public path to ``path``, which takes into account the base path
109109
set for the package and the URL path. More information in
110-
:ref:`book-templating-assets`. For asset versioning, see :ref:`reference-framework-assets-version`.
110+
:ref:`book-templating-assets`. For asset versioning, see
111+
:ref:`reference-framework-assets-version`.
111112

112113
assets_version
113114
~~~~~~~~~~~~~~
@@ -344,34 +345,52 @@ information in :ref:`book-templating-pages`.
344345
absolute_url
345346
~~~~~~~~~~~~
346347

348+
.. versionadded:: 2.7
349+
The ``absolute_url()`` function was introduced in Symfony 2.7.
350+
347351
.. code-block:: jinja
348352
349353
{{ absolute_url(path) }}
350354
351355
``path``
352356
**type**: ``string``
353357

354-
Returns the absolute URL for the given absolute path. This is useful to convert
355-
an existing path:
358+
Returns the absolute URL from the passed relative path. For example, assume
359+
you're on the following page in your app:
360+
``http://example.com/products/hover-board``.
356361

357362
.. code-block:: jinja
358363
359-
{{ absolute_url(asset(path)) }}
364+
{{ absolute_url('/human.txt') }}
365+
{# http://example.com/human.txt #}
366+
367+
{{ absolute_url('products_icon.png') }}
368+
{# http://example.com/products/products_icon.png #}
360369
361370
relative_path
362371
~~~~~~~~~~~~~
363372

373+
.. versionadded:: 2.7
374+
The ``relative_path()`` function was introduced in Symfony 2.7.
375+
364376
.. code-block:: jinja
365377
366378
{{ relative_path(path) }}
367379
368380
``path``
369381
**type**: ``string``
370382

371-
Returns a relative path for the given absolute path (based on the current
372-
request path). For instance, if the current path is
373-
``/article/news/welcome.html``, the relative path for ``/article/image.png`` is
374-
``../images.png``.
383+
Returns the relative path from the passed absolute URL. For example, assume
384+
you're on the following page in your app:
385+
``http://example.com/products/hover-board``.
386+
387+
.. code-block:: jinja
388+
389+
{{ relative_path('http://example.com/human.txt') }}
390+
{# ../human.txt #}
391+
392+
{{ relative_path('http://example.com/products/products_icon.png') }}
393+
{# products_icon.png #}
375394
376395
expression
377396
~~~~~~~~~~

0 commit comments

Comments
 (0)
0