8000 minor #6349 [book] controller ch review, part 1 (Talita Kocjan Zager) · symfony/symfony-docs@87df252 · GitHub
[go: up one dir, main page]
Skip to content

Commit 87df252

Browse files
weaverryanweaverryan
committed
minor #6349 [book] controller ch review, part 1 (Talita Kocjan Zager)
This PR was merged into the 2.3 branch. Discussion ---------- [book] controller ch review, part 1 | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | all | Fixed tickets | x - tried to better form the concept of controller methods and controller classes - nothing new was edded just better formed - changes in styling, wording, typos Commits ------- 888e47e added missing ref in routing ch 7a3255e controller ch review, part 1
2 parents 9860554 + 888e47e commit 87df252

File tree

2 files changed

+102
-92
lines changed

2 files changed

+102
-92
lines changed

‎book/controller.rst

Lines changed: 100 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,9 @@ common examples:
3333
* *Controller A* prepares a ``Response`` object representing the content
3434
for the homepage of the site.
3535

36-
* *Controller B* reads the ``slug`` parameter from the request to load a
36+
* *Controller B* reads the ``{slug}`` placeholder from the request to load a
3737
blog entry from the database and creates a ``Response`` object displaying
38-
that blog. If the ``slug`` can't be found in the database, it creates and
38+
that blog. If the ``{slug}`` can't be found in the database, it creates and
3939
returns a ``Response`` object with a 404 status code.
4040

4141
* *Controller C* handles the form submission of a contact form. It reads
@@ -54,31 +54,44 @@ Every request handled by a Symfony project goes through the same simple lifecycl
5454
The framework takes care of all the repetitive stuff: you just need to write
5555
your custom code in the controller function:
5656

57-
#. Each request is handled by a single front controller file (e.g. ``app.php``
58-
or ``app_dev.php``) that bootstraps the application;
57+
#. Each request executes a single front controller file (e.g. on production
58+
``app.php`` or on development ``app_dev.php``) that bootstraps the
59+
application;
5960

60-
#. The ``Router`` reads information from the request (e.g. the URI), finds
61-
a route that matches that information, and reads the ``_controller`` parameter
62-
from the route;
61+
#. Front controller's only job is to initialize Symfony's engine (called the
62+
`Kernel`) and pass it a ``Request`` object to handle;
6363

64-
#. The controller from the matched route is executed and the code inside the
65-
controller creates and returns a ``Response`` object;
64+
#. The Symfony core asks the router to inspect the request;
6665

67-
#. The HTTP headers and content of the ``Response`` object are sent back to
68-
the client.
66+
#. The router matches the incoming URL to a specific route and returns
67+
information about the route, including the controller that should be
68+
executed;
6969

