Skip to content

Commit 2567919

Browse files
weaverryanweaverryan
committed
Merge branch '2.0' into 2.1
Conflicts: components/http_foundation/index.rst components/map.rst.inc contributing/code/patches.rst
2 parents eed8e46 + b040bd9 commit 2567919

File tree

5 files changed

+158
-26
lines changed

5 files changed

+158
-26
lines changed

‎components/http_foundation/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,4 @@ HTTP Foundation
88
sessions
99
session_configuration
1010
session_testing
11+
trusting_proxies

‎components/http_foundation/trusting_proxies.rst

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
.. index::
2+
single: Request; Trusted Proxies
3+
4+
Trusting Proxies
5+
================
6+
7+
If you find yourself behind some sort of proxy - like a load balancer - then
8+
certain header information may be sent to you using special ``X-Forwarded-*``
9+
headers. For example, the ``Host`` HTTP header is usually used to return
10+
the requested host. But when you're behind a proxy, the true host may be
11+
stored in a ``X-Forwarded-Host`` header.
12+
13+
Since HTTP headers can be spoofed, Symfony2 does *not* trust these proxy
14+
headers by default. If you are behind a proxy, you should manually whitelist
15+
your proxy::
16+
17+
use Symfony\Component\HttpFoundation\Request;
18+
19+
$request = Request::createFromGlobals();
20+
// only trust proxy headers coming from this IP address
21+
$request->setTrustedProxies(array(192.0.0.1));
22+
23+
Configuring Header Names
24+
------------------------
25+
26+
By default, the following proxy headers are trusted:
27+
28+
* ``X-Forwarded-For`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getClientIp`;
29+
* ``X-Forwarded-Host`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getHost`;
30+
* ``X-Forwarded-Port`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getPort`;
31+
* ``X-Forwarded-Proto`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getScheme` and :method:`Symfony\\Component\\HttpFoundation\\Request::isSecure`;
32+
33+
If your reverse proxy uses a different header name for any of these, you
34+
can configure that header name via :method:`Symfony\\Component\\HttpFoundation\\Request::setTrustedHeaderName`::
35+
36+
$request->setTrustedHeaderName(Request::HEADER_CLIENT_IP, 'X-Proxy-For');
37+
$request->setTrustedHeaderName(Request::HEADER_CLIENT_HOST, 'X-Proxy-Host');
38+
$request->setTrustedHeaderName(Request::HEADER_CLIENT_PORT, 'X-Proxy-Port');
39+
$request->setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, 'X-Proxy-Proto');
40+
41+
Not trusting certain Headers
42+
----------------------------
43+
44+
By default, if you whitelist your proxy's IP address, then all four headers
45+
listed above are trusted. If you need to trust some of these headers but
46+
not others, you can do that as well::
47+
48+
// disables trusting the ``X-Forwarded-Proto`` header, the default header is used
49+
$request->setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, '');

‎components/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@
5858
* :doc:`/components/http_foundation/sessions`
5959
* :doc:`/components/http_foundation/session_configuration`
6060
* :doc:`/components/http_foundation/session_testing`
61+
* :doc:`/components/http_foundation/trusting_proxies`
6162

6263
* :doc:`/components/http_kernel/index`
6364

‎contributing/code/patches.rst

Lines changed: 74 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -200,10 +200,12 @@ Prepare your Patch for Submission
200200
When your patch is not about a bug fix (when you add a new feature or change
201201
an existing one for instance), it must also include the following:
202202

203-
* An explanation of the changes in the relevant CHANGELOG file(s);
203+
* An explanation of the changes in the relevant CHANGELOG file(s) (the ``[BC
204+
BREAK]`` or the ``[DEPRECATION]`` prefix must be used when relevant);
204205

205206
* An explanation on how to upgrade an existing application in the relevant
206-
UPGRADE file(s) if the changes break backward compatibility.
207+
UPGRADE file(s) if the changes break backward compatibility or if you
208+
deprecate something that will ultimately break backward compatibility.
207209

208210
Step 3: Submit your Patch
209211
-------------------------
@@ -262,41 +264,87 @@ pull request message, like in:
262264
[Yaml] fixed something
263265
[Form] [Validator] [FrameworkBundle] added something
264266
265-
.. tip::
266-
267-
Please use the title with "[WIP]" if the submission is not yet completed
268-
or the tests are incomplete or not yet passing.
269-
270-
Pull Request Description
271-
~~~~~~~~~~~~~~~~~~~~~~~~
272-
273267
The pull request description must include the following check list to ensure
274268
that contributions may be reviewed without needless feedback loops and that
275269
your contributions can be included into Symfony2 as quickly as possible:
276270

