Skip to content

Commit 88b6551

Browse files
weaverryanweaverryan
committed
Re-proofreading and updating "the big picture" quick tour
1 parent a07d702 commit 88b6551

File tree

4 files changed

+95
-53
lines changed

4 files changed

+95
-53
lines changed

‎images/quick_tour/hello_fabien.png

57.1 KB
Loading

‎images/quick_tour/profiler.png

60.2 KB
Loading

‎images/quick_tour/web_debug_toolbar.png

58.8 KB
Loading

‎quick_tour/the_big_picture.rst

+95-53
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
The Big Picture
22
===============
33

4-
Start using Symfony2 in 10 minutes! This chapter walks you through some of the
5-
most important concepts behind Symfony2. It explains how to get started
6-
quickly by showing you the structure of a simple project.
4+
Start using Symfony2 in 10 minutes! This chapter will walk you through some
5+
of the most important concepts behind Symfony2 and explain how you can get
6+
started quickly by showing you a simple project in action.
77

88
If you've used a web framework before, you should feel right at home with
99
Symfony2. If not, welcome to a whole new way of developing web applications!
1010

11-
.. tip:
11+
.. tip::
1212

1313
Want to learn why and when you need to use a framework? Read the "`Symfony
1414
in 5 minutes`_" document.
@@ -19,7 +19,7 @@ Downloading Symfony2
1919
First, check that you have installed and configured a Web server (such as
2020
Apache) with PHP 5.3.2 or higher.
2121

22-
Ready? Let's start by downloading the "`Symfony2 Standard Edition`_", a Symfony
22+
Ready? Start by downloading the "`Symfony2 Standard Edition`_", a Symfony
2323
:term:`distribution` that is preconfigured for the most common use cases and
2424
also contains some code that demonstrates how to use Symfony2 (get the archive
2525
with the *vendors* included to get started even faster).
@@ -35,17 +35,30 @@ have a ``Symfony/`` directory that looks like this:
3535
cache/
3636
config/
3737
logs/
38+
Resources/
39+
bin/
3840
src/
3941
Acme/
4042
DemoBundle/
4143
Controller/
4244
Resources/
45+
...
4346
vendor/
4447
symfony/
4548
doctrine/
4649
...
4750
web/
4851
app.php
52+
...
53+
54+
.. note::
55+
56+
If you downloaded the Standard Edition *without vendors*, simply run the
57+
following command to download all of the vendor libraries:
58+
59+
.. code-block:: bash
60+
61+
./bin/vendors install
4962
5063
Checking the Configuration
5164
--------------------------
@@ -60,8 +73,8 @@ URL to see the diagnostics for your machine:
6073
6174
If there are any outstanding issues listed, correct them. You might also tweak
6275
your configuration by following any given recommendations. When everything is
63-
fine, click on "Go to the Welcome page" to request your first "real" Symfony2
64-
webpage:
76+
fine, click on "*Bypass configuration and go to the Welcome page*" to request
77+
your first "real" Symfony2 webpage:
6578

6679
.. code-block:: text
6780
@@ -70,13 +83,14 @@ webpage:
7083
Symfony2 should welcome and congratulate you for your hard work so far!
7184

7285
.. image:: /images/quick_tour/welcome.jpg
86+
:align: center
7387

7488
Understanding the Fundamentals
7589
------------------------------
7690

77-
One of the main goals of a framework is to ensure the `Separation of Concerns`_.
91+
One of the main goals of a framework is to ensure `Separation of Concerns`_.
7892
This keeps your code organized and allows your application to evolve easily
79-
over time by avoiding the mix of database calls, HTML tags, and business
93+
over time by avoiding the mixing of database calls, HTML tags, and business
8094
logic in the same script. To achieve this goal with Symfony, you'll first
8195
need to learn a few fundamental concepts and terms.
8296

@@ -86,14 +100,17 @@ need to learn a few fundamental concepts and terms.
86100
in the same script? Read the ":doc:`/book/from_flat_php_to_symfony2`"
87101
chapter of the book.
88102

89-
The distribution comes with some sample code that you will use to learn more
103+
The distribution comes with some sample code that you can use to learn more
90104
about the main Symfony2 concepts. Go to the following URL to be greeted by
91105
Symfony2 (replace *Fabien* with your first name):
92106

93107
.. code-block:: text
94108
95109
http://localhost/Symfony/web/app_dev.php/demo/hello/Fabien
96110
111+
.. image:: /images/quick_tour/hello_fabien.png
112+
:align: center
113+
97114
What's going on here? Let's dissect the URL:
98115

99116
* ``app_dev.php``: This is a :term:`front controller`. It is the unique entry
@@ -104,19 +121,22 @@ What's going on here? Let's dissect the URL:
104121

105122
Your responsibility as a developer is to write the code that maps the user's
106123
*request* (``/demo/hello/Fabien``) to the *resource* associated with it
107-
(``Hello Fabien!``).
124+
(the ``Hello Fabien!`` HTML page).
108125

109126
Routing
110127
~~~~~~~
111128

112129
Symfony2 routes the request to the code that handles it by trying to match the
113130
requested URL against some configured patterns. By default, these patterns
114131
(called routes) are defined in the ``app/config/routing.yml`` configuration
115-
file:
132+
file. When you're in the ``dev`` :ref:`environment<quick-tour-big-picture-environments>` -
133+
indicated by the app_**dev**.php front controller - the ``app/config/routing_dev.yml``
134+
configuration file is also loaded. In the Standard Edition, the routes to
135+
these "demo" pages are placed in that file:
116136

117137
.. code-block:: yaml
118138
119-
# app/config/routing.yml
139+
# app/config/routing_dev.yml
120140
_welcome:
121141
pattern: /
122142
defaults: { _controller: AcmeDemoBundle:Welcome:index }
@@ -126,9 +146,12 @@ file:
126146
type: annotation
127147
prefix: /demo
128148
149+
# ...
150+
129151
The first three lines (after the comment) define the code that is executed
130-
when the user requests the "``/``" resource (i.e. the welcome page). When
131-
requested, the ``AcmeDemoBundle:Welcome:index`` controller will be executed.
152+
when the user requests the "``/``" resource (i.e. the welcome page you saw
153+
earlier). When requested, the ``AcmeDemoBundle:Welcome:index`` controller
154+
will be executed. In the next section, you'll learn exactly what that means.
132155

133156
.. tip::
134157

@@ -142,12 +165,12 @@ requested, the ``AcmeDemoBundle:Welcome:index`` controller will be executed.
142165
Controllers
143166
~~~~~~~~~~~
144167

145-
A controller handles incoming *requests* and returns *responses* (often HTML
146-
code). Instead of using the PHP global variables and functions (like ``$_GET``
147-
or ``header()``) to manage these HTTP messages, Symfony uses objects:
148-
:class:`Symfony\\Component\\HttpFoundation\\Request` and
149-
:class:`Symfony\\Component\\HttpFoundation\\Response`. The simplest possible
150-
controller creates the response by hand, based on the request::
168+
A controller is a fancy name for a PHP function or method that handles incoming
169+
*requests* and returns *responses* (often HTML code). Instead of using the
170+
PHP global variables and functions (like ``$_GET`` or ``header()``) to manage
171+
these HTTP messages, Symfony uses objects: :class:`Symfony\\Component\\HttpFoundation\\Request`
172+
and :class:`Symfony\\Component\\HttpFoundation\\Response`. The simplest possible
173+
controller might create the response by hand, based on the request::
151174

152175
use Symfony\Component\HttpFoundation\Response;
153176

@@ -157,10 +180,10 @@ controller creates the response by hand, based on the request::
157180

158181
.. note::
159182

160-
Don't be fooled by the simple concepts and the power that they hold. Read
161-
the ":doc:`/book/http_fundamentals`" chapter of the book to learn more
162-
about how Symfony2 embraces HTTP and why it makes things simpler and more
163-
powerful at the same time.
183+
Symfony2 embraces the HTTP Specification, which are the rules that govern
184+
all communication on the We. Read the ":doc:`/book/http_fundamentals`"
185+
chapter of the book to learn more about this and the added power that
186+
this brings.
164187

165188
Symfony2 chooses the controller based on the ``_controller`` value from the
166189
routing configuration: ``AcmeDemoBundle:Welcome:index``. This string is the
@@ -182,13 +205,13 @@ the ``Acme\DemoBundle\Controller\WelcomeController`` class::
182205

183206
.. tip::
184207

185-
You could have used
186-
``Acme\DemoBundle\Controller\WelcomeController::indexAction`` for the
187-
``_controller`` value but if you follow some simple conventions, the
188-
logical name is more concise and allows for more flexibility.
208+
You could have used the full class and method name -
209+
``Acme\DemoBundle\Controller\WelcomeController::indexAction`` - for the
210+
``_controller`` value. But if you follow some simple conventions, the
211+
logical name is shorter and allows for more flexibility.
189212

190-
The controller class extends the built-in ``Controller`` class, which provides
191-
useful shortcut methods, like the
213+
The ``WelcomeController`` class extends the built-in ``Controller`` class,
214+
which provides useful shortcut methods, like the
192215
:method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::render`
193216
method that loads and renders a template
194217
(``AcmeDemoBundle:Welcome:index.html.twig``). The returned value is a Response
@@ -203,6 +226,11 @@ Response can be tweaked before it is sent to the browser::
203226
return $response;
204227
}
205228

