Skip to content

Commit aa43d32

Browse files
weaverryanweaverryan
committed
Merge branch '2.3' into 2.4
* 2.3: Fixing bulleting on reverse proxy thanks to @xabbuh Title case fix thanks to @xabbuh! A bunch of changes thanks to @xabbuh and @stof [Cookbook][Forms] fix PHP template file name Fixing build error Adding another note about how AppCache is a reverse proxy at the IP address 127.0.0.1 Adding a new entry about reverse proxies in the framework and linking to it in many places labels in submit buttons + new screenshot fix php template
2 parents 6606698 + 2b1935b commit aa43d32

File tree

12 files changed

+184
-12
lines changed

12 files changed

+184
-12
lines changed

‎book/forms.rst

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ from inside a controller::
103103
$form = $this->createFormBuilder($task)
104104
->add('task', 'text')
105105
->add('dueDate', 'date')
106-
->add('save', 'submit')
106+
->add('save', 'submit', array('label' => 'Create Post'))
107107
->getForm();
108108

109109
return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
@@ -128,7 +128,9 @@ In this example, you've added two fields to your form - ``task`` and ``dueDate``
128128
corresponding to the ``task`` and ``dueDate`` properties of the ``Task`` class.
129129
You've also assigned each a "type" (e.g. ``text``, ``date``), which, among
130130
other things, determines which HTML form tag(s) is rendered for that field.
131-
Finally, you added a submit button for submitting the form to the server.
131+
132+
Finally, you added a submit button with a custom label for submitting the form to
133+
the server.
132134

133135
.. versionadded:: 2.3
134136
Support for submit buttons was introduced in Symfony 2.3. Before that, you had
@@ -217,7 +219,7 @@ controller::
217219
$form = $this->createFormBuilder($task)
218220
->add('task', 'text')
219221
->add('dueDate', 'date')
220-
->add('save', 'submit')
222+
->add('save', 'submit', array('label' => 'Create Post'))
221223
->getForm();
222224

223225
$form->handleRequest($request);
@@ -289,8 +291,8 @@ To do this, add a second button with the caption "Save and add" to your form::
289291
$form = $this->createFormBuilder($task)
290292
->add('task', 'text')
291293
->add('dueDate', 'date')
292-
->add('save', 'submit')
293-
->add('saveAndAdd', 'submit')
294+
->add('save', 'submit', array('label' => 'Create Post'))
295+
->add('saveAndAdd', 'submit', array('label' => 'Save and Add'))
294296
->getForm();
295297

296298
In your controller, use the button's

‎book/http_cache.rst

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,10 @@ kernel::
162162
The caching kernel will immediately act as a reverse proxy - caching responses
163163
from your application and returning them to the client.
164164

165+
Now that you're using a "proxy", you'll need to configure ``127.0.0.1`` under
166+
the ``trusted_proxies`` configuration (see :ref:`reference <reference-framework-trusted-proxies>`).
167+
Without this, the client's IP address and a few other things won't report correctly.
168+
165169
.. tip::
166170

167171
The cache kernel has a special ``getLog()`` method that returns a string
@@ -915,7 +919,7 @@ matter), Symfony2 uses the standard ``render`` helper to configure ESI tags:
915919
.. code-block:: html+php
916920

917921
<?php echo $view['actions']->render(
918-
new ControllerReference('...:news', array('max' => 5)),
922+
new \Symfony\Component\HttpKernel\Controller\ControllerReference('...:news', array('max' => 5)),
919923
array('strategy' => 'esi'))
920924
?>
921925

@@ -1005,8 +1009,8 @@ possible.
10051009

10061010
.. tip::
10071011

1008-
The listener only responds to local IP addresses or trusted
1009-
proxies.
1012+
The listener only responds to local IP addresses or
1013+
:doc:`trusted proxies </cookbook/request/load_balancer_reverse_proxy>`.
10101014

10111015
.. note::
10121016