277271
.. code-block:: text
278272
279-
Bug fix: [yes|no]
280-
Feature addition: [yes|no]
281-
Backwards compatibility break: [yes|no]
282-
Deprecations: [what, when|no]
283-
Symfony2 tests pass: [yes|no]
284-
Fixes the following tickets: [comma separated list of tickets fixed by the PR]
285-
Todo: [list of todos pending]
286-
License of the code: MIT
287-
Documentation PR: [The reference to the documentation PR if any]
273+
| Q | A
274+
| ------------- | ---
275+
| Bug fix? | [yes|no]
276+
| New feature? | [yes|no]
277+
| BC breaks? | [yes|no]
278+
| Deprecations? | [yes|no]
279+
| Tests pass? | [yes|no]
280+
| Fixed tickets | [comma separated list of tickets fixed by the PR]
281+
| License | MIT
282+
| Doc PR | [The reference to the documentation PR if any]
288283
289284
An example submission could now look as follows:
290285

291286
.. code-block:: text
292287
293-
Bug fix: no
294-
Feature addition: yes
295-
Backwards compatibility break: no
296-
Fixes the following tickets: #12, #43
297-
Todo: -
298-
License of the code: MIT
299-
Documentation PR: symfony/symfony-docs#123
288+
| Q | A
289+
| ------------- | ---
290+
| Bug fix? | no
291+
| New feature? | no
292+
| BC breaks? | no
293+
| Deprecations? | no
294+
| Tests pass? | yes
295+
| Fixed tickets | #12, #43
296+
| License | MIT
297+
| Doc PR | symfony/symfony-docs#123
298+
299+
For typos, minor changes in the PHPDocs, or changes in translation files, use
300+
the shorter version of the check-list:
301+
302+
.. code-block:: text
303+
304+
| Q | A
305+
| ------------- | ---
306+
| Fixed tickets | [comma separated list of tickets fixed by the PR]
307+
| License | MIT
308+
309+
Some answers to the questions trigger some more requirements:
310+
311+
* If you answer yes to "Bug fix?", check if the bug is already listed in the
312+
Symfony issues and reference it/them in "Fixed tickets";
313+
314+
* If you answer yes to "New feature?", you must submit a pull request to the
315+
documentation and reference it under the "Doc PR" section;
316+
317+
* If you answer yes to "BC breaks?", the patch must contain updates to the
318+
relevant CHANGELOG and UPGRADE files;
319+
320+
* If you answer yes to "Deprecations?", the patch must contain updates to the
321+
relevant CHANGELOG and UPGRADE files;
322+
323+
* If you answer no to "Tests pass", you must add an item to a todo-list with
324+
the actions that must be done to fix the tests;
325+
326+
* If the "license" is not MIT, just don't submit the pull request as it won't
327+
be accepted anyway.
328+
329+
If some of the previous requirements are not met, create a todo-list and add
330+
relevant items:
331+
332+
.. code-block:: text
333+
334+
- [ ] fix the tests as they have not been updated yet
335+
- [ ] submit changes to the documentation
336+
- [ ] document the BC breaks
337+
338+
If the code is not finished yet because you don't have time to finish it or
339+
because you want early feedback on your work, add an item to todo-list:
340+
341+
.. code-block:: text
342+
343+
- [ ] finish the code
344+
- [ ] gather feedback my changes
345+
346+
As long as you have items in the todo-list, please prefix the pull request
347+
title with "[WIP]".
300348

301349
In the pull request description, give as much details as possible about your
302350
changes (don't hesitate to give code examples to illustrate your points). If

‎reference/configuration/framework.rst

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,9 +82,42 @@ services related to testing your application (e.g. ``test.client``) are loaded.
8282
This setting should be present in your ``test`` environment (usually via
8383
``app/config/config_test.yml``). For more information, see :doc:`/book/testing`.
8484

85+
trusted_proxies
86+
~~~~~~~~~~~~~~~
87+
88+
**type**: ``array``
89+
90+
Configures the IP addresses that should be trusted as proxies. For more details,
91+
see :doc:`/components/http_foundation/trusting_proxies`.
92+
93+
.. configuration-block::
94+
95+
.. code-block:: yaml
96+
97+
framework:
98+
trusted_proxies: [192.0.0.1]
99+
100+
.. code-block:: xml
101+
102+
<framework:config trusted-proxies="192.0.0.1">
103+
<!-- ... -->
104+
</framework>
105+
106+
.. code-block:: php
107+
108+
$container->loadFromExtension('framework', array(
109+
'trusted_proxies' => array('192.0.0.1'),
110+
));
111+
85112
trust_proxy_headers
86113
~~~~~~~~~~~~~~~~~~~
87114

115+
.. caution::
116+
117+
The ``trust_proxy_headers`` option is deprecated and will be removed in
118+
Symfony 2.3. See `trusted_proxies`_ and :doc:`/components/http_foundation/trusting_proxies`
119+
for details on how to properly trust proxy data.
120+
88121
**type**: ``Boolean``
89122

90123
Configures if HTTP headers (like ``HTTP_X_FORWARDED_FOR``, ``X_FORWARDED_PROTO``, and

0 commit comments

Comments
 (0)