8000 Javiereguiluz revamped quick tour by weaverryan · Pull Request #3613 · symfony/symfony-docs · GitHub
[go: up one dir, main page]

Skip to content

Javiereguiluz revamped quick tour #3613

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 31 commits into from
Feb 27, 2014
Merged
Changes from 1 commit
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
a84a556
[quick_tour] simplified drastically the first two sections of "The Bi…
javiereguiluz Jan 30, 2014
29992cd
[quick_tour] simplified the "routing" section
javiereguiluz Jan 31, 2014
20e9fb0
[quick_tour] updated the "Controllers" section
javiereguiluz Jan 31, 2014
f24eabc
[quick_tour] updated some screenshots
javiereguiluz Jan 31, 2014
5b3a572
[quick_tour] finished the review of "The Big Picture" chapter
javiereguiluz Jan 31, 2014
dbbc8c2
[quick_tour] updated "the view" chapter
javiereguiluz Feb 1, 2014
eb3fe4c
[quick tour] simplified "the controller" chapter
javiereguiluz Feb 1, 2014
e7dfc8b
[quick_tour] simplified "the architecture" chapter
javiereguiluz Feb 1, 2014
4ad3c44
[quick_tour] second pass to the "big picture" chapter
javiereguiluz Feb 3, 2014
2cd3bab
[quick tour] second pass to "the view" chapter
javiereguiluz Feb 3, 2014
cdb7064
[quick_tour] second pass to "the controller" chapter and
javiereguiluz Feb 4, 2014
50e136c
[quick_tour] second pass to "the architecture" chapter
javiereguiluz Feb 4, 2014
81d6e20
[quick_tour] replaced "chapter" by "part" in some tutorial parts
javiereguiluz Feb 4, 2014
38b1292
[quick_tour] removed inline links
javiereguiluz Feb 9, 2014
e004661
Bundle names should not be placed in literals
javiereguiluz Feb 9, 2014
6afc80b
Removed a wrongly inserted comma
javiereguiluz Feb 9, 2014
2fdcffd
When using server:run command, it's not necessary to add the `app_dev…
javiereguiluz Feb 9, 2014
b16c3a2
Capitalized some sentences that come after a colon
8000 javiereguiluz Feb 9, 2014
c1ad15d
Added a new headline to better structure the documentation
javiereguiluz Feb 9, 2014
75be815
Minor rewording
javiereguiluz Feb 9, 2014
42bd69f
Fixed the capitalization of a section heading
javiereguiluz Feb 9, 2014
985c68f
Replaced "variable" by "placeholder" when using {_format} inside a route
javiereguiluz Feb 9, 2014
a013b11
Removed the animated GIF showing how to install Symfony
javiereguiluz Feb 9, 2014
eca1e73
Added a more useful message for users that don't have PHP 5.4
javiereguiluz Feb 16, 2014
fdc755e
Grammar fixes proposed by @weaverryan and @WouterJ
javiereguiluz Feb 16, 2014
cb98a6c
Restored the original line that explained how a routing file is imported
javiereguiluz Feb 16, 2014
7c0037e
Restored all the original introductions for each tutorial part
javiereguiluz Feb 16, 2014
0f13ce9
[quick_tour] rewording and grammar fixes suggested by @weaverryan
javiereguiluz Feb 18, 2014
30624eb
[quick_tour] more rewording and grammar fixes
javiereguiluz Feb 18, 2014
69fdff1
[quick_tour] removed an unneeded comma
javiereguiluz Feb 18, 2014
1e36cfa
[quick_tour] rewording and grammar fixes noted by @xabbuh
javiereguiluz Feb 19, 2014
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
[quick_tour] updated the "Controllers" section
  • Loading branch information
javiereguiluz authored and weaverryan committed Feb 26, 2014
commit 20e9fb0222abfc806782224750491366f6b51888
63 changes: 18 additions & 45 deletions quick_tour/the_big_picture.rst
Original file line number Diff line number Diff line change
Expand Up @@ -146,32 +146,25 @@ will be executed. In the next section, you'll learn exactly what that means.
.. tip::

In addition to YAML format, routes can be configured in XML or PHP files
and even as annotations on PHP classes. This flexibility is one of the main
and even embedded in PHP annotations. This flexibility is one of the main
features of Symfony2, a framework that never imposes you a particular
configuration format.

Controllers
~~~~~~~~~~~

A controller is a fancy name for a PHP function or method that handles incoming
*requests* and returns *responses* (often HTML code). Instead of using the
PHP global variables and functions (like ``$_GET`` or ``header()``) to manage
these HTTP messages, Symfony uses objects: :ref:`Request<component-http-foundation-request>`
A controller is a PHP function or method that handles incoming *requests* and
returns *responses* (often HTML code). Instead of using the PHP global variables
and functions (like ``$_GET`` or ``header()``) to manage these HTTP messages
Symfony uses objects: :ref:`Request<component-http-foundation-request>`
and :ref:`Response<component-http-foundation-response>`. The simplest possible
controller might create the response by hand, based on the request::

