Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 432 lines (319 sloc) 16.281 kb
907f598 Fabien Potencier converted documentation from Markdown to reStructuredText (managed by Sp...
fabpot authored
1 The Big Picture
2 ===============
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
3
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
7
43db6c5 Ryan Weaver [quick_tour] A few further changes to language in "the big picture".
weaverryan authored
8 If you've used a web framework before, you should feel right at home with
9 Symfony2. If not, welcome to a whole new way of developing web applications!
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
10
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
11 .. tip::
3df2a5f Fabien Potencier added index information
fabpot authored
12
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
13 Want to learn why and when you need to use a framework? Read the "`Symfony
14 in 5 minutes`_" document.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
15
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
16 Downloading Symfony2
17 --------------------
18
19 First, check that you have installed and configured a Web server (such as
f3da29e ckwalsh Adjusting wording on The Big Picture intro
ckwalsh authored
20 Apache) with PHP 5.3.2 or higher.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
21
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
22 Ready? Start by downloading the "`Symfony2 Standard Edition`_", a Symfony
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
23 :term:`distribution` that is preconfigured for the most common use cases and
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
24 also contains some code that demonstrates how to use Symfony2 (get the archive
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
25 with the *vendors* included to get started even faster).
26
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
27 After unpacking the archive under your web server root directory, you should
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
28 have a ``Symfony/`` directory that looks like this:
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
29
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
30 .. code-block:: text
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
31
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
32 www/ <- your web root directory
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
33 Symfony/ <- the unpacked archive
93aae98 Fabien Potencier renamed hello/ directory to app/ as per the sandbox change
fabpot authored
34 app/
6beb989 blue-eyes Updated example codes according CS
blue-eyes authored
35 cache/
36 config/
37 logs/
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
38 Resources/
39 bin/
6beb989 blue-eyes Updated example codes according CS
blue-eyes authored
40 src/
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
41 Acme/
42 DemoBundle/
6beb989 blue-eyes Updated example codes according CS
blue-eyes authored
43 Controller/
44 Resources/
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
45 ...
447a61f Fabien Potencier renamed Application namespace to Sensio
fabpot authored
46 vendor/
47 symfony/
48 doctrine/
49 ...
6beb989 blue-eyes Updated example codes according CS
blue-eyes authored
50 web/
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
51 app.php
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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:
3474fac Fabien Potencier updated the stable API document
fabpot authored
58
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
59 .. code-block:: bash
3474fac Fabien Potencier updated the stable API document
fabpot authored
60
d24050a Fabien Potencier fixed a bash call to be nice with Windows users
fabpot authored
61 php bin/vendors install
3df2a5f Fabien Potencier added index information
fabpot authored
62
b901545 Fabien Potencier fixed various typos; made minor tweaks
fabpot authored
63 Checking the Configuration
64 --------------------------
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
65
e188b2a Ryan Weaver [quick_tour][big_picture] Fixing up some spacing and a few minor changes
weaverryan authored
66 Symfony2 comes with a visual server configuration tester to help avoid some
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
67 headaches that come from Web server or PHP misconfiguration. Use the following
68 URL to see the diagnostics for your machine:
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
69
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
70 .. code-block:: text
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
71
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
72 http://localhost/Symfony/web/config.php
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
73
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
74 If there are any outstanding issues listed, correct them. You might also tweak
75 your configuration by following any given recommendations. When everything is
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
76 fine, click on "*Bypass configuration and go to the Welcome page*" to request
77 your first "real" Symfony2 webpage:
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
78
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
79 .. code-block:: text
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
80
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
81 http://localhost/Symfony/web/app_dev.php/
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
82
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
83 Symfony2 should welcome and congratulate you for your hard work so far!
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
84
778e9ac Fabien Potencier adding an image in the quick tour
fabpot authored
85 .. image:: /images/quick_tour/welcome.jpg
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
86 :align: center
778e9ac Fabien Potencier adding an image in the quick tour
fabpot authored
87
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
88 Understanding the Fundamentals
89 ------------------------------
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
90
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
91 One of the main goals of a framework is to ensure `Separation of Concerns`_.
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
92 This keeps your code organized and allows your application to evolve easily
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
93 over time by avoiding the mixing of database calls, HTML tags, and business
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
94 logic in the same script. To achieve this goal with Symfony, you'll first
95 need to learn a few fundamental concepts and terms.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
96
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
97 .. tip::
3df2a5f Fabien Potencier added index information
fabpot authored
98
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
99 Want proof that using a framework is better than mixing everything
8340577 Ryan Weaver [quick_tour][the_big_picture] Updating links
weaverryan authored
100 in the same script? Read the ":doc:`/book/from_flat_php_to_symfony2`"
101 chapter of the book.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
102
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
103 The distribution comes with some sample code that you can use to learn more
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
104 about the main Symfony2 concepts. Go to the following URL to be greeted by
105 Symfony2 (replace *Fabien* with your first name):
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
106
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
107 .. code-block:: text
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
108
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
109 http://localhost/Symfony/web/app_dev.php/demo/hello/Fabien
af36459 Fabien Potencier updated Quick Tour for PR3
fabpot authored
110
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
111 .. image:: /images/quick_tour/hello_fabien.png
112 :align: center
113
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
114 What's going on here? Let's dissect the URL:
af36459 Fabien Potencier updated Quick Tour for PR3
fabpot authored
115
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
116 * ``app_dev.php``: This is a :term:`front controller`. It is the unique entry
117 point of the application and it responds to all user requests;
b901545 Fabien Potencier fixed various typos; made minor tweaks
fabpot authored
118
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
119 * ``/demo/hello/Fabien``: This is the *virtual path* to the resource the user
120 wants to access.
af36459 Fabien Potencier updated Quick Tour for PR3
fabpot authored
121
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
122 Your responsibility as a developer is to write the code that maps the user's
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
123 *request* (``/demo/hello/Fabien``) to the *resource* associated with it
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
124 (the ``Hello Fabien!`` HTML page).
3df2a5f Fabien Potencier added index information
fabpot authored
125
907f598 Fabien Potencier converted documentation from Markdown to reStructuredText (managed by Sp...
fabpot authored
126 Routing
127 ~~~~~~~
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
128
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
129 Symfony2 routes the request to the code that handles it by trying to match the
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
130 requested URL against some configured patterns. By default, these patterns
131 (called routes) are defined in the ``app/config/routing.yml`` configuration
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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:
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
136
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
137 .. code-block:: yaml
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
138
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
139 # app/config/routing_dev.yml
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
140 _welcome:
141 pattern: /
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
142 defaults: { _controller: AcmeDemoBundle:Welcome:index }
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
143
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
144 _demo:
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
145 resource: "@AcmeDemoBundle/Controller/DemoController.php"
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
146 type: annotation
147 prefix: /demo
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
148
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
149 # ...
150
072b9e7 Ryan Weaver [quick_tour][the_big_picture] Fixing line breaks
weaverryan authored
151 The first three lines (after the comment) define the code that is executed
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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.
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
155
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
156 .. tip::
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
157
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
158 The Symfony2 Standard Edition uses `YAML`_ for its configuration files,
159 but Symfony2 also supports XML, PHP, and annotations natively. The
160 different formats are compatible and may be used interchangeably within an
161 application. Also, the performance of your application does not depend on
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
162 the configuration format you choose as everything is cached on the very
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
163 first request.
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
164
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
165 Controllers
166 ~~~~~~~~~~~
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
167
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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::
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
174
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
175 use Symfony\Component\HttpFoundation\Response;
06c3bac Rich updated Routing
chaffneue authored
176
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
177 $name = $request->query->get('name');
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
178
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
179 return new Response('Hello '.$name, 200, array('Content-Type' => 'text/plain'));
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
180
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
181 .. note::
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
182
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
183 Symfony2 embraces the HTTP Specification, which are the rules that govern
eddae20 Edited quick_tour/the_big_picture.rst via GitHub
Alex Normand authored
184 all communication on the Web. Read the ":doc:`/book/http_fundamentals`"
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
185 chapter of the book to learn more about this and the added power that
186 this brings.
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
187
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
188 Symfony2 chooses the controller based on the ``_controller`` value from the
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
189 routing configuration: ``AcmeDemoBundle:Welcome:index``. This string is the
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
190 controller *logical name*, and it references the ``indexAction`` method from
191 the ``Acme\DemoBundle\Controller\WelcomeController`` class::
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
192
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
193 // src/Acme/DemoBundle/Controller/WelcomeController.php
194 namespace Acme\DemoBundle\Controller;
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
195
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
196 use Symfony\Bundle\FrameworkBundle\Controller\Controller;
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
197
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
198 class WelcomeController extends Controller
199 {
200 public function indexAction()
201 {
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
202 return $this->render('AcmeDemoBundle:Welcome:index.html.twig');
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
203 }
204 }
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
205
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
206 .. tip::
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
207
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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.
5af332b Fabien Potencier updated the Quick Tour for PR3 (WIP)
fabpot authored
212
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
213 The ``WelcomeController`` class extends the built-in ``Controller`` class,
214 which provides useful shortcut methods, like the
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
215 :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::render`
216 method that loads and renders a template
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
217 (``AcmeDemoBundle:Welcome:index.html.twig``). The returned value is a Response
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
218 object populated with the rendered content. So, if the needs arise, the
219 Response can be tweaked before it is sent to the browser::
907f598 Fabien Potencier converted documentation from Markdown to reStructuredText (managed by Sp...
fabpot authored
220
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
221 public function indexAction()
222 {
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
223 $response = $this->render('AcmeDemoBundle:Welcome:index.txt.twig');
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
224 $response->headers->set('Content-Type', 'text/plain');
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
225
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
226 return $response;
227 }
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
228
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
234 .. tip::
3df2a5f Fabien Potencier added index information
fabpot authored
235
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
236 Extending the ``Controller`` base class is optional. As a matter of fact,
8340577 Ryan Weaver [quick_tour][the_big_picture] Updating links
weaverryan authored
237 a controller can be a plain PHP function or even a PHP closure.
238 ":doc:`The Controller</book/controller>`" chapter of the book tells you
239 everything about Symfony2 controllers.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
240
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
241 The template name, ``AcmeDemoBundle:Welcome:index.html.twig``, is the template
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
242 *logical name* and it references the
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
246
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
247 Now, take a look at the routing configuration again and find the ``_demo``
248 key:
907f598 Fabien Potencier converted documentation from Markdown to reStructuredText (managed by Sp...
fabpot authored
249
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
250 .. code-block:: yaml
907f598 Fabien Potencier converted documentation from Markdown to reStructuredText (managed by Sp...
fabpot authored
251
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
252 # app/config/routing_dev.yml
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
253 _demo:
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
254 resource: "@AcmeDemoBundle/Controller/DemoController.php"
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
255 type: annotation
256 prefix: /demo
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
257
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
260 *logical name* is ``@AcmeDemoBundle/Controller/DemoController.php`` and refers
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
261 to the ``src/Acme/DemoBundle/Controller/DemoController.php`` file. In this
262 file, routes are defined as annotations on action methods::
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
263
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
264 // src/Acme/DemoBundle/Controller/DemoController.php
06f3bcb Fabien Potencier updated annotations
fabpot authored
265 use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
266 use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
267
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
268 class DemoController extends Controller
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
269 {
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
270 /**
06f3bcb Fabien Potencier updated annotations
fabpot authored
271 * @Route("/hello/{name}", name="_demo_hello")
272 * @Template()
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
273 */
274 public function helloAction($name)
f9d1100 Fabien Potencier fixed coding standards
fabpot authored
275 {
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
276 return array('name' => $name);
f9d1100 Fabien Potencier fixed coding standards
fabpot authored
277 }
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
278
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
279 // ...
280 }
e188b2a Ryan Weaver [quick_tour][big_picture] Fixing up some spacing and a few minor changes
weaverryan authored
281
06f3bcb Fabien Potencier updated annotations
fabpot authored
282 The ``@Route()`` annotation defines a new route with a pattern of
283 ``/hello/{name}`` that executes the ``helloAction`` method when matched. A
284 string enclosed in curly brackets like ``{name}`` is called a placeholder. As
285 you can see, its value can be retrieved through the ``$name`` method argument.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
286
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
287 .. note::
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
288
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
289 Even if annotations are not natively supported by PHP, you use them
290 extensively in Symfony2 as a convenient way to configure the framework
291 behavior and keep the configuration next to the code.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
292
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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``).
858af75 Peter Dietrich More details to lower the threshold for beginners
Xosofox authored
300
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
301 .. tip::
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
302
06f3bcb Fabien Potencier updated annotations
fabpot authored
303 The ``@Route()`` and ``@Template()`` annotations are more powerful than
304 the simple examples shown in this tutorial. Learn more about "`annotations
305 in controllers`_" in the official documentation.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
306
907f598 Fabien Potencier converted documentation from Markdown to reStructuredText (managed by Sp...
fabpot authored
307 Templates
308 ~~~~~~~~~
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
309
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
310 The controller renders the
311 ``src/Acme/DemoBundle/Resources/views/Demo/hello.html.twig`` template (or
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
312 ``AcmeDemoBundle:Demo:hello.html.twig`` if you use the logical name):
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
313
5d9a9ba Fabien Potencier made Twig the default in the Quick Tour
fabpot authored
314 .. code-block:: jinja
907f598 Fabien Potencier converted documentation from Markdown to reStructuredText (managed by Sp...
fabpot authored
315
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
316 {# src/Acme/DemoBundle/Resources/views/Demo/hello.html.twig #}
414400f Fabien Potencier reverted Bundle suffix removal
fabpot authored
317 {% extends "AcmeDemoBundle::layout.html.twig" %}
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
318
319 {% block title "Hello " ~ name %}
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
320
5d9a9ba Fabien Potencier made Twig the default in the Quick Tour
fabpot authored
321 {% block content %}
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
322 <h1>Hello {{ name }}!</h1>
5d9a9ba Fabien Potencier made Twig the default in the Quick Tour
fabpot authored
323 {% endblock %}
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
324
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
325 By default, Symfony2 uses `Twig`_ as its template engine but you can also use
326 traditional PHP templates if you choose. The next chapter will introduce how
327 templates work in Symfony2.
bffbcd3 Ryan Weaver [quick_tour] Making a few tweaks to earlier modifications to this sectio...
weaverryan authored
328
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
329 Bundles
330 ~~~~~~~
331
332 You might have wondered why the :term:`bundle` word is used in many names we
333 have seen so far. All the code you write for your application is organized in
334 bundles. In Symfony2 speak, a bundle is a structured set of files (PHP files,
335 stylesheets, JavaScripts, images, ...) that implements a single feature (a
336 blog, a forum, ...) and which can be easily shared with other developers. As
337 of now, we have manipulated one bundle, ``AcmeDemoBundle``. You will learn
338 more about bundles in the last chapter of this tutorial.
3df2a5f Fabien Potencier added index information
fabpot authored
339
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
340 .. _quick-tour-big-picture-environments:
341
b901545 Fabien Potencier fixed various typos; made minor tweaks
fabpot authored
342 Working with Environments
343 -------------------------
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
344
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
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
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
359
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
360 Of course, you won't want to show these tools when you deploy your application
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
361 to production. That's why you will find another front controller in the
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
362 ``web/`` directory (``app.php``), which is optimized for the production environment:
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
363
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
364 .. code-block:: text
365
366 http://localhost/Symfony/web/app.php/demo/hello/Fabien
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
367
b901545 Fabien Potencier fixed various typos; made minor tweaks
fabpot authored
368 And if you use Apache with ``mod_rewrite`` enabled, you can even omit the
9d663a8 Fabien Potencier renamed index*.php to app*.php
fabpot authored
369 ``app.php`` part of the URL:
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
370
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
371 .. code-block:: text
372
373 http://localhost/Symfony/web/demo/hello/Fabien
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
374
bffbcd3 Ryan Weaver [quick_tour] Making a few tweaks to earlier modifications to this sectio...
weaverryan authored
375 Last but not least, on the production servers, you should point your web root
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
376 directory to the ``web/`` directory to secure your installation and have an
377 even better looking URL:
378
379 .. code-block:: text
bffbcd3 Ryan Weaver [quick_tour] Making a few tweaks to earlier modifications to this sectio...
weaverryan authored
380
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
381 http://localhost/demo/hello/Fabien
bffbcd3 Ryan Weaver [quick_tour] Making a few tweaks to earlier modifications to this sectio...
weaverryan authored
382
28f10a7 Massimo Giagnoni [quick-tour][big-picture] Added note for prod front controller URLs
mgiagnoni authored
383 .. note::
384
385 Note that the three URLs above are provided here only as **examples** of
386 how a URL looks like when the production front controller is used (with or
387 without mod_rewrite). If you actually try them in an out of the box
388 installation of *Symfony Standard Edition* you will get a 404 error as
389 *AcmeDemoBundle* is enabled only in dev environment and its routes imported
390 in *app/config/routing_dev.yml*.
391
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
392 To make you application respond faster, Symfony2 maintains a cache under the
393 ``app/cache/`` directory. In the development environment (``app_dev.php``),
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
394 this cache is flushed automatically whenever you make changes to any code or
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
395 configuration. But that's not the case in the production environment
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
396 (``app.php``) where performance is key. That's why you should always use
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
397 the development environment when developing your application.
398
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
399 Different :term:`environments<environment>` of a given application differ
400 only in their configuration. In fact, a configuration can inherit from another
401 one:
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
402
403 .. code-block:: yaml
404
405 # app/config/config_dev.yml
406 imports:
407 - { resource: config.yml }
408
409 web_profiler:
410 toolbar: true
411 intercept_redirects: false
412
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
413 The ``dev`` environment (which loads the ``config_dev.yml`` configuration file)
414 imports the global ``config.yml`` file and then modifies it by, in this example,
415 enabling the web debug toolbar.
ff7a141 Fabien Potencier added the Quick Tour tutorial in English
fabpot authored
416
417 Final Thoughts
418 --------------
419
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
420 Congratulations! You've had your first taste of Symfony2 code. That wasn't so
421 hard, was it? There's a lot more to explore, but you should already see how
422 Symfony2 makes it really easy to implement web sites better and faster. If you
88b6551 Ryan Weaver Re-proofreading and updating "the big picture" quick tour
weaverryan authored
423 are eager to learn more about Symfony2, dive into the next section:
424 ":doc:`The View<the_view>`".
2141e85 Fabien Potencier updated the Quick Tour
fabpot authored
425
8f2d2c8 Ryan Weaver [quick_tour][the_big_picture] Proofreading and making minor modification...
weaverryan authored
426 .. _Symfony2 Standard Edition: http://symfony.com/download
427 .. _Symfony in 5 minutes: http://symfony.com/symfony-in-five-minutes
428 .. _Separation of Concerns: http://en.wikipedia.org/wiki/Separation_of_concerns
429 .. _YAML: http://www.yaml.org/
02d3e3f Ryan Weaver [quick_tour] Fixing bad link - see #663
weaverryan authored
430 .. _annotations in controllers: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html#annotations-for-controllers
3cad1b7 Fabien Potencier updated Twig domain name
fabpot authored
431 .. _Twig: http://twig.sensiolabs.org/
Something went wrong with that request. Please try again.