‎book/templating.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -658,7 +658,7 @@ string syntax for controllers (i.e. **bundle**:**controller**:**action**):
658658
<!-- ... -->
659659
<div id="sidebar">
660660
<?php echo $view['actions']->render(
661-
new ControllerReference(
661+
new \Symfony\Component\HttpKernel\Controller\ControllerReference(
662662
'AcmeArticleBundle:Article:recentArticles',
663663
array('max' => 3)
664664
)

‎components/http_foundation/trusting_proxies.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@
44
Trusting Proxies
55
================
66

7+
.. tip::
8+
9+
If you're using the Symfony Framework, start by reading
10+
:doc:`/cookbook/request/load_balancer_reverse_proxy`.
11+
712
If you find yourself behind some sort of proxy - like a load balancer - then
813
certain header information may be sent to you using special ``X-Forwarded-*``
914
headers. For example, the ``Host`` HTTP header is usually used to return

‎cookbook/cache/varnish.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,13 @@ Because Symfony2's cache uses the standard HTTP cache headers, the
99
proxy. `Varnish`_ is a powerful, open-source, HTTP accelerator capable of serving
1010
cached content quickly and including support for :ref:`Edge Side Includes <edge-side-includes>`.
1111

12+
Trusting Reverse Proxies
13+
------------------------
14+
15+
For ESI to work correctly and for the :ref:`X-FORWARDED <varnish-x-forwarded-headers>`
16+
headers to be used, you need to configure Varnish as a
17+
:doc:`trusted proxy </cookbook/request/load_balancer_reverse_proxy>`.
18+
1219
.. index::
1320
single: Varnish; configuration
1421

@@ -188,6 +195,8 @@ that will invalidate the cache for a given resource:
188195
}
189196
}
190197
198+
.. _varnish-x-forwarded-headers:
199+
191200
Routing and X-FORWARDED Headers
192201
-------------------------------
193202

‎cookbook/form/create_custom_field_type.rst

Lines changed: 48 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ link for details), create a ``gender_widget`` block to handle this:
129129

130130
.. code-block:: html+php
131131

132-
<!-- src/Acme/DemoBundle/Resources/views/Form/gender_widget.html.twig -->
132+
<!-- src/Acme/DemoBundle/Resources/views/Form/gender_widget.html.php -->
133133
<?php if ($expanded) : ?>
134134
<ul <?php $view['form']->block($form, 'widget_container_attributes') ?>>
135135
<?php foreach ($form as $child) : ?>
@@ -151,6 +151,8 @@ link for details), create a ``gender_widget`` block to handle this:
151151
Further, the main config file should point to the custom form template
152152
so that it's used when rendering all forms.
153153

154+
When using Twig this is:
155+
154156
.. configuration-block::
155157

156158
.. code-block:: yaml
@@ -181,6 +183,51 @@ link for details), create a ``gender_widget`` block to handle this:
181183
),
182184
));
183185
186+
For the PHP templating engine, your configuration should look like this:
187+
188+
.. configuration-block::
189+
190+
.. code-block:: yaml
191+
192+
# app/config/config.yml
193+
framework:
194+
templating:
195+
form:
196+
resources:
197+
- 'AcmeDemoBundle:Form'
198+
199+
.. code-block:: xml
200+
201+
<!-- app/config/config.xml -->
202+
<?xml version="1.0" encoding="UTF-8" ?>
203+
<container xmlns="http://symfony.com/schema/dic/services"
204+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
205+
xmlns:framework="http://symfony.com/schema/dic/symfony"
206+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
207+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
208+
209+
<framework:config>
210+
<framework:templating>
211+
<framework:form>
212+
<framework:resource>AcmeDemoBundle:Form</twig:resource>
213+
</framework:form>
214+
</framework:templating>
215+
</framework:config>
216+
</container>
217+
218+
.. code-block:: php
219+
220+
// app/config/config.php
221+
$container->loadFromExtension('framework', array(
222+
'templating' => array(
223+
'form' => array(
224+
'resources' => array(
225+
'AcmeDemoBundle:Form',
226+
),
227+
),
228+
),
229+
));
230+
184231
Using the Field Type
185232
--------------------
186233

‎cookbook/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,7 @@
119119

120120
* :doc:`/cookbook/request/index`
121121

122+
* :doc:`/cookbook/request/load_balancer_reverse_proxy`
122123
* :doc:`/cookbook/request/mime_type`
123124
* (session) :doc:`/cookbook/session/locale_sticky_session`
124125

‎cookbook/request/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@ Request
44
.. toctree::
55
:maxdepth: 2
66

7+
load_balancer_reverse_proxy
78
mime_type

