Merge branch '2.1'

book/forms.rst

@@ -1468,7 +1468,7 @@ But sometimes, you may just want to use a form without a class, and get back
 an array of the submitted data. This is actually really easy::
 
     // make sure you've imported the Request namespace above the class
-    use Symfony\Component\HttpFoundation\Request
+    use Symfony\Component\HttpFoundation\Request;
     // ...
 
     public function contactAction(Request $request)

components/filesystem.rst

@@ -38,11 +38,12 @@ endpoint for filesystem operations::
 .. note::
 
     Methods :method:`Symfony\\Component\\Filesystem\\Filesystem::mkdir`,
-    :method:`Symfony\\Component\\Filesystem\\Filesystem::chown`,
-    :method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp`,
-    :method:`Symfony\\Component\\Filesystem\\Filesystem::chown`,
-    :method:`Symfony\\Component\\Filesystem\\Filesystem::remove` and
-    :method:`Symfony\\Component\\Filesystem\\Filesystem::touch` can receive a
+    :method:`Symfony\\Component\\Filesystem\\Filesystem::exists`,
+    :method:`Symfony\\Component\\Filesystem\\Filesystem::touch`,
+    :method:`Symfony\\Component\\Filesystem\\Filesystem::remove`,
+    :method:`Symfony\\Component\\Filesystem\\Filesystem::chmod`,
+    :method:`Symfony\\Component\\Filesystem\\Filesystem::chown` and
+    :method:`Symfony\\Component\\Filesystem\\Filesystem::chgrp` can receive a
     string, an array or any object implementing :phpclass:`Traversable` as
     the target argument.
 

components/http_foundation/index.rst

@@ -8,3 +8,4 @@ HTTP Foundation
     sessions
     session_configuration
     session_testing
+    trusting_proxies

components/http_foundation/trusting_proxies.rst

@@ -0,0 +1,49 @@
+.. index::
+   single: Request; Trusted Proxies
+
+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.
+
+Since HTTP headers can be spoofed, Symfony2 does *not* trust these proxy
+headers by default. If you are behind a proxy, you should manually whitelist
+your proxy::
+
+    use Symfony\Component\HttpFoundation\Request;
+
+    $request = Request::createFromGlobals();
+    // only trust proxy headers coming from this IP address
+    $request->setTrustedProxies(array(192.0.0.1));
+
+Configuring Header Names
+------------------------
+
+By default, the following proxy headers are trusted:
+
+* ``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`;
+* ``X-Forwarded-Proto`` Used in :method:`Symfony\\Component\\HttpFoundation\\Request::getScheme` and :method:`Symfony\\Component\\HttpFoundation\\Request::isSecure`;
+
+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_CLIENT_IP, 'X-Proxy-For');
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_HOST, 'X-Proxy-Host');
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_PORT, 'X-Proxy-Port');
+    $request->setTrustedHeaderName(Request::HEADER_CLIENT_PROTO, 'X-Proxy-Proto');
+
+Not trusting certain Headers
+----------------------------
+
+By default, if you whitelist your proxy's IP address, then all four 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, '');

components/map.rst.inc

@@ -58,6 +58,7 @@
   * :doc:`/components/http_foundation/sessions`
   * :doc:`/components/http_foundation/session_configuration`
   * :doc:`/components/http_foundation/session_testing`
+  * :doc:`/components/http_foundation/trusting_proxies`
 
 * :doc:`/components/http_kernel/index`
 

contributing/code/patches.rst

@@ -200,10 +200,12 @@ Prepare your Patch for Submission
 When your patch is not about a bug fix (when you add a new feature or change
 an existing one for instance), it must also include the following:
 
-* An explanation of the changes in the relevant CHANGELOG file(s);
+* An explanation of the changes in the relevant CHANGELOG file(s) (the ``[BC
+  BREAK]`` or the ``[DEPRECATION]`` prefix must be used when relevant);
 
 * An explanation on how to upgrade an existing application in the relevant
-  UPGRADE file(s) if the changes break backward compatibility.
+  UPGRADE file(s) if the changes break backward compatibility or if you
+  deprecate something that will ultimately break backward compatibility.
 
 Step 3: Submit your Patch
 -------------------------
@@ -262,40 +264,87 @@ pull request message, like in:
     [Yaml] fixed something
     [Form] [Validator] [FrameworkBundle] added something
 
-.. tip::
-
-    Please use the title with "[WIP]" if the submission is not yet completed
-    or the tests are incomplete or not yet passing.
-
-Pull Request Description
-~~~~~~~~~~~~~~~~~~~~~~~~
-
 The pull request description must include the following check list to ensure
 that contributions may be reviewed without needless feedback loops and that
 your contributions can be included into Symfony2 as quickly as possible:
 
 .. code-block:: text
 
