Skip to content
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

Updated the Quick Tour to the latest changes introduced by Symfony #5631

Closed
wants to merge 2 commits into from
Closed
Changes from 1 commit
Commits
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
44 changes: 23 additions & 21 deletions quick_tour/the_big_picture.rst
Original file line number Diff line number Diff line change
Expand Up @@ -131,18 +131,18 @@ of database calls, HTML tags and other PHP code in the same script. To achieve
this goal with Symfony, you'll first need to learn a few fundamental concepts.

When developing a Symfony application, your responsibility as a developer
is to write the code that maps the user's *request* (e.g. ``http://localhost:8000/app/example``)
is to write the code that maps the user's *request* (e.g. ``http://localhost:8000/``)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

while it wasn't your fault, can you please remove one of the 2 spaces before the URL?

to the *resource* associated with it (the ``Homepage`` HTML page).

The code to execute is defined in **actions** and **controllers**. The mapping
between user's requests and that code is defined via the **routing** configuration.
And the contents displayed in the browser are usually rendered using **templates**.

When you browsed ``http://localhost:8000/app/example`` earlier, Symfony executed
the controller defined in the ``src/AppBundle/Controller/DefaultController.php``
file and rendered the ``app/Resources/views/default/index.html.twig`` template.
In the following sections you'll learn in detail the inner workings of Symfony
controllers, routes and templates.
When you browsed ``http://localhost:8000/`` earlier, Symfony executed the controller
defined in the ``src/AppBundle/Controller/DefaultController.php`` file and rendered
the ``app/Resources/views/default/index.html.twig`` template. In the following
sections you'll learn in detail the inner workings of Symfony controllers, routes
and templates.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new word wrapping in this paragraph is incorrect (the previous word wrapping was done by docbot)


Actions and Controllers
~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -155,11 +155,12 @@ because that will be explained in the next section)::

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Request;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not needed.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are right. I've added it to make it identical to the controller they will see. We decided to add the Request import to make it easier for newcomers: https://github.com/symfony/symfony-standard/blob/2.8/src/AppBundle/Controller/DefaultController.php#L7

However, the content of the indexAction() is not the same as in the symfony-standard. I did this because in this case it's more confusing than useful.

In any case, let me know what you think about this and I'll make the changes you say. Thanks.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure if it makes things easier to understand for newcomers when they see a use statement for a class that is not used anywhere. It could give them the feeling that simply adding the use statement triggers some magic. However, let's see what Ryan and Wouter think about it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @xabbuh here. I can see why it's usefull at the code side, I think it's confusion when doing it in the docs.


class DefaultController extends Controller
{
/**
* @Route("/app/example", name="homepage")
* @Route("/", name="homepage")
*/
public function indexAction()
{
Expand Down Expand Up @@ -197,11 +198,12 @@ at the three lines of code above the ``indexAction`` method::

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Request;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here


class DefaultController extends Controller
{
/**
* @Route("/app/example", name="homepage")
* @Route("/", name="homepage")
*/
public function indexAction()
{
Expand All @@ -217,15 +219,14 @@ start with ``/**``, whereas regular PHP comments start with ``/*``.
The first value of ``@Route()`` defines the URL that will trigger the execution
of the action. As you don't have to add the host of your application to
the URL (e.g. ```http://example.com``), these URLs are always relative and
they are usually called *paths*. In this case, the ``/app/example`` path
refers to the application homepage. The second value of ``@Route()`` (e.g.
``name="homepage"``) is optional and sets the name of this route. For now
this name is not needed, but later it'll be useful for linking pages.
they are usually called *paths*. In this case, the ``/`` path refers to the
application homepage. The second value of ``@Route()`` (e.g. ``name="homepage"``)
is optional and sets the name of this route. For now this name is not needed,
but later it'll be useful for linking pages.

Considering all this, the ``@Route("/app/example", name="homepage")`` annotation
creates a new route called ``homepage`` which makes Symfony execute the
``index`` action of the ``Default`` controller when the user browses the
``/app/example`` path of the application.
Considering all this, the ``@Route("/", name="homepage")`` annotation creates a
new route called ``homepage`` which makes Symfony execute the ``index`` action
of the ``Default`` controller when the user browses the ``/`` path of the application.

.. tip::

Expand Down Expand Up @@ -257,13 +258,14 @@ you'll see the following code:
{% extends 'base.html.twig' %}

{% block body %}
Homepage.
<h1>Welcome to Symfony</h1>

...
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be: {# ... #}

{% endblock %}

This template is created with `Twig`_, a new template engine created for
modern PHP applications. The
:doc:`second part of this tutorial </quick_tour/the_view>` will introduce
how templates work in Symfony.
This template is created with `Twig`_, a template engine created for modern PHP
applications. The :doc:`second part of this tutorial </quick_tour/the_view>`
explains how templates work in Symfony.

.. _quick-tour-big-picture-environments:

Expand Down