229+
No matter how you do it, the end goal of your controller is always to return
230+
the ``Response`` object that should be delivered back to the user. This ``Response``
231+
object can be populated with HTML code, represent a client redirect, or even
232+
return the contents of a JPG image with a ``Content-Type`` header of ``image/jpg``.
233+
206234
.. tip::
207235

208236
Extending the ``Controller`` base class is optional. As a matter of fact,
@@ -212,21 +240,23 @@ Response can be tweaked before it is sent to the browser::
212240

213241
The template name, ``AcmeDemoBundle:Welcome:index.html.twig``, is the template
214242
*logical name* and it references the
215-
``src/Acme/DemoBundle/Resources/views/Welcome/index.html.twig`` file. The
216-
bundles section below will explain why this is useful.
243+
``Resources/views/Welcome/index.html.twig`` file inside the ``AcmeDemoBundle``
244+
(located at ``src/Acme/DemoBundle``). The bundles section below will explain
245+
why this is useful.
217246

218-
Now, take a look at the end of the routing configuration again:
247+
Now, take a look at the routing configuration again and find the ``_demo``
248+
key:
219249

220250
.. code-block:: yaml
221251
222-
# app/config/routing.yml
252+
# app/config/routing_dev.yml
223253
_demo:
224254
resource: "@AcmeDemoBundle/Controller/DemoController.php"
225255
type: annotation
226256
prefix: /demo
227257
228-
Symfony2 can read the routing information from different resources written in
229-
YAML, XML, PHP, or even embedded in PHP annotations. Here, the resource
258+
Symfony2 can read/import the routing information from different files written
259+
in YAML, XML, PHP, or even embedded in PHP annotations. Here, the file's
230260
*logical name* is ``@AcmeDemoBundle/Controller/DemoController.php`` and refers
231261
to the ``src/Acme/DemoBundle/Controller/DemoController.php`` file. In this
232262
file, routes are defined as annotations on action methods::
@@ -260,13 +290,13 @@ you can see, its value can be retrieved through the ``$name`` method argument.
260290
extensively in Symfony2 as a convenient way to configure the framework
261291
behavior and keep the configuration next to the code.
262292

