Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit87df252

Browse files
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, typosCommits-------888e47e added missing ref in routing ch7a3255e controller ch review, part 1
2 parents9860554 +888e47e commit87df252

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 theaction method (``$name``).
141+
to thecontroller 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 thereisno ``foo``
334-
parameter defined in the route::
345+
Making the argument optional, however,isperfectly 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)
[8]ページ先頭
©2009-2025 Movatter.jp