Skip to content

Commit 700513b

Browse files
bicpibicpi
committed
Merge branch '2.2' of https://github.com/symfony/symfony-docs into 2.2
2 parents 7c39d38 + 8c33ddc commit 700513b

File tree

366 files changed

+23453
-6160
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

366 files changed

+23453
-6160
lines changed

‎CONTRIBUTING.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Contributing
2+
------------
3+
4+
We love contributors! For more information on how you can contribute to the
5+
Symfony documentation, please read [Contributing to the Documentation](http://symfony.com/doc/current/contributing/documentation/overview.html)
6+
and notice the [Pull Request Format](http://symfony.com/doc/current/contributing/documentation/overview.html#pull-request-format)
7+
that helps us merge your pull requests faster!

‎README.markdown

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,11 @@ This documentation is rendered online at http://symfony.com/doc/current/
66
Contributing
77
------------
88

9-
>**Note**
10-
>Unless you're documenting a feature that's new to Symfony 2.1, all pull
11-
>requests must be based off of the **2.0** branch, **not** the master branch.
9+
>**Note**
10+
>Unless you're documenting a feature that's new to a specific version of Symfony
11+
>(e.g. Symfony 2.3), all pull requests must be based off of the **2.2** branch,
12+
>**not** the master or 2.3 branch.
1213
1314
We love contributors! For more information on how you can contribute to the
14-
Symfony documentation, please read [Contributing to the Documentation](http://symfony.com/doc/current/contributing/documentation/overview.html)
15+
Symfony documentation, please read
16+
[Contributing to the Documentation](http://symfony.com/doc/current/contributing/documentation/overview.html)

‎book/controller.rst

Lines changed: 107 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ a serialized JSON array, an image, a redirect, a 404 error or anything else
1111
you can dream up. The controller contains whatever arbitrary logic *your
1212
application* needs to render the content of a page.
1313

14-
To see how simple this is, let's look at a Symfony2 controller in action.
14+
See how simple this is by looking at a Symfony2 controller in action.
1515
The following controller would render a page that simply prints ``Hello world!``::
1616

1717
use Symfony\Component\HttpFoundation\Response;
@@ -73,7 +73,7 @@ maps a URL to that controller (#2).
7373
.. note::
7474

7575
Though similarly named, a "front controller" is different from the
76-
"controllers" we'll talk about in this chapter. A front controller
76+
"controllers" talked about in this chapter. A front controller
7777
is a short PHP file that lives in your web directory and through which
7878
all requests are directed. A typical application will have a production
7979
front controller (e.g. ``app.php``) and a development front controller
@@ -102,7 +102,7 @@ a controller object. Controllers are also called *actions*.
102102
{
103103
public function indexAction($name)
104104
{
105-
return new Response('<html><body>Hello '.$name.'!</body></html>');
105+
return new Response('<html><body>Hello '.$name.'!</body></html>');
106106
}
107107
}
108108
@@ -115,11 +115,11 @@ a controller object. Controllers are also called *actions*.
115115
will house several controllers/actions (e.g. ``updateAction``, ``deleteAction``,
116116
etc).
117117

118-
This controller is pretty straightforward, but let's walk through it:
118+
This controller is pretty straightforward:
119119

120120
* *line 4*: Symfony2 takes advantage of PHP 5.3 namespace functionality to
121121
namespace the entire controller class. The ``use`` keyword imports the
122-
``Response`` class, which our controller must return.
122+
``Response`` class, which the controller must return.
123123

124124
* *line 6*: The class name is the concatenation of a name for the controller
125125
class (i.e. ``Hello``) and the word ``Controller``. This is a convention
@@ -141,7 +141,7 @@ Mapping a URL to a Controller
141141
-----------------------------
142142

143143
The new controller returns a simple HTML page. To actually view this page
144-
in your browser, you need to create a route, which maps a specific URL pattern
144+
in your browser, you need to create a route, which maps a specific URL path
145145
to the controller:
146146

147147
.. configuration-block::
@@ -150,15 +150,22 @@ to the controller:
150150
151151
# app/config/routing.yml
152152
hello:
153-
pattern: /hello/{name}
154-
defaults: { _controller: AcmeHelloBundle:Hello:index }
153+
path: /hello/{name}
154+
defaults: { _controller: AcmeHelloBundle:Hello:index }
155155
156156
.. code-block:: xml
157157
158158
<!-- app/config/routing.xml -->
159-
<route id="hello" pattern="/hello/{name}">
160-
<default key="_controller">AcmeHelloBundle:Hello:index</default>
161-
</route>
159+
<?xml version="1.0" encoding="UTF-8" ?>
160+
<routes xmlns="http://symfony.com/schema/routing"
161+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
162+
xsi:schemaLocation="http://symfony.com/schema/routing
163+
http://symfony.com/schema/routing/routing-1.0.xsd">
164+
165+
<route id="hello" path="/hello/{name}">
166+
<default key="_controller">AcmeHelloBundle:Hello:index</default>
167+
</route>
168+
</routes>
162169
163170
.. code-block:: php
164171
@@ -189,7 +196,7 @@ see :ref:`controller-string-syntax`.
189196

190197
.. tip::
191198

192-
You can learn much more about the routing system in the :doc:`Routing chapter</book/routing>`.
199+
You can learn much more about the routing system in the :doc:`Routing chapter </book/routing>`.
193200

194201
.. index::
195202
single: Controller; Controller arguments
@@ -202,11 +209,8 @@ Route Parameters as Controller Arguments
202209
You already know that the ``_controller`` parameter ``AcmeHelloBundle:Hello:index``
203210
refers to a ``HelloController::indexAction()`` method that lives inside the
204211
``AcmeHelloBundle`` bundle. What's more interesting is the arguments that are
205-
passed to that method:
206-
207-
.. code-block:: php
212+
passed to that method::
208213

209-
<?php
210214
// src/Acme/HelloBundle/Controller/HelloController.php
211215
namespace Acme\HelloBundle\Controller;
212216

@@ -221,7 +225,7 @@ passed to that method:
221225
}
222226

223227
The controller has a single argument, ``$name``, which corresponds to the
224-
``{name}`` parameter from the matched route (``ryan`` in our example). In
228+
``{name}`` parameter from the matched route (``ryan`` in the example). In
225229
fact, when executing your controller, Symfony2 matches each argument of
226230
the controller with a parameter from the matched route. Take the following
227231
example:
@@ -232,16 +236,23 @@ example:
232236
233237
# app/config/routing.yml
234238
hello:
235-
pattern: /hello/{first_name}/{last_name}
236-
defaults: { _controller: AcmeHelloBundle:Hello:index, color: green }
239+
path: /hello/{first_name}/{last_name}
240+
defaults: { _controller: AcmeHelloBundle:Hello:index, color: green }
237241
238242
.. code-block:: xml
239243
240244
<!-- app/config/routing.xml -->
241-
<route id="hello" pattern="/hello/{first_name}/{last_name}">
242-
<default key="_controller">AcmeHelloBundle:Hello:index</default>
243-
<default key="color">green</default>
244-
</route>
245+
<?xml version="1.0" encoding="UTF-8" ?>
246+
<routes xmlns="http://symfony.com/schema/routing"
247+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
248+
xsi:schemaLocation="http://symfony.com/schema/routing
249+
http://symfony.com/schema/routing/routing-1.0.xsd">
250+
251+
<route id="hello" path="/hello/{first_name}/{last_name}">
252+
<default key="_controller">AcmeHelloBundle:Hello:index</default>
253+
<default key="color">green</default>
254+
</route>
255+
</routes>
245256
246257
.. code-block:: php
247258
@@ -335,6 +346,14 @@ working with forms, for example::
335346
.. index::
336347
single: Controller; Base controller class
337348

349+
Creating Static Pages
350+
---------------------
351+
352+
You can create a static page without even creating a controller (only a route
353+
and template are needed).
354+
355+
Use it! See :doc:`/cookbook/templating/render_without_controller`.
356+
338357
The Base Controller Class
339358
-------------------------
340359

@@ -344,9 +363,7 @@ access to any resource it might need. By extending this ``Controller`` class,
344363
you can take advantage of several helper methods.
345364

346365
Add the ``use`` statement atop the ``Controller`` class and then modify the
347-
``HelloController`` to extend it:
348-
349-
.. code-block:: php
366+
``HelloController`` to extend it::
350367

351368
// src/Acme/HelloBundle/Controller/HelloController.php
352369
namespace Acme\HelloBundle\Controller;
@@ -358,7 +375,7 @@ Add the ``use`` statement atop the ``Controller`` class and then modify the
358375
{
359376
public function indexAction($name)
360377
{
361-
return new Response('<html><body>Hello '.$name.'!</body></html>');
378+
return new Response('<html><body>Hello '.$name.'!</body></html>');
362379
}
363380
}
364381

@@ -375,13 +392,14 @@ itself.
375392

376393
Extending the base class is *optional* in Symfony; it contains useful
377394
shortcuts but nothing mandatory. You can also extend
378-
``Symfony\Component\DependencyInjection\ContainerAware``. The service
395+
:class:`Symfony\\Component\\DependencyInjection\\ContainerAware`. The service
379396
container object will then be accessible via the ``container`` property.
380397

381398
.. note::
382399

383-
You can also define your :doc:`Controllers as Services
384-
</cookbook/controller/service>`.
400+
You can also define your :doc:`Controllers as Services </cookbook/controller/service>`.
401+
This is optional, but can give you more control over the exact dependencies
402+
that are injected into your controllers.
385403

386404
.. index::
387405
single: Controller; Common tasks
@@ -422,9 +440,7 @@ perform a 301 (permanent) redirect, modify the second argument::
422440
.. tip::
423441

424442
The ``redirect()`` method is simply a shortcut that creates a ``Response``
425-
object that specializes in redirecting the user. It's equivalent to:
426-
427-
.. code-block:: php
443+
object that specializes in redirecting the user. It's equivalent to::
428444

429445
use Symfony\Component\HttpFoundation\RedirectResponse;
430446

@@ -436,7 +452,8 @@ perform a 301 (permanent) redirect, modify the second argument::
436452
Forwarding
437453
~~~~~~~~~~
438454

439-
You can also easily forward to another controller internally with the ``forward()``
455+
You can also easily forward to another controller internally with the
456+
:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::forward`
440457
method. Instead of redirecting the user's browser, it makes an internal sub-request,
441458
and calls the specified controller. The ``forward()`` method returns the ``Response``
442459
object that's returned from that controller::
@@ -445,7 +462,7 @@ object that's returned from that controller::
445462
{
446463
$response = $this->forward('AcmeHelloBundle:Hello:fancy', array(
447464
'name' => $name,
448-
'color' => 'green'
465+
'color' => 'green',
449466
));
450467

451468
// ... further modify the response or return it directly
@@ -476,14 +493,22 @@ value to each variable.
476493

477494
Like other base ``Controller`` methods, the ``forward`` method is just
478495
a shortcut for core Symfony2 functionality. A forward can be accomplished
479-
directly via the ``http_kernel`` service. A forward returns a ``Response``
480-
object::
496+
directly by duplicating the current request. When this
497+
:ref:`sub request <http-kernel-sub-requests>` is executed via the ``http_kernel``
498+
service the ``HttpKernel`` returns a ``Response`` object::
499+
500+
use Symfony\Component\HttpKernel\HttpKernelInterface;
501+
502+
$path = array(
503+
'_controller' => 'AcmeHelloBundle:Hello:fancy',
504+
'name' => $name,
505+
'color' => 'green',
506+
);
507+
$request = $this->container->get('request');
508+
$subRequest = $request->duplicate(array(), null, $path);
481509

482510
$httpKernel = $this->container->get('http_kernel');
483-
$response = $httpKernel->forward('AcmeHelloBundle:Hello:fancy', array(
484-
'name' => $name,
485-
'color' => 'green',
486-
));
511+
$response = $httpKernel->handle($subRequest, HttpKernelInterface::SUB_REQUEST);
487512

488513
.. index::
489514
single: Controller; Rendering templates
@@ -498,36 +523,57 @@ that's responsible for generating the HTML (or other format) for the controller.
498523
The ``renderView()`` method renders a template and returns its content. The
499524
content from the template can be used to create a ``Response`` object::
500525

501-
$content = $this->renderView('AcmeHelloBundle:Hello:index.html.twig', array('name' => $name));
526+
use Symfony\Component\HttpFoundation\Response;
527+
528+
$content = $this->renderView(
529+
'AcmeHelloBundle:Hello:index.html.twig',
530+
array('name' => $name)
531+
);
502532

503533
return new Response($content);
504534

505535
This can even be done in just one step with the ``render()`` method, which
506536
returns a ``Response`` object containing the content from the template::
507537

508-
return $this->render('AcmeHelloBundle:Hello:index.html.twig', array('name' => $name));
538+
return $this->render(
539+
'AcmeHelloBundle:Hello:index.html.twig',
540+
array('name' => $name)
541+
);
509542

510543
In both cases, the ``Resources/views/Hello/index.html.twig`` template inside
511544
the ``AcmeHelloBundle`` will be rendered.
512545

513546
The Symfony templating engine is explained in great detail in the
514547
:doc:`Templating </book/templating>` chapter.
515548

549+
.. tip::
550+
551+
You can even avoid calling the ``render`` method by using the ``@Template``
552+
annotation. See the
553+
:doc:`FrameworkExtraBundle documentation </bundles/SensioFrameworkExtraBundle/annotations/view>`
554+
more details.
555+
516556
.. tip::
517557

518558
The ``renderView`` method is a shortcut to direct use of the ``templating``
519559
service. The ``templating`` service can also be used directly::
520560

521561
$templating = $this->get('templating');
522-
$content = $templating->render('AcmeHelloBundle:Hello:index.html.twig', array('name' => $name));
562+
$content = $templating->render(
563+
'AcmeHelloBundle:Hello:index.html.twig',
564+
array('name' => $name)
565+
);
523566

524567
.. note::
525568

526569
It is possible to render templates in deeper subdirectories as well, however
527570
be careful to avoid the pitfall of making your directory structure unduly
528571
elaborate::
529572

530-
$templating->render('AcmeHelloBundle:Hello/Greetings:index.html.twig', array('name' => $name));
573+
$templating->render(
574+
'AcmeHelloBundle:Hello/Greetings:index.html.twig',
575+
array('name' => $name)
576+
);
531577
// index.html.twig found in Resources/views/Hello/Greetings is rendered.
532578

533579
.. index::
@@ -644,7 +690,10 @@ For example, imagine you're processing a form submit::
644690
if ($form->isValid()) {
645691
// do some sort of processing
646692

647-
$this->get('session')->getFlashBag()->add('notice', 'Your changes were saved!');
693+
$this->get('session')->getFlashBag()->add(
694+
'notice',
695+
'Your changes were saved!'
696+
);
648697

649698
return $this->redirect($this->generateUrl(...));
650699
}
@@ -669,7 +718,7 @@ the ``notice`` message:
669718
</div>
670719
{% endfor %}
671720

672-
.. code-block:: php
721+
.. code-block:: html+php
673722

674723
<?php foreach ($view['session']->getFlashBag()->get('notice') as $message): ?>
675724
<div class="flash-notice">
@@ -692,6 +741,8 @@ The only requirement for a controller is to return a ``Response`` object. The
692741
abstraction around the HTTP response - the text-based message filled with HTTP
693742
headers and content that's sent back to the client::
694743

744+
use Symfony\Component\HttpFoundation\Response;
745+
695746
// create a simple Response with a 200 status code (the default)
696747
$response = new Response('Hello '.$name, 200);
697748

@@ -707,6 +758,15 @@ headers and content that's sent back to the client::
707758
header names are normalized so that using ``Content-Type`` is equivalent
708759
to ``content-type`` or even ``content_type``.
709760

761+
.. tip::
762+
763+
There are also special classes to make certain kinds of responses easier:
764+
765+
- For JSON, there is :class:`Symfony\\Component\\HttpFoundation\\JsonResponse`.
766+
See :ref:`component-http-foundation-json-response`.
767+
- For files, there is :class:`Symfony\\Component\\HttpFoundation\\BinaryFileResponse`.
768+
See :ref:`component-http-foundation-serving-files`.
769+
710770
.. index::
711771
single: Controller; Request object
712772

0 commit comments

Comments
 (0)