‎cookbook/request/load_balancer_reverse_proxy.rst

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
How to Configure Symfony to Work behind a Load Balancer or Reverse Proxy
2+
========================================================================
3+
4+
When you deploy your application, you may be behind a load balancer (e.g.
5+
an AWS Elastic Load Balancer) or a reverse proxy (e.g. Varnish for
6+
:doc:`caching</book/http_cache>`).
7+
8+
For the most part, this doesn't cause any problems with Symfony. But, when
9+
a request passes through a proxy, certain request information is sent using
10+
special ``X-Forwarded-*`` headers. For example, instead of reading the ``REMOTE_ADDR``
11+
header (which will now be the IP address of your reverse proxy), the user's
12+
true IP will be stored in an ``X-Forwarded-For`` header.
13+
14+
.. tip::
15+
16+
If you're using Symfony's :ref:`AppCache<symfony-gateway-cache>` for caching,
17+
then you *are* using a reverse proxy with the IP address ``127.0.0.1``.
18+
You'll need to configure that address as a trusted proxy below.
19+
20+
If you don't configure Symfony to look for these headers, you'll get incorrect
21+
information about the client's IP address, whether or not the client is connecting
22+
via HTTPS, the client's port and the hostname being requested.
23+
24+
Solution: trusted_proxies
25+
-------------------------
26+
27+
This is no problem, but you *do* need to tell Symfony that this is happening
28+
and which reverse proxy IP addresses will be doing this type of thing:
29+
30+
.. configuration-block::
31+
32+
.. code-block:: yaml
33+
34+
# app/config/config.yml
35+
# ...
36+
framework:
37+
trusted_proxies: [192.0.0.1, 10.0.0.0/8]
38+
39+
.. code-block:: xml
40+
41+
<!-- app/config/config.xml -->
42+
<?xml version="1.0" encoding="UTF-8" ?>
43+
<container xmlns="http://symfony.com/schema/dic/services"
44+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
45+
xmlns:framework="http://symfony.com/schema/dic/symfony"
46+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
47+
http://symfony.com/schema/dic/symfony http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
48+
49+
<framework:config trusted-proxies="192.0.0.1, 10.0.0.0/8">
50+
<!-- ... -->
51+
</framework>
52+
</container>
53+
54+
.. code-block:: php
55+
56+
// app/config/config.php
57+
$container->loadFromExtension('framework', array(
58+
'trusted_proxies' => array('192.0.0.1', '10.0.0.0/8'),
59+
));
60+
61+
In this example, you're saying that your reverse proxy (or proxies) has
62+
the IP address ``192.0.0.1`` or matches the range of IP addresses that use
63+
the CIDR notation ``10.0.0.0/8``. For more details, see :ref:`reference-framework-trusted-proxies`.
64+
65+
That's it! Symfony will now look for the correct ``X-Forwarded-*`` headers
66+
to get information like the client's IP address, host, port and whether or
67+
not the request is using HTTPS.
68+
69+
But what if the IP of my Reverse Proxy Changes Constantly!
70+
----------------------------------------------------------
71+
72+
Some reverse proxies (like Amazon's Elastic Load Balancers) don't have a
73+
static IP address or even a range that you can target with the CIDR notation.
74+
In this case, you'll need to - *very carefully* - trust *all* proxies.
75+
76+
#. Configure your web server(s) to *not* respond to traffic from *any* clients
77+
other than your load balancers. For AWS, this can be done with `security groups`_.
78+
79+
#. Once you've guaranteed that traffic will only come from your trusted reverse
80+
proxies, configure Symfony to *always* trust incoming request. This is
81+
done inside of your front controller::
82+
83+
// web/app.php
84+
// ...
85+
86+
Request::setTrustedProxies(array($request->server->get('REMOTE_ADDR')));
87+
88+
$response = $kernel->handle($request);
89+
// ...
90+
91+
That's it! It's critical that you prevent traffic from all non-trusted sources.
92+
If you allow outside traffic, they could "spoof" their true IP address and
93+
other information.
94+
95+
My Reverse Proxy Uses Non-Standard (not X-Forwarded) Headers
96+
------------------------------------------------------------
97+
98+
Most reverse proxies store information on specific ``X-Forwarded-*`` headers.
99+
But if your reverse proxy uses non-standard header names, you can configure
100+
these (:doc:`see reference </components/http_foundation/trusting_proxies>`.
101+
The code for doing this will need to live in your front controller (e.g. ``web/app.php``).
102+
103+
.. _`security groups`: http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/using-elb-security-groups.html

‎cookbook/templating/PHP.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -229,7 +229,7 @@ If you create a ``fancy`` action, and want to include it into the
229229

230230
<!-- src/Acme/HelloBundle/Resources/views/Hello/index.html.php -->
231231
<?php echo $view['actions']->render(
232-
new ControllerReference('AcmeHelloBundle:Hello:fancy', array(
232+
new \Symfony\Component\HttpKernel\Controller\ControllerReference('AcmeHelloBundle:Hello:fancy', array(
233233
'name' => $name,
234234
'color' => 'green',
235235
))

‎images/book/form-simple.png

34 Bytes
Loading

‎reference/configuration/framework.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ trusted_proxies
148148
**type**: ``array``
149149

150150
Configures the IP addresses that should be trusted as proxies. For more details,
151-
see :doc:`/components/http_foundation/trusting_proxies`.
151+
see :doc:`/cookbook/request/load_balancer_reverse_proxy`.
152152

153153
.. versionadded:: 2.3
154154
CIDR notation support was introduced in Symfony 2.3, so you can whitelist whole

0 commit comments

Comments
 (0)