-    Bug fix: [yes|no]
-    Feature addition: [yes|no]
-    Backwards compatibility break: [yes|no]
-    Symfony2 tests pass: [yes|no]
-    Fixes the following tickets: [comma separated list of tickets fixed by the PR]
-    Todo: [list of todos pending]
-    License of the code: MIT
-    Documentation PR: [The reference to the documentation PR if any]
+    | Q             | A
+    | ------------- | ---
+    | Bug fix?      | [yes|no]
+    | New feature?  | [yes|no]
+    | BC breaks?    | [yes|no]
+    | Deprecations? | [yes|no]
+    | Tests pass?   | [yes|no]
+    | Fixed tickets | [comma separated list of tickets fixed by the PR]
+    | License       | MIT
+    | Doc PR        | [The reference to the documentation PR if any]
 
 An example submission could now look as follows:
 
 .. code-block:: text
 
-    Bug fix: no
-    Feature addition: yes
-    Backwards compatibility break: no
-    Fixes the following tickets: #12, #43
-    Todo: -
-    License of the code: MIT
-    Documentation PR: symfony/symfony-docs#123
+    | Q             | A
+    | ------------- | ---
+    | Bug fix?      | no
+    | New feature?  | no
+    | BC breaks?    | no
+    | Deprecations? | no
+    | Tests pass?   | yes
+    | Fixed tickets | #12, #43
+    | License       | MIT
+    | Doc PR        | symfony/symfony-docs#123
+
+For typos, minor changes in the PHPDocs, or changes in translation files, use
+the shorter version of the check-list:
+
+.. code-block:: text
+
+    | Q             | A
+    | ------------- | ---
+    | Fixed tickets | [comma separated list of tickets fixed by the PR]
+    | License       | MIT
+
+Some answers to the questions trigger some more requirements:
+
+ * If you answer yes to "Bug fix?", check if the bug is already listed in the
+   Symfony issues and reference it/them in "Fixed tickets";
+
+ * If you answer yes to "New feature?", you must submit a pull request to the
+   documentation and reference it under the "Doc PR" section;
+
+ * If you answer yes to "BC breaks?", the patch must contain updates to the
+   relevant CHANGELOG and UPGRADE files;
+
+ * If you answer yes to "Deprecations?", the patch must contain updates to the
+   relevant CHANGELOG and UPGRADE files;
+
+ * If you answer no to "Tests pass", you must add an item to a todo-list with
+   the actions that must be done to fix the tests;
+
+ * If the "license" is not MIT, just don't submit the pull request as it won't
+   be accepted anyway.
+
+If some of the previous requirements are not met, create a todo-list and add
+relevant items:
+
+.. code-block:: text
+
+    - [ ] fix the tests as they have not been updated yet
+    - [ ] submit changes to the documentation
+    - [ ] document the BC breaks
+
+If the code is not finished yet because you don't have time to finish it or
+because you want early feedback on your work, add an item to todo-list:
+
+.. code-block:: text
+
+    - [ ] finish the code
+    - [ ] gather feedback my changes
+
+As long as you have items in the todo-list, please prefix the pull request
+title with "[WIP]".
 
 In the pull request description, give as much details as possible about your
 changes (don't hesitate to give code examples to illustrate your points). If

cookbook/form/form_collections.rst

@@ -63,8 +63,8 @@ objects. Start by creating a simple ``Task`` class::
 .. note::
 
     The ``ArrayCollection`` is specific to Doctrine and is basically the
-    same as using an ``array`` (but it must be an ``ArrayCollection``) if
-    you're using Doctrine.
+    same as using an ``array`` (but it must be an ``ArrayCollection`` if
+    you're using Doctrine).
 
 Now, create a ``Tag`` class. As you saw above, a ``Task`` can have many ``Tag``
 objects::

reference/configuration/framework.rst

@@ -82,9 +82,42 @@ services related to testing your application (e.g. ``test.client``) are loaded.
 This setting should be present in your ``test`` environment (usually via
 ``app/config/config_test.yml``). For more information, see :doc:`/book/testing`.
 
+trusted_proxies
+~~~~~~~~~~~~~~~
+
+**type**: ``array``
+
+Configures the IP addresses that should be trusted as proxies. For more details,
+see :doc:`/components/http_foundation/trusting_proxies`.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        framework:
+            trusted_proxies:  [192.0.0.1]
+
+    .. code-block:: xml
+
+        <framework:config trusted-proxies="192.0.0.1">
+            <!-- ... -->
+        </framework>
+
+    .. code-block:: php
+
+        $container->loadFromExtension('framework', array(
+            'trusted_proxies' => array('192.0.0.1'),
+        ));
+
 trust_proxy_headers
 ~~~~~~~~~~~~~~~~~~~
 
+.. caution::
+
+    The ``trust_proxy_headers`` option is deprecated and will be removed in
+    Symfony 2.3. See `trusted_proxies`_ and :doc:`/components/http_foundation/trusting_proxies`
+    for details on how to properly trust proxy data.
+
 **type**: ``Boolean``
 
 Configures if HTTP headers (like ``HTTP_X_FORWARDED_FOR``, ``X_FORWARDED_PROTO``, and