Skip to content

Commit 2fb8acf

Browse files
weaverryanweaverryan
committed
Merge branch '2.1'
2 parents f320634 + 2567919 commit 2fb8acf

File tree

8 files changed

+167
-33
lines changed

8 files changed

+167
-33
lines changed

‎book/forms.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1468,7 +1468,7 @@ But sometimes, you may just want to use a form without a class, and get back
14681468
an array of the submitted data. This is actually really easy::
14691469

14701470
// make sure you've imported the Request namespace above the class
1471-
use Symfony\Component\HttpFoundation\Request
1471+
use Symfony\Component\HttpFoundation\Request;
14721472
// ...
14731473

14741474
public function contactAction(Request $request)

‎components/filesystem.rst

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,11 +38,12 @@ endpoint for filesystem operations::
3838
.. note::
3939

4040
Methods :method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir`,
41-
:method:`Symfony\\Component\\Filesystem\\Filesystem::chown`,
42-
:method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp`,
43-
:method:`Symfony\\Component\\Filesystem\\Filesystem::chown`,
44-
:method:`Symfony\\Component\\Filesystem\\Filesystem::remove` and
45-
:method:`Symfony\\Component\\Filesystem\\Filesystem::touch` can receive a
41+
:method:`Symfony\\Component\\Filesystem\\Filesystem::exists`,
42+
:method:`Symfony\\Component\\Filesystem\\Filesystem::touch`,
43+
:method:`Symfony\\Component\\Filesystem\\Filesystem::remove`,
44+
:method:`Symfony\\Component\\Filesystem\\Filesystem::chmod`,
45+
:method:`Symfony\\Component\\Filesystem\\Filesystem::chown` and
46+
:method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` can receive a
4647
string, an array or any object implementing :phpclass:`Traversable` as
4748
the target argument.
4849

‎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 & 25 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,40 +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-
Symfony2 tests pass: [yes|no]
283-
Fixes the following tickets: [comma separated list of tickets fixed by the PR]
284-
Todo: [list of todos pending]
285-
License of the code: MIT
286-
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]
287283
288284
An example submission could now look as follows:
289285

290286
.. code-block:: text
291287
292-
Bug fix: no
293-
Feature addition: yes
294-
Backwards compatibility break: no
295-
Fixes the following tickets: #12, #43
296-
Todo: -
297-
License of the code: MIT
298-
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]".
299348

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

‎cookbook/form/form_collections.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,8 @@ objects. Start by creating a simple ``Task`` class::
6363
.. note::
6464

6565
The ``ArrayCollection`` is specific to Doctrine and is basically the
66-
same as using an ``array`` (but it must be an ``ArrayCollection``) if
67-
you're using Doctrine.
66+
same as using an ``array`` (but it must be an ``ArrayCollection`` if
67+
you're using Doctrine).
6868

6969
Now, create a ``Tag`` class. As you saw above, a ``Task`` can have many ``Tag``
7070
objects::

‎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)