use Symfony\Component\HttpFoundation\Response;

$name = $request->query->get('name');

return new Response('Hello '.$name, 200, array('Content-Type' => 'text/plain'));

.. note::

Symfony2 embraces the HTTP Specification, which are the rules that govern
all communication on the Web. Read the ":doc:`/book/http_fundamentals`"
chapter of the book to learn more about this and the added power that
this brings.
return new Response('Hello '.$name);

Symfony2 chooses the controller based on the ``_controller`` value from the
routing configuration: ``AcmeDemoBundle:Welcome:index``. This string is the
Expand All @@ -195,15 +188,15 @@ the ``Acme\DemoBundle\Controller\WelcomeController`` class::

You could have used the full class and method name -
``Acme\DemoBundle\Controller\WelcomeController::indexAction`` - for the
``_controller`` value. But if you follow some simple conventions, the
logical name is shorter and allows for more flexibility.
``_controller`` value. But using the logical name is shorter and allows
for more flexibility.

The ``WelcomeController`` class extends the built-in ``Controller`` class,
which provides useful shortcut methods, like the
:ref:`render()<controller-rendering-templates>` method that loads and renders
a template (``AcmeDemoBundle:Welcome:index.html.twig``). The returned value
is a Response object populated with the rendered content. So, if the need
arises, the Response can be tweaked before it is sent to the browser::
is a ``Response`` object populated with the rendered content. So, if the need
arises, F571 the ``Response`` can be tweaked before it is sent to the browser::

public function indexAction()
{
Expand All @@ -218,13 +211,6 @@ the ``Response`` object that should be delivered back to the user. This ``Respon
object can be populated with HTML code, represent a client redirect, or even
return the contents of a JPG image with a ``Content-Type`` header of ``image/jpg``.

.. tip::

Extending the ``Controller`` base class is optional. As a matter of fact,
a controller can be a plain PHP function or even a PHP closure.
":doc:`The Controller</book/controller>`" chapter of the book tells you
everything about Symfony2 controllers.

The template name, ``AcmeDemoBundle:Welcome:index.html.twig``, is the template
*logical name* and it references the ``Resources/views/Welcome/index.html.twig``
file inside the AcmeDemoBundle (located at ``src/Acme/DemoBundle``).
Expand All @@ -242,9 +228,8 @@ key:
type: annotation
prefix: /demo

Symfony2 can read/import the routing information from different files written
in YAML, XML, PHP, or even embedded in PHP annotations. Here, the file's
*logical name* is ``@AcmeDemoBundle/Controller/DemoController.php`` and refers
The *logical name* of the file containing the ``_demo`` routes is
``@AcmeDemoBundle/Controller/DemoController.php`` and refers
to the ``src/Acme/DemoBundle/Controller/DemoController.php`` file. In this
file, routes are defined as annotations on action methods::

Expand All @@ -266,31 +251,19 @@ file, routes are defined as annotations on action methods::
// ...
}

The ``@Route()`` annotation defines a new route with a path of
``/hello/{name}`` that executes the ``helloAction`` method when matched. A
string enclosed in curly brackets like ``{name}`` is called a placeholder. As
you can see, its value can be retrieved through the ``$name`` method argument.

.. note::

Even if annotations are not natively supported by PHP, you can use them
in Symfony2 as a convenient way to configure the framework behavior and
keep the configuration next to the code.
The ``@Route()`` annotation creates a new route matching the ``/hello/{name}``
path to the ``helloAction()`` method. Any string enclosed in curly brackets,
like ``{name}``, is considered a variable that can be directly retrieved as a
method argument with the same name.

If you take a closer look at the controller code, you can see that instead of
rendering a template and returning a ``Response`` object like before, it
just returns an array of parameters. The ``@Template()`` annotation tells
Symfony to render the template for you, passing in each variable of the array
to the template. The name of the template that's rendered follows the name
Symfony to render the template for you, passing to it each variable of the
returned array. The name of the template that's rendered follows the name
of the controller. So, in this example, the ``AcmeDemoBundle:Demo:hello.html.twig``
template is rendered (located at ``src/Acme/DemoBundle/Resources/views/Demo/hello.html.twig``).

.. tip::

The ``@Route()`` and ``@Template()`` annotations are more powerful than
the simple examples shown in this tutorial. Learn more about "`annotations in controllers`_"
in the official documentation.

Templates
~~~~~~~~~

Expand Down
0