Routing

Symfony2 routes the request to the code that handles it by trying to match the requested URL against some configured patterns. By default, these patterns (called routes) are defined in the app/config/routing.yml configuration file. When you're in the dev environment - indicated by the app_dev.php front controller - the app/config/routing_dev.yml configuration file is also loaded. In the Standard Edition, the routes to these "demo" pages are placed in that file:

1
2
3
4
5
6
7
8
9
10
11

# app/config/routing_dev.yml
_welcome:
    pattern:  /
    defaults: { _controller: AcmeDemoBundle:Welcome:index }

_demo:
    resource: "@AcmeDemoBundle/Controller/DemoController.php"
    type:     annotation
    prefix:   /demo

# ...

The first three lines (after the comment) define the code that is executed when the user requests the "/" resource (i.e. the welcome page you saw earlier). When requested, the AcmeDemoBundle:Welcome:index controller will be executed. In the next section, you'll learn exactly what that means.

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: Request and Response. The simplest possible controller might create the response by hand, based on the request:

1
2
3
4
5

use Symfony\Component\HttpFoundation\Response;

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

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

Symfony2 chooses the controller based on the _controller value from the routing configuration: AcmeDemoBundle:Welcome:index. This string is the controller logical name, and it references the indexAction method from the Acme\DemoBundle\Controller\WelcomeController class:

1
2
3
4
5
6
7
8
9
10
11
12

// src/Acme/DemoBundle/Controller/WelcomeController.php
namespace Acme\DemoBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class WelcomeController extends Controller
{
    public function indexAction()
    {
        return $this->render('AcmeDemoBundle:Welcome:index.html.twig');
    }
}

The WelcomeController class extends the built-in Controller class, which provides useful shortcut methods, like the render() 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 needs arise, the Response can be tweaked before it is sent to the browser:

1
2
3
4
5
6
7

public function indexAction()
{
    $response = $this->render('AcmeDemoBundle:Welcome:index.txt.twig');
    $response->headers->set('Content-Type', 'text/plain');

    return $response;
}

No matter how you do it, the end goal of your controller is always to return the Response object that should be delivered back to the user. This Response 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.

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). The bundles section below will explain why this is useful.

Now, take a look at the routing configuration again and find the _demo key:

1
2
3
4
5

# app/config/routing_dev.yml
_demo:
    resource: "@AcmeDemoBundle/Controller/DemoController.php"
    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 to the src/Acme/DemoBundle/Controller/DemoController.php file. In this file, routes are defined as annotations on action methods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// src/Acme/DemoBundle/Controller/DemoController.php
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;

class DemoController extends Controller
{
    /**
     * @Route("/hello/{name}", name="_demo_hello")
     * @Template()
     */
    public function helloAction($name)
    {
        return array('name' => $name);
    }

    // ...
}

The @Route() annotation defines a new route with a pattern 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.

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 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).

Templates

The controller renders the src/Acme/DemoBundle/Resources/views/Demo/hello.html.twig template (or AcmeDemoBundle:Demo:hello.html.twig if you use the logical name):

1
2
3
4
5
6
7
8

{# src/Acme/DemoBundle/Resources/views/Demo/hello.html.twig #}
{% extends "AcmeDemoBundle::layout.html.twig" %}

{% block title "Hello " ~ name %}

{% block content %}
    <h1>Hello {{ name }}!</h1>
{% endblock %}

By default, Symfony2 uses Twig as its template engine but you can also use traditional PHP templates if you choose. The next chapter will introduce how templates work in Symfony2.

Bundles

You might have wondered why the bundle word is used in many names you have seen so far. All the code you write for your application is organized in bundles. In Symfony2 speak, a bundle is a structured set of files (PHP files, stylesheets, JavaScripts, images, ...) that implements a single feature (a blog, a forum, ...) and which can be easily shared with other developers. As of now, you have manipulated one bundle, AcmeDemoBundle. You will learn more about bundles in the last chapter of this tutorial.