263-
If you take a closer look at the action code, you can see that instead of
264-
rendering a template like before, it just returns an array of parameters. The
265-
``@Template()`` annotation tells Symfony to render the template for you,
266-
passing in each variable of the array to the template. The name of the
267-
template that's rendered follows the name of the controller. So, in this
268-
example, the ``AcmeDemoBundle:Demo:hello.html.twig`` template is rendered
269-
(located at ``src/Acme/DemoBundle/Resources/views/Demo/hello.html.twig``).
293+
If you take a closer look at the controller code, you can see that instead of
294+
rendering a template and returning a ``Response`` object like before, it
295+
just returns an array of parameters. The ``@Template()`` annotation tells
296+
Symfony to render the template for you, passing in each variable of the array
297+
to the template. The name of the template that's rendered follows the name
298+
of the controller. So, in this example, the ``AcmeDemoBundle:Demo:hello.html.twig``
299+
template is rendered (located at ``src/Acme/DemoBundle/Resources/views/Demo/hello.html.twig``).
270300

271301
.. tip::
272302

@@ -307,14 +337,25 @@ blog, a forum, ...) and which can be easily shared with other developers. As
307337
of now, we have manipulated one bundle, ``AcmeDemoBundle``. You will learn
308338
more about bundles in the last chapter of this tutorial.
309339

340+
.. _quick-tour-big-picture-environments:
341+
310342
Working with Environments
311343
-------------------------
312344

313-
Now that you have a better understanding of how Symfony2 works, have a closer
314-
look at the bottom of the page; you will notice a small bar with the Symfony2
315-
logo. This is called the "Web Debug Toolbar" and it is the developer's best
316-
friend. But this is only the tip of the iceberg; click on the weird hexadecimal
317-
number to reveal yet another very useful Symfony2 debugging tool: the profiler.
345+
Now that you have a better understanding of how Symfony2 works, take a closer
346+
look at the bottom of any Symfony2 rendered page. You should notice a small
347+
bar with the Symfony2 logo. This is called the "Web Debug Toolbar" and it
348+
is the developer's best friend.
349+
350+
.. image:: /images/quick_tour/web_debug_toolbar.png
351+
:align: center
352+
353+
But what you see initially is only the tip of the iceberg; click on the weird
354+
hexadecimal number to reveal yet another very useful Symfony2 debugging tool:
355+
the profiler.
356+
357+
.. image:: /images/quick_tour/profiler.png
358+
:align: center
318359

319360
Of course, you won't want to show these tools when you deploy your application
320361
to production. That's why you will find another front controller in the
@@ -360,17 +401,18 @@ one:
360401
toolbar: true
361402
intercept_redirects: false
362403
363-
The ``dev`` environment (defined in ``config_dev.yml``) inherits from the
364-
global ``config.yml`` file and extends it by enabling the web debug toolbar.
404+
The ``dev`` environment (which loads the ``config_dev.yml`` configuration file)
405+
imports the global ``config.yml`` file and then modifies it by, in this example,
406+
enabling the web debug toolbar.
365407

366408
Final Thoughts
367409
--------------
368410

369411
Congratulations! You've had your first taste of Symfony2 code. That wasn't so
370412
hard, was it? There's a lot more to explore, but you should already see how
371413
Symfony2 makes it really easy to implement web sites better and faster. If you
372-
are eager to learn more about Symfony2, dive into the next section: "The
373-
View".
414+
are eager to learn more about Symfony2, dive into the next section:
415+
":doc:`The View<the_view>`".
374416

375417
.. _Symfony2 Standard Edition: http://symfony.com/download
376418
.. _Symfony in 5 minutes: http://symfony.com/symfony-in-five-minutes

0 commit comments

Comments
 (0)