70-
Creating a page is as easy as creating a controller (#3) and making a route that
71-
maps a URL to that controller (#2).
70+
#. The correct controller from the matched route is executed and the code
71+
inside the controller creates and returns the appropriate ``Response``
72+
object;
7273

73-
.. note::
74+
#. The HTTP headers and content of the ``Response`` object are sent back
75+
to the client.
76+
77+
Creating a page is as easy as creating a controller (#5) and making a route
78+
that maps a URL to that controller (#4).
79+
80+
.. image:: /images/http-xkcd-request.png
81+
:align: center
7482

75-
Though similarly named, a "front controller" is different from the
76-
"controllers" talked about in this chapter. A front controller
77-
is a short PHP file that lives in your web directory and through which
78-
all requests are directed. A typical application will have a production
79-
front controller (e.g. ``app.php``) and a development front controller
80-
(e.g. ``app_dev.php``). You'll likely never need to edit, view or worry
81-
about the front controllers in your application.
83+
Though similarly named, a "front controller" is different from the PHP
84+
functions called "controllers" talked about in this chapter. A front
85+
controller is a short PHP file that lives in your ``web/`` directory
86+
through which all requests are directed. A typical application will
87+
have a production front controller (e.g. ``app.php``) and a development
88+
front controller (e.g. ``app_dev.php``). You'll likely never need to
89+
edit, view or worry about the front controllers in your application.
90+
The "controller class" is a convenient way to group several "controllers",
91+
also called actions, together in one class (e.g. ``updateAction()``,
92+
``deleteAction()``, etc). So, a controller is a method inside a controller
93+
class. They hold your code which creates and returns the appropriate
94+
``Response`` object.
8295

8396
.. index::
8497
single: Controller; Simple example
@@ -87,10 +100,8 @@ A Simple Controller
87100
-------------------
88101

89102
While a controller can be any PHP callable (a function, method on an object,
90-
or a ``Closure``), a controller is usually a method inside a controller class.
91-
Controllers are also called *actions*.
92-
93-
.. code-block:: php
103+
or a ``Closure``), a controller is usually a method inside a controller
104+
class::
94105

95106
// src/AppBundle/Controller/HelloController.php
96107
namespace AppBundle\Controller;
@@ -105,33 +116,29 @@ Controllers are also called *actions*.
105116
}
106117
}
107118

108-
.. tip::
109-
110-
Note that the *controller* is the ``indexAction`` method, which lives
111-
inside a *controller class* (``HelloController``). Don't be confused
112-
by the naming: a *controller class* is simply a convenient way to group
113-
several controllers/actions together. Typically, the controller class
114-
will house several controllers/actions (e.g. ``updateAction``, ``deleteAction``,
115-
etc).
119+
The controller is the ``indexAction()`` method, which lives inside a
120+
controller class ``HelloController``.
116121

117122
This controller is pretty straightforward:
118123

119124
* *line 2*: Symfony takes advantage of PHP's namespace functionality to
120125
namespace the entire controller class.
121126

122-
* *line 4*: Symfony again takes advantage of PHP's namespace functionality: the ``use`` keyword imports the
123-
``Response`` class, which the controller must return.
127+
* *line 4*: Symfony again takes advantage of PHP's namespace functionality:
128+
the ``use`` keyword imports the ``Response`` class, which the controller
129+
must return.
124130

125131
* *line 6*: The class name is the concatenation of a name for the controller
126132
class (i.e. ``Hello``) and the word ``Controller``. This is a convention
127133
that provides consistency to controllers and allows them to be referenced
128-
only by the first part of the name (i.e. ``Hello``) in the routing configuration.
134+
only by the first part of the name (i.e. ``Hello``) in the routing
135+
configuration.
129136

130137
* *line 8*: Each action in a controller class is suffixed with ``Action``
131-
and is referenced in the routing configuration by the action's name (``index``).
138+
and is referenced in the routing configuration by the action's name (e.g. ``index``).
132139
In the next section, you'll create a route that maps a URI to this action.
133140
You'll learn how the route's placeholders (``{name}``) become arguments
134-
to the action method (``$name``).
141+
to the controller method (``$name``).
135142

136143
* *line 10*: The controller creates and returns a ``Response`` object.
137144

@@ -143,7 +150,7 @@ Mapping a URL to a Controller
143150

144151
The new controller returns a simple HTML page. To actually view this page
145152
in your browser, you need to create a route, which maps a specific URL path
146-
to the controller:
153+
to the controller::
147154

148155
.. configuration-block::
149156

@@ -211,13 +218,13 @@ simply creating a controller method and an associated route.
211218

212219
Simple, right?
213220

214-
.. sidebar:: The AppBundle:Hello:index controller syntax
215-
216-
If you use the YML or XML formats, you'll refer to the controller using
217-
a special shortcut syntax: ``AppBundle:Hello:index``. For more details
218-
on the controller format, see :ref:`controller-string-syntax`.
221+
.. sidebar:: Logical controller name
219222

220-
.. seealso::
223+
If you use the YAML or XML formats, you'll refer to the controller
224+
using a special shortcut syntax called *logical controller name*
225+
which, for example, looks like ``AppBundle:Hello:index``. For more
226+
details on the controller format, read
227+
:ref:`controller-string-syntax` subtitle of the Routing chapter.
221228

222229
You can learn much more about the routing system in the
223230
:doc:`Routing chapter </book/routing>`.
@@ -231,8 +238,9 @@ Route Parameters as Controller Arguments
231238
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
232239

233240
You already know that the route points to the
234-
``HelloController::indexAction()`` method that lives inside AppBundle. What's
235-
more interesting is the argument that is passed to that method::
241+
``HelloController::indexAction()`` controller method that lives inside AppBundle.
242+
What's more interesting is the argument that is passed to that controller
243+
method::
236244

237245
// src/AppBundle/Controller/HelloController.php
238246
// ...
@@ -247,11 +255,14 @@ more interesting is the argument that is passed to that method::
247255
}
248256

249257
The controller has a single argument, ``$name``, which corresponds to the
250-
``{name}`` parameter from the matched route (``ryan`` if you go to ``/hello/ryan``).
251-
When executing your controller, Symfony matches each argument with a parameter
252-
from the route. So the value for ``{name}`` is passed to ``$name``.
258+
``{name}`` placehold from the matched route (``ryan`` if you go to
259+
``/hello/ryan``). When executing controller, Symfony matches each argument
260+
with a placehold from the route. So the value for ``{name}`` is passed
261+
to ``$name``. Just make sure they the name of the placeholder is the
262+
same as the name of the argument variable.
253263

254-
Take the following more-interesting example:
264+
Take the following more-interesting example, where controller has two
265+
arguments::
255266

256267
.. configuration-block::
257268

@@ -307,62 +318,58 @@ Take the following more-interesting example:
307318
308319
return $collection;
309320
310-
Now, the controller can have two arguments::
321+
Mapping route parameters to controller arguments is easy and flexible.
322+
Keep the following guidelines in mind while you develop.
311323

312-
public function indexAction($firstName, $lastName)
313-
{
314-
// ...
315-
}
324+
#. **The order of the controller arguments does not matter**
316325

317-
Mapping route parameters to controller arguments is easy and flexible. Keep
318-
the following guidelines in mind while you develop.
326+
Symfony matches the parameter **names** from the route to the variable
327+
**names** of the controller. The arguments of the controller could be
328+
totally reordered and still work perfectly::
319329

320-
* **The order of the controller arguments does not matter**
330+
public function indexAction($lastName, $firstName)
331+
{
332+
// ...
333+
}
321334

322-
Symfony matches the parameter **names** from the route to the variable
323-
**names** of the controller. The arguments of the controller could be totally
324-
reordered and still work perfectly::
335+
#. **Each required controller argument must match up with a routing parameter**
325336

326-
public function indexAction($lastName, $firstName)
327-
{
328-
// ...
329-
}
337+
The following would throw a ``RuntimeException`` because there is no
338+
``foo`` parameter defined in the route::
330339

331-
* **Each required controller argument must match up with a routing parameter**
340+
public function indexAction($firstName, $lastName, $foo)
341+
{
342+
// ...
343+
}
332344

333-
The following would throw a ``RuntimeException`` because there is no ``foo``
334-
parameter defined in the route::
345+
Making the argument optional, however, is perfectly ok. The following
346+
example would not throw an exception::
335347

336-
public function indexAction($firstName, $lastName, $foo)
337-
{
338-
// ...
339-
}
348+
public function indexAction($firstName, $lastName, $foo = 'bar')
349+
{
350+
// ...
351+
}
340352

341-
Making the argument optional, however, is perfectly ok. The following
342-
example would not throw an exception::
353+
#. **Not all routing parameters need to be arguments on your controller**
343354

344-
public function indexAction($firstName, $lastName, $foo = 'bar')
345-
{
346-
// ...
347-
}
355+
If, for example, the ``lastName`` weren't important for your controller,
356+
you could omit it entirely::
348357

349-
* **Not all routing parameters need to be arguments on your controller**
358+
public function indexAction($firstName)
359+
{
360+
// ...
361+
}
350362

351-
If, for example, the ``lastName`` weren't important for your controller,
352-
you could omit it entirely::
363+
.. tip::
353364

354-
public function indexAction($firstName)
355-
{
356-
// ...
357-
}
365+
Every route also has a special ``_route`` parameter (you will learn more
366+
about this in the :ref:`Routing chapter <book-special-routing-parameters>`),
367+
which is equal to the name of the route that was matched (e.g. ``hello``).
368+
Though not usually useful, this is also available as a controller argument.
358369

359-
.. tip::
370+
You can also pass other variables from your route to your controller
371+
arguments. See :doc:`/cookbook/routing/extra_information`.
360372

361-
Every route also has a special ``_route`` parameter, which is equal to
362-
the name of the route that was matched (e.g. ``hello``). Though not usually
363-
useful, this is also available as a controller argument. You can also
364-
pass other variables from your route to your controller arguments. See
365-
:doc:`/cookbook/routing/extra_information`.
366373

367374
.. _book-controller-request-argument:
368375

@@ -838,3 +845,4 @@ Learn more from the Cookbook
838845
* :doc:`/cookbook/controller/service`
839846

840847
.. _`Controller class`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bundle/FrameworkBundle/Controller/Controller.php
848+

‎book/routing.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1050,6 +1050,8 @@ a slash. URLs matching this route might look like:
10501050
Symfony provides you with a way to do this by leveraging service container
10511051
parameters. Read more about this in ":doc:`/cookbook/routing/service_container_parameters`".
10521052

1053+
.. _book-special-routing-parameters:
1054+
10531055
Special Routing Parameters
10541056
~~~~~~~~~~~~~~~~~~~~~~~~~~
10551057

0 commit comments

Comments
 (0)
0