Symfony2 Documentation¶

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:

# 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: Symfony\Component\HttpFoundation\Request and Symfony\Component\HttpFoundation\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'));

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:

// 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 :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::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:

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:

# 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:

// 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):

{# 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 we 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, we have manipulated one bundle, AcmeDemoBundle. You will learn more about bundles in the last chapter of this tutorial.

Including other Templates¶

The best way to share a snippet of code between several distinct templates is to create a new template that can then be included from other templates.

Create an embedded.html.twig template:

{# src/Acme/DemoBundle/Resources/views/Demo/embedded.html.twig #}
Hello {{ name }}

And change the index.html.twig template to include it:

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

{# override the body block from embedded.html.twig #}
{% block content %}
    {% include "AcmeDemoBundle:Demo:embedded.html.twig" %}
{% endblock %}

Embedding other Controllers¶

And what if you want to embed the result of another controller in a template? That’s very useful when working with Ajax, or when the embedded template needs some variable not available in the main template.

Suppose you’ve created a fancy action, and you want to include it inside the index template. To do this, use the render tag:

{# src/Acme/DemoBundle/Resources/views/Demo/index.html.twig #}
{% render "AcmeDemoBundle:Demo:fancy" with { 'name': name, 'color': 'green' } %}

Here, the AcmeDemoBundle:Demo:fancy string refers to the fancy action of the Demo controller. The arguments (name and color) act like simulated request variables (as if the fancyAction were handling a whole new request) and are made available to the controller:

// src/Acme/DemoBundle/Controller/DemoController.php

class DemoController extends Controller
{
    public function fancyAction($name, $color)
    {
        // create some object, based on the $color variable
        $object = ...;

        return $this->render('AcmeDemoBundle:Demo:fancy.html.twig', array('name' => $name, 'object' => $object));
    }

    // ...
}

Creating Links between Pages¶

Speaking of web applications, creating links between pages is a must. Instead of hardcoding URLs in templates, the path function knows how to generate URLs based on the routing configuration. That way, all your URLs can be easily updated by just changing the configuration:

<a href="{{ path('_demo_hello', { 'name': 'Thomas' }) }}">Greet Thomas!</a>

The path function takes the route name and an array of parameters as arguments. The route name is the main key under which routes are referenced and the parameters are the values of the placeholders defined in the route pattern:

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

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

Including Assets: images, JavaScripts, and stylesheets¶

What would the Internet be without images, JavaScripts, and stylesheets? Symfony2 provides the asset function to deal with them easily:

<link href="{{ asset('css/blog.css') }}" rel="stylesheet" type="text/css" />

<img src="{{ asset('images/logo.png') }}" />

The asset function’s main purpose is to make your application more portable. Thanks to this function, you can move the application root directory anywhere under your web root directory without changing anything in your template’s code.

The web/ Directory¶

The web root directory is the home of all public and static files like images, stylesheets, and JavaScript files. It is also where each front controller lives:

// web/app.php
require_once __DIR__.'/../app/bootstrap.php.cache';
require_once __DIR__.'/../app/AppKernel.php';

use Symfony\Component\HttpFoundation\Request;

$kernel = new AppKernel('prod', false);
$kernel->loadClassCache();
$kernel->handle(Request::createFromGlobals())->send();

The kernel first requires the bootstrap.php.cache file, which bootstraps the framework and registers the autoloader (see below).

Like any front controller, app.php uses a Kernel Class, AppKernel, to bootstrap the application.

The app/ Directory¶

The AppKernel class is the main entry point of the application configuration and as such, it is stored in the app/ directory.

This class must implement two methods:

• registerBundles() must return an array of all bundles needed to run the application;
• registerContainerConfiguration() loads the application configuration (more on this later).

PHP autoloading can be configured via app/autoload.php:

// app/autoload.php
use Symfony\Component\ClassLoader\UniversalClassLoader;

$loader = new UniversalClassLoader();
$loader->registerNamespaces(array(
    'Symfony'          => array(__DIR__.'/../vendor/symfony/src', __DIR__.'/../vendor/bundles'),
    'Sensio'           => __DIR__.'/../vendor/bundles',
    'JMS'              => __DIR__.'/../vendor/bundles',
    'Doctrine\\Common' => __DIR__.'/../vendor/doctrine-common/lib',
    'Doctrine\\DBAL'   => __DIR__.'/../vendor/doctrine-dbal/lib',
    'Doctrine'         => __DIR__.'/../vendor/doctrine/lib',
    'Monolog'          => __DIR__.'/../vendor/monolog/src',
    'Assetic'          => __DIR__.'/../vendor/assetic/src',
    'Metadata'         => __DIR__.'/../vendor/metadata/src',
));
$loader->registerPrefixes(array(
    'Twig_Extensions_' => __DIR__.'/../vendor/twig-extensions/lib',
    'Twig_'            => __DIR__.'/../vendor/twig/lib',
));

// ...

$loader->registerNamespaceFallbacks(array(
    __DIR__.'/../src',
));
$loader->register();

The Symfony\Component\ClassLoader\UniversalClassLoader is used to autoload files that respect either the technical interoperability standards for PHP 5.3 namespaces or the PEAR naming convention for classes. As you can see here, all dependencies are stored under the vendor/ directory, but this is just a convention. You can store them wherever you want, globally on your server or locally in your projects.

Registering a Bundle¶

An application is made up of bundles as defined in the registerBundles() method of the AppKernel class. Each bundle is a directory that contains a single Bundle class that describes it:

// app/AppKernel.php
public function registerBundles()
{
    $bundles = array(
        new Symfony\Bundle\FrameworkBundle\FrameworkBundle(),
        new Symfony\Bundle\SecurityBundle\SecurityBundle(),
        new Symfony\Bundle\TwigBundle\TwigBundle(),
        new Symfony\Bundle\MonologBundle\MonologBundle(),
        new Symfony\Bundle\SwiftmailerBundle\SwiftmailerBundle(),
        new Symfony\Bundle\DoctrineBundle\DoctrineBundle(),
        new Symfony\Bundle\AsseticBundle\AsseticBundle(),
        new Sensio\Bundle\FrameworkExtraBundle\SensioFrameworkExtraBundle(),
        new JMS\SecurityExtraBundle\JMSSecurityExtraBundle(),
    );

    if (in_array($this->getEnvironment(), array('dev', 'test'))) {
        $bundles[] = new Acme\DemoBundle\AcmeDemoBundle();
        $bundles[] = new Symfony\Bundle\WebProfilerBundle\WebProfilerBundle();
        $bundles[] = new Sensio\Bundle\DistributionBundle\SensioDistributionBundle();
        $bundles[] = new Sensio\Bundle\GeneratorBundle\SensioGeneratorBundle();
    }

    return $bundles;
}

In addition to the AcmeDemoBundle that we have already talked about, notice that the kernel also enables other bundles such as the FrameworkBundle, DoctrineBundle, SwiftmailerBundle, and AsseticBundle bundle. They are all part of the core framework.

Configuring a Bundle¶

Each bundle can be customized via configuration files written in YAML, XML, or PHP. Have a look at the default configuration:

# app/config/config.yml
imports:
    - { resource: parameters.yml }
    - { resource: security.yml }

framework:
    #esi:             ~
    #translator:      { fallback: %locale% }
    secret:          %secret%
    charset:         UTF-8
    router:          { resource: "%kernel.root_dir%/config/routing.yml" }
    form:            true
    csrf_protection: true
    validation:      { enable_annotations: true }
    templating:      { engines: ['twig'] } #assets_version: SomeVersionScheme
    default_locale:  %locale%
    session:
        auto_start:     true

# Twig Configuration
twig:
    debug:            %kernel.debug%
    strict_variables: %kernel.debug%

# Assetic Configuration
assetic:
    debug:          %kernel.debug%
    use_controller: false
    bundles:        [ ]
    # java: /usr/bin/java
    filters:
        cssrewrite: ~
        # closure:
        #     jar: %kernel.root_dir%/java/compiler.jar
        # yui_css:
        #     jar: %kernel.root_dir%/java/yuicompressor-2.4.2.jar

# Doctrine Configuration
doctrine:
    dbal:
        driver:   %database_driver%
        host:     %database_host%
        port:     %database_port%
        dbname:   %database_name%
        user:     %database_user%
        password: %database_password%
        charset:  UTF8

    orm:
        auto_generate_proxy_classes: %kernel.debug%
        auto_mapping: true

# Swiftmailer Configuration
swiftmailer:
    transport: %mailer_transport%
    host:      %mailer_host%
    username:  %mailer_user%
    password:  %mailer_password%

jms_security_extra:
    secure_controllers:  true
    secure_all_services: false

Each entry like framework defines the configuration for a specific bundle. For example, framework configures the FrameworkBundle while swiftmailer configures the SwiftmailerBundle.

Each environment can override the default configuration by providing a specific configuration file. For example, the dev environment loads the config_dev.yml file, which loads the main configuration (i.e. config.yml) and then modifies it to add some debugging tools:

# app/config/config_dev.yml
imports:
    - { resource: config.yml }

framework:
    router:   { resource: "%kernel.root_dir%/config/routing_dev.yml" }
    profiler: { only_exceptions: false }

web_profiler:
    toolbar: true
    intercept_redirects: false

monolog:
    handlers:
        main:
            type:  stream
            path:  %kernel.logs_dir%/%kernel.environment%.log
            level: debug
        firephp:
            type:  firephp
            level: info

assetic:
    use_controller: true

Extending a Bundle¶

In addition to being a nice way to organize and configure your code, a bundle can extend another bundle. Bundle inheritance allows you to override any existing bundle in order to customize its controllers, templates, or any of its files. This is where the logical names (e.g. @AcmeDemoBundle/Controller/SecuredController.php) come in handy: they abstract where the resource is actually stored.

Step1: The Client sends a Request¶

Every conversation on the web starts with a request. The request is a text message created by a client (e.g. a browser, an iPhone app, etc) in a special format known as HTTP. The client sends that request to a server, and then waits for the response.

Take a look at the first part of the interaction (the request) between a browser and the xkcd web server:

In HTTP-speak, this HTTP request would actually look something like this:

GET / HTTP/1.1
Host: xkcd.com
Accept: text/html
User-Agent: Mozilla/5.0 (Macintosh)

This simple message communicates everything necessary about exactly which resource the client is requesting. The first line of an HTTP request is the most important and contains two things: the URI and the HTTP method.

The URI (e.g. /, /contact, etc) is the unique address or location that identifies the resource the client wants. The HTTP method (e.g. GET) defines what you want to do with the resource. The HTTP methods are the verbs of the request and define the few common ways that you can act upon the resource:

With this in mind, you can imagine what an HTTP request might look like to delete a specific blog entry, for example:

DELETE /blog/15 HTTP/1.1

In addition to the first line, an HTTP request invariably contains other lines of information called request headers. The headers can supply a wide range of information such as the requested Host, the response formats the client accepts (Accept) and the application the client is using to make the request (User-Agent). Many other headers exist and can be found on Wikipedia’s List of HTTP header fields article.

Step 2: The Server returns a Response¶

Once a server has received the request, it knows exactly which resource the client needs (via the URI) and what the client wants to do with that resource (via the method). For example, in the case of a GET request, the server prepares the resource and returns it in an HTTP response. Consider the response from the xkcd web server:

Translated into HTTP, the response sent back to the browser will look something like this:

HTTP/1.1 200 OK
Date: Sat, 02 Apr 2011 21:05:05 GMT
Server: lighttpd/1.4.19
Content-Type: text/html

<html>
  <!-- HTML for the xkcd comic -->
</html>

The HTTP response contains the requested resource (the HTML content in this case), as well as other information about the response. The first line is especially important and contains the HTTP response status code (200 in this case). The status code communicates the overall outcome of the request back to the client. Was the request successful? Was there an error? Different status codes exist that indicate success, an error, or that the client needs to do something (e.g. redirect to another page). A full list can be found on Wikipedia’s List of HTTP status codes article.

Like the request, an HTTP response contains additional pieces of information known as HTTP headers. For example, one important HTTP response header is Content-Type. The body of the same resource could be returned in multiple different formats like HTML, XML, or JSON and the Content-Type header uses Internet Media Types like text/html to tell the client which format is being returned. A list of common media types can be found on Wikipedia’s List of common media types article.

Many other headers exist, some of which are very powerful. For example, certain headers can be used to create a powerful caching system.

Requests, Responses and Web Development¶

This request-response conversation is the fundamental process that drives all communication on the web. And as important and powerful as this process is, it’s inescapably simple.

The most important fact is this: regardless of the language you use, the type of application you build (web, mobile, JSON API), or the development philosophy you follow, the end goal of an application is always to understand each request and create and return the appropriate response.

Symfony is architected to match this reality.

The Front Controller¶

Traditionally, applications were built so that each “page” of a site was its own physical file:

index.php
contact.php
blog.php

There are several problems with this approach, including the inflexibility of the URLs (what if you wanted to change blog.php to news.php without breaking all of your links?) and the fact that each file must manually include some set of core files so that security, database connections and the “look” of the site can remain consistent.

A much better solution is to use a front controller: a single PHP file that handles every request coming into your application. For example:

Now, every request is handled exactly the same. Instead of individual URLs executing different PHP files, the front controller is always executed, and the routing of different URLs to different parts of your application is done internally. This solves both problems with the original approach. Almost all modern web apps do this - including apps like WordPress.

Stay Organized¶

But inside your front controller, how do you know which page should be rendered and how can you render each in a sane way? One way or another, you’ll need to check the incoming URI and execute different parts of your code depending on that value. This can get ugly quickly:

// index.php

$request = Request::createFromGlobals();
$path = $request->getPathInfo(); // the URI path being requested

if (in_array($path, array('', '/')) {
    $response = new Response('Welcome to the homepage.');
} elseif ($path == '/contact') {
    $response = new Response('Contact us');
} else {
    $response = new Response('Page not found.', 404);
}
$response->send();

Solving this problem can be difficult. Fortunately it’s exactly what Symfony is designed to do.

The Symfony Application Flow¶

When you let Symfony handle each request, life is much easier. Symfony follows the same simple pattern for every request:

Incoming requests are interpreted by the routing and passed to controller functions that return Response objects.

Each “page” of your site is defined in a routing configuration file that maps different URLs to different PHP functions. The job of each PHP function, called a controller, is to use information from the request - along with many other tools Symfony makes available - to create and return a Response object. In other words, the controller is where your code goes: it’s where you interpret the request and create a response.

It’s that easy! Let’s review:

• Each request executes a front controller file;
• The routing system determines which PHP function should be executed based on information from the request and routing configuration you’ve created;
• The correct PHP function is executed, where your code creates and returns the appropriate Response object.

A Symfony Request in Action¶

Without diving into too much detail, let’s see this process in action. Suppose you want to add a /contact page to your Symfony application. First, start by adding an entry for /contact to your routing configuration file:

contact:
    pattern:  /contact
    defaults: { _controller: AcmeDemoBundle:Main:contact }

When someone visits the /contact page, this route is matched, and the specified controller is executed. As you’ll learn in the routing chapter, the AcmeDemoBundle:Main:contact string is a short syntax that points to a specific PHP method contactAction inside a class called MainController:

class MainController
{
    public function contactAction()
    {
        return new Response('<h1>Contact us!</h1>');
    }
}

In this very simple example, the controller simply creates a Response object with the HTML “<h1>Contact us!</h1>”. In the controller chapter, you’ll learn how a controller can render templates, allowing your “presentation” code (i.e. anything that actually writes out HTML) to live in a separate template file. This frees up the controller to worry only about the hard stuff: interacting with the database, handling submitted data, or sending email messages.

Standalone Tools: The Symfony2 Components¶

So what is Symfony2? First, Symfony2 is a collection of over twenty independent libraries that can be used inside any PHP project. These libraries, called the Symfony2 Components, contain something useful for almost any situation, regardless of how your project is developed. To name a few:

• HttpFoundation - Contains the Request and Response classes, as well as other classes for handling sessions and file uploads;
• Routing - Powerful and fast routing system that allows you to map a specific URI (e.g. /contact) to some information about how that request should be handled (e.g. execute the contactAction() method);
• Form - A full-featured and flexible framework for creating forms and handing form submissions;
• Validator A system for creating rules about data and then validating whether or not user-submitted data follows those rules;
• ClassLoader An autoloading library that allows PHP classes to be used without needing to manually require the files containing those classes;
• Templating A toolkit for rendering templates, handling template inheritance (i.e. a template is decorated with a layout) and performing other common template tasks;
• Security - A powerful library for handling all types of security inside an application;
• Translation A framework for translating strings in your application.

Each and every one of these components is decoupled and can be used in any PHP project, regardless of whether or not you use the Symfony2 framework. Every part is made to be used if needed and replaced when necessary.

The Full Solution: The Symfony2 Framework¶

So then, what is the Symfony2 Framework? The Symfony2 Framework is a PHP library that accomplishes two distinct tasks:

1. Provides a selection of components (i.e. the Symfony2 Components) and third-party libraries (e.g. Swiftmailer for sending emails);
2. Provides sensible configuration and a “glue” library that ties all of these pieces together.

The goal of the framework is to integrate many independent tools in order to provide a consistent experience for the developer. Even the framework itself is a Symfony2 bundle (i.e. a plugin) that can be configured or replaced entirely.

Symfony2 provides a powerful set of tools for rapidly developing web applications without imposing on your application. Normal users can quickly start development by using a Symfony2 distribution, which provides a project skeleton with sensible defaults. For more advanced users, the sky is the limit.

Isolating the Presentation¶

The code can immediately gain from separating the application “logic” from the code that prepares the HTML “presentation”:

<?php
// index.php

$link = mysql_connect('localhost', 'myuser', 'mypassword');
mysql_select_db('blog_db', $link);

$result = mysql_query('SELECT id, title FROM post', $link);

$posts = array();
while ($row = mysql_fetch_assoc($result)) {
    $posts[] = $row;
}

mysql_close($link);

// include the HTML presentation code
require 'templates/list.php';

The HTML code is now stored in a separate file (templates/list.php), which is primarily an HTML file that uses a template-like PHP syntax:

<html>
    <head>
        <title>List of Posts</title>
    </head>
    <body>
        <h1>List of Posts</h1>
        <ul>
            <?php foreach ($posts as $post): ?>
            <li>
                <a href="/read?id=<?php echo $post['id'] ?>">
                    <?php echo $post['title'] ?>
                </a>
            </li>
            <?php endforeach; ?>
        </ul>
    </body>
</html>

By convention, the file that contains all of the application logic - index.php - is known as a “controller”. The term controller is a word you’ll hear a lot, regardless of the language or framework you use. It refers simply to the area of your code that processes user input and prepares the response.

In this case, our controller prepares data from the database and then includes a template to present that data. With the controller isolated, you could easily change just the template file if you needed to render the blog entries in some other format (e.g. list.json.php for JSON format).

Isolating the Application (Domain) Logic¶

So far the application contains only one page. But what if a second page needed to use the same database connection, or even the same array of blog posts? Refactor the code so that the core behavior and data-access functions of the application are isolated in a new file called model.php:

<?php
// model.php

function open_database_connection()
{
    $link = mysql_connect('localhost', 'myuser', 'mypassword');
    mysql_select_db('blog_db', $link);

    return $link;
}

function close_database_connection($link)
{
    mysql_close($link);
}

function get_all_posts()
{
    $link = open_database_connection();

    $result = mysql_query('SELECT id, title FROM post', $link);
    $posts = array();
    while ($row = mysql_fetch_assoc($result)) {
        $posts[] = $row;
    }
    close_database_connection($link);

    return $posts;
}

The controller (index.php) is now very simple:

<?php
require_once 'model.php';

$posts = get_all_posts();

require 'templates/list.php';

Now, the sole task of the controller is to get data from the model layer of the application (the model) and to call a template to render that data. This is a very simple example of the model-view-controller pattern.

Isolating the Layout¶

At this point, the application has been refactored into three distinct pieces offering various advantages and the opportunity to reuse almost everything on different pages.

The only part of the code that can’t be reused is the page layout. Fix that by creating a new layout.php file:

<!-- templates/layout.php -->
<html>
    <head>
        <title><?php echo $title ?></title>
    </head>
    <body>
        <?php echo $content ?>
    </body>
</html>

The template (templates/list.php) can now be simplified to “extend” the layout:

<?php $title = 'List of Posts' ?>

<?php ob_start() ?>
    <h1>List of Posts</h1>
    <ul>
        <?php foreach ($posts as $post): ?>
        <li>
            <a href="/read?id=<?php echo $post['id'] ?>">
                <?php echo $post['title'] ?>
            </a>
        </li>
        <?php endforeach; ?>
    </ul>
<?php $content = ob_get_clean() ?>

<?php include 'layout.php' ?>

You’ve now introduced a methodology that allows for the reuse of the layout. Unfortunately, to accomplish this, you’re forced to use a few ugly PHP functions (ob_start(), ob_get_clean()) in the template. Symfony2 uses a Templating component that allows this to be accomplished cleanly and easily. You’ll see it in action shortly.

Creating the Front Controller¶

You’re about to take a big step with the application. With one file handling all requests, you can centralize things such as security handling, configuration loading, and routing. In this application, index.php must now be smart enough to render the blog post list page or the blog post show page based on the requested URI:

<?php
// index.php

// load and initialize any global libraries
require_once 'model.php';
require_once 'controllers.php';

// route the request internally
$uri = $_SERVER['REQUEST_URI'];
if ($uri == '/index.php') {
    list_action();
} elseif ($uri == '/index.php/show' && isset($_GET['id'])) {
    show_action($_GET['id']);
} else {
    header('Status: 404 Not Found');
    echo '<html><body><h1>Page Not Found</h1></body></html>';
}

For organization, both controllers (formerly index.php and show.php) are now PHP functions and each has been moved into a separate file, controllers.php:

function list_action()
{
    $posts = get_all_posts();
    require 'templates/list.php';
}

function show_action($id)
{
    $post = get_post_by_id($id);
    require 'templates/show.php';
}

As a front controller, index.php has taken on an entirely new role, one that includes loading the core libraries and routing the application so that one of the two controllers (the list_action() and show_action() functions) is called. In reality, the front controller is beginning to look and act a lot like Symfony2’s mechanism for handling and routing requests.

By now, the application has evolved from a single PHP file into a structure that is organized and allows for code reuse. You should be happier, but far from satisfied. For example, the “routing” system is fickle, and wouldn’t recognize that the list page (/index.php) should be accessible also via / (if Apache rewrite rules were added). Also, instead of developing the blog, a lot of time is being spent working on the “architecture” of the code (e.g. routing, calling controllers, templates, etc.). More time will need to be spent to handle form submissions, input validation, logging and security. Why should you have to reinvent solutions to all these routine problems?

Add a Touch of Symfony2¶

Symfony2 to the rescue. Before actually using Symfony2, you need to make sure PHP knows how to find the Symfony2 classes. This is accomplished via an autoloader that Symfony provides. An autoloader is a tool that makes it possible to start using PHP classes without explicitly including the file containing the class.

First, download symfony and place it into a vendor/symfony/ directory. Next, create an app/bootstrap.php file. Use it to require the two files in the application and to configure the autoloader:

<?php
// bootstrap.php
require_once 'model.php';
require_once 'controllers.php';
require_once 'vendor/symfony/src/Symfony/Component/ClassLoader/UniversalClassLoader.php';

$loader = new Symfony\Component\ClassLoader\UniversalClassLoader();
$loader->registerNamespaces(array(
    'Symfony' => __DIR__.'/../vendor/symfony/src',
));

$loader->register();

This tells the autoloader where the Symfony classes are. With this, you can start using Symfony classes without using the require statement for the files that contain them.

Core to Symfony’s philosophy is the idea that an application’s main job is to interpret each request and return a response. To this end, Symfony2 provides both a Symfony\Component\HttpFoundation\Request and a Symfony\Component\HttpFoundation\Response class. These classes are object-oriented representations of the raw HTTP request being processed and the HTTP response being returned. Use them to improve the blog:

<?php
// index.php
require_once 'app/bootstrap.php';

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

$request = Request::createFromGlobals();

$uri = $request->getPathInfo();
if ($uri == '/') {
    $response = list_action();
} elseif ($uri == '/show' && $request->query->has('id')) {
    $response = show_action($request->query->get('id'));
} else {
    $html = '<html><body><h1>Page Not Found</h1></body></html>';
    $response = new Response($html, 404);
}

// echo the headers and send the response
$response->send();

The controllers are now responsible for returning a Response object. To make this easier, you can add a new render_template() function, which, incidentally, acts quite a bit like the Symfony2 templating engine:

// controllers.php
use Symfony\Component\HttpFoundation\Response;

function list_action()
{
    $posts = get_all_posts();
    $html = render_template('templates/list.php', array('posts' => $posts));

    return new Response($html);
}

function show_action($id)
{
    $post = get_post_by_id($id);
    $html = render_template('templates/show.php', array('post' => $post));

    return new Response($html);
}

// helper function to render templates
function render_template($path, array $args)
{
    extract($args);
    ob_start();
    require $path;
    $html = ob_get_clean();

    return $html;
}

By bringing in a small part of Symfony2, the application is more flexible and reliable. The Request provides a dependable way to access information about the HTTP request. Specifically, the getPathInfo() method returns a cleaned URI (always returning /show and never /index.php/show). So, even if the user goes to /index.php/show, the application is intelligent enough to route the request through show_action().

The Response object gives flexibility when constructing the HTTP response, allowing HTTP headers and content to be added via an object-oriented interface. And while the responses in this application are simple, this flexibility will pay dividends as your application grows.

The Sample Application in Symfony2¶

The blog has come a long way, but it still contains a lot of code for such a simple application. Along the way, we’ve also invented a simple routing system and a method using ob_start() and ob_get_clean() to render templates. If, for some reason, you needed to continue building this “framework” from scratch, you could at least use Symfony’s standalone Routing and Templating components, which already solve these problems.

Instead of re-solving common problems, you can let Symfony2 take care of them for you. Here’s the same sample application, now built in Symfony2:

<?php
// src/Acme/BlogBundle/Controller/BlogController.php

namespace Acme\BlogBundle\Controller;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class BlogController extends Controller
{
    public function listAction()
    {
        $posts = $this->get('doctrine')->getEntityManager()
            ->createQuery('SELECT p FROM AcmeBlogBundle:Post p')
            ->execute();

        return $this->render('AcmeBlogBundle:Blog:list.html.php', array('posts' => $posts));
    }

    public function showAction($id)
    {
        $post = $this->get('doctrine')
            ->getEntityManager()
            ->getRepository('AcmeBlogBundle:Post')
            ->find($id);

        if (!$post) {
            // cause the 404 page not found to be displayed
            throw $this->createNotFoundException();
        }

        return $this->render('AcmeBlogBundle:Blog:show.html.php', array('post' => $post));
    }
}

The two controllers are still lightweight. Each uses the Doctrine ORM library to retrieve objects from the database and the Templating component to render a template and return a Response object. The list template is now quite a bit simpler:

<!-- src/Acme/BlogBundle/Resources/views/Blog/list.html.php -->
<?php $view->extend('::layout.html.php') ?>

<?php $view['slots']->set('title', 'List of Posts') ?>

<h1>List of Posts</h1>
<ul>
    <?php foreach ($posts as $post): ?>
    <li>
        <a href="<?php echo $view['router']->generate('blog_show', array('id' => $post->getId())) ?>">
            <?php echo $post->getTitle() ?>
        </a>
    </li>
    <?php endforeach; ?>
</ul>

The layout is nearly identical:

<!-- app/Resources/views/layout.html.php -->
<html>
    <head>
        <title><?php echo $view['slots']->output('title', 'Default title') ?></title>
    </head>
    <body>
        <?php echo $view['slots']->output('_content') ?>
    </body>
</html>

When Symfony2’s engine (called the Kernel) boots up, it needs a map so that it knows which controllers to execute based on the request information. A routing configuration map provides this information in a readable format:

# app/config/routing.yml
blog_list:
    pattern:  /blog
    defaults: { _controller: AcmeBlogBundle:Blog:list }

blog_show:
    pattern:  /blog/show/{id}
    defaults: { _controller: AcmeBlogBundle:Blog:show }

Now that Symfony2 is handling all the mundane tasks, the front controller is dead simple. And since it does so little, you’ll never have to touch it once it’s created (and if you use a Symfony2 distribution, you won’t even need to create it!):

<?php
// web/app.php
require_once __DIR__.'/../app/bootstrap.php';
require_once __DIR__.'/../app/AppKernel.php';

use Symfony\Component\HttpFoundation\Request;

$kernel = new AppKernel('prod', false);
$kernel->handle(Request::createFromGlobals())->send();

The front controller’s only job is to initialize Symfony2’s engine (Kernel) and pass it a Request object to handle. Symfony2’s core then uses the routing map to determine which controller to call. Just like before, the controller method is responsible for returning the final Response object. There’s really not much else to it.

For a visual representation of how Symfony2 handles each request, see the request flow diagram.

Where Symfony2 Delivers¶

In the upcoming chapters, you’ll learn more about how each piece of Symfony works and the recommended organization of a project. For now, let’s see how migrating the blog from flat PHP to Symfony2 has improved life:

• Your application now has clear and consistently organized code (though Symfony doesn’t force you into this). This promotes reusability and allows for new developers to be productive in your project more quickly.
• 100% of the code you write is for your application. You don’t need to develop or maintain low-level utilities such as autoloading, routing, or rendering controllers.
• Symfony2 gives you access to open source tools such as Doctrine and the Templating, Security, Form, Validation and Translation components (to name a few).
• The application now enjoys fully-flexible URLs thanks to the Routing component.
• Symfony2’s HTTP-centric architecture gives you access to powerful tools such as HTTP caching powered by Symfony2’s internal HTTP cache or more powerful tools such as Varnish. This is covered in a later chapter all about caching.

And perhaps best of all, by using Symfony2, you now have access to a whole set of high-quality open source tools developed by the Symfony2 community! A good selection of Symfony2 community tools can be found on KnpBundles.com.

Updating Vendors¶

Finally, if you downloaded the archive “without vendors”, install the vendors by running the following command from the command line:

php bin/vendors install

This command downloads all of the necessary vendor libraries - including Symfony itself - into the vendor/ directory. For more information on how third-party vendor libraries are managed inside Symfony2, see “cookbook-managing-vendor-libraries”.

Configuration and Setup¶

At this point, all of the needed third-party libraries now live in the vendor/ directory. You also have a default application setup in app/ and some sample code inside the src/ directory.

Symfony2 comes with a visual server configuration tester to help make sure your Web server and PHP are configured to use Symfony. Use the following URL to check your configuration:

http://localhost/Symfony/web/config.php

If there are any issues, correct them now before moving on.

rm -rf app/cache/*
rm -rf app/logs/*

sudo chmod +a "www-data allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs
sudo chmod +a "`whoami` allow delete,write,append,file_inherit,directory_inherit" app/cache app/logs

sudo setfacl -R -m u:www-data:rwx -m u:`whoami`:rwx app/cache app/logs
sudo setfacl -dR -m u:www-data:rwx -m u:`whoami`:rwx app/cache app/logs

umask(0002); // This will let the permissions be 0775

// or

umask(0000); // This will let the permissions be 0777

When everything is fine, click on “Go to the Welcome page” to request your first “real” Symfony2 webpage:

http://localhost/Symfony/web/app_dev.php/

Symfony2 should welcome and congratulate you for your hard work so far!

Ignoring the vendor/ Directory¶

If you’ve downloaded the archive without vendors, you can safely ignore the entire vendor/ directory and not commit it to source control. With Git, this is done by creating and adding the following to a .gitignore file:

vendor/

Now, the vendor directory won’t be committed to source control. This is fine (actually, it’s great!) because when someone else clones or checks out the project, he/she can simply run the php bin/vendors install script to download all the necessary vendor libraries.

Before you begin: Create the Bundle¶

Before you begin, you’ll need to create a bundle. In Symfony2, a bundle is like a plugin, except that all of the code in your application will live inside a bundle.

A bundle is nothing more than a directory that houses everything related to a specific feature, including PHP classes, configuration, and even stylesheets and Javascript files (see The Bundle System).

To create a bundle called AcmeHelloBundle (a play bundle that you’ll build in this chapter), run the following command and follow the on-screen instructions (use all of the default options):

php app/console generate:bundle --namespace=Acme/HelloBundle --format=yml

Behind the scenes, a directory is created for the bundle at src/Acme/HelloBundle. A line is also automatically added to the app/AppKernel.php file so that the bundle is registered with the kernel:

// app/AppKernel.php
public function registerBundles()
{
    $bundles = array(
        // ...
        new Acme\HelloBundle\AcmeHelloBundle(),
    );
    // ...

    return $bundles;
}

Now that you have a bundle setup, you can begin building your application inside the bundle.

Step 1: Create the Route¶

By default, the routing configuration file in a Symfony2 application is located at app/config/routing.yml. Like all configuration in Symfony2, you can also choose to use XML or PHP out of the box to configure routes.

If you look at the main routing file, you’ll see that Symfony already added an entry when you generated the AcmeHelloBundle:

This entry is pretty basic: it tells Symfony to load routing configuration from the Resources/config/routing.yml file that lives inside the AcmeHelloBundle. This means that you place routing configuration directly in app/config/routing.yml or organize your routes throughout your application, and import them from here.

Now that the routing.yml file from the bundle is being imported, add the new route that defines the URL of the page that you’re about to create:

The routing consists of two basic pieces: the pattern, which is the URL that this route will match, and a defaults array, which specifies the controller that should be executed. The placeholder syntax in the pattern ({name}) is a wildcard. It means that /hello/Ryan, /hello/Fabien or any other similar URL will match this route. The {name} placeholder parameter will also be passed to the controller so that you can use its value to personally greet the user.

Step 2: Create the Controller¶

When a URL such as /hello/Ryan is handled by the application, the hello route is matched and the AcmeHelloBundle:Hello:index controller is executed by the framework. The second step of the page-creation process is to create that controller.

The controller - AcmeHelloBundle:Hello:index is the logical name of the controller, and it maps to the indexAction method of a PHP class called Acme\HelloBundle\Controller\Hello. Start by creating this file inside your AcmeHelloBundle:

// src/Acme/HelloBundle/Controller/HelloController.php
namespace Acme\HelloBundle\Controller;

use Symfony\Component\HttpFoundation\Response;

class HelloController
{
}

In reality, the controller is nothing more than a PHP method that you create and Symfony executes. This is where your code uses information from the request to build and prepare the resource being requested. Except in some advanced cases, the end product of a controller is always the same: a Symfony2 Response object.

Create the indexAction method that Symfony will execute when the hello route is matched:

// src/Acme/HelloBundle/Controller/HelloController.php

// ...
class HelloController
{
    public function indexAction($name)
    {
        return new Response('<html><body>Hello '.$name.'!</body></html>');
    }
}

The controller is simple: it creates a new Response object, whose first argument is the content that should be used in the response (a small HTML page in this example).

Congratulations! After creating only a route and a controller, you already have a fully-functional page! If you’ve setup everything correctly, your application should greet you:

http://localhost/app_dev.php/hello/Ryan

http://localhost/app.php/hello/Ryan

php app/console cache:clear --env=prod --no-debug

An optional, but common, third step in the process is to create a template.

Optional Step 3: Create the Template¶

Templates allows you to move all of the presentation (e.g. HTML code) into a separate file and reuse different portions of the page layout. Instead of writing the HTML inside the controller, render a template instead:

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

// src/Acme/HelloBundle/Controller/HelloController.php
namespace Acme\HelloBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class HelloController extends Controller
{
    public function indexAction($name)
    {
        return $this->render('AcmeHelloBundle:Hello:index.html.twig', array('name' => $name));

        // render a PHP template instead
        // return $this->render('AcmeHelloBundle:Hello:index.html.php', array('name' => $name));
    }
}

The render() method creates a Response object filled with the content of the given, rendered template. Like any other controller, you will ultimately return that Response object.

Notice that there are two different examples for rendering the template. By default, Symfony2 supports two different templating languages: classic PHP templates and the succinct but powerful Twig templates. Don’t be alarmed - you’re free to choose either or even both in the same project.

The controller renders the AcmeHelloBundle:Hello:index.html.twig template, which uses the following naming convention:

BundleName:ControllerName:TemplateName

This is the logical name of the template, which is mapped to a physical location using the following convention.

/path/to/BundleName/Resources/views/ControllerName/TemplateName

In this case, AcmeHelloBundle is the bundle name, Hello is the controller, and index.html.twig the template:

Let’s step through the Twig template line-by-line:

• line 2: The extends token defines a parent template. The template explicitly defines a layout file inside of which it will be placed.
• line 4: The block token says that everything inside should be placed inside a block called body. As you’ll see, it’s the responsibility of the parent template (base.html.twig) to ultimately render the block called body.

The parent template, ::base.html.twig, is missing both the BundleName and ControllerName portions of its name (hence the double colon (::) at the beginning). This means that the template lives outside of the bundles and in the app directory:

The base template file defines the HTML layout and renders the body block that you defined in the index.html.twig template. It also renders a title block, which you could choose to define in the index.html.twig template. Since you did not define the title block in the child template, it defaults to “Welcome!”.

Templates are a powerful way to render and organize the content for your page. A template can render anything, from HTML markup, to CSS code, or anything else that the controller may need to return.

In the lifecycle of handling a request, the templating engine is simply an optional tool. Recall that the goal of each controller is to return a Response object. Templates are a powerful, but optional, tool for creating the content for that Response object.

The Web Directory¶

The web root directory is the home of all public and static files including images, stylesheets, and JavaScript files. It is also where each front controller lives:

// web/app.php
require_once __DIR__.'/../app/bootstrap.php.cache';
require_once __DIR__.'/../app/AppKernel.php';

use Symfony\Component\HttpFoundation\Request;

$kernel = new AppKernel('prod', false);
$kernel->loadClassCache();
$kernel->handle(Request::createFromGlobals())->send();

The front controller file (app.php in this example) is the actual PHP file that’s executed when using a Symfony2 application and its job is to use a Kernel class, AppKernel, to bootstrap the application.

http://localhost/app.php/hello/Ryan

http://localhost/hello/Ryan

Though front controllers are essential in handling every request, you’ll rarely need to modify or even think about them. We’ll mention them again briefly in the Environments section.

The Application (app) Directory¶

As you saw in the front controller, the AppKernel class is the main entry point of the application and is responsible for all configuration. As such, it is stored in the app/ directory.

This class must implement two methods that define everything that Symfony needs to know about your application. You don’t even need to worry about these methods when starting - Symfony fills them in for you with sensible defaults.

• registerBundles(): Returns an array of all bundles needed to run the application (see The Bundle System);
• registerContainerConfiguration(): Loads the main application configuration resource file (see the Application Configuration section).

In day-to-day development, you’ll mostly use the app/ directory to modify configuration and routing files in the app/config/ directory (see Application Configuration). It also contains the application cache directory (app/cache), a log directory (app/logs) and a directory for application-level resource files, such as templates (app/Resources). You’ll learn more about each of these directories in later chapters.

Class Name:
    Acme\HelloBundle\Controller\HelloController
Path:
    src/Acme/HelloBundle/Controller/HelloController.php

The Source (src) Directory¶

Put simply, the src/ directory contains all of the actual code (PHP code, templates, configuration files, stylesheets, etc) that drives your application. When developing, the vast majority of your work will be done inside one or more bundles that you create in this directory.

But what exactly is a bundle?

Creating a Bundle¶

The Symfony Standard Edition comes with a handy task that creates a fully-functional bundle for you. Of course, creating a bundle by hand is pretty easy as well.

To show you how simple the bundle system is, create a new bundle called AcmeTestBundle and enable it.

Start by creating a src/Acme/TestBundle/ directory and adding a new file called AcmeTestBundle.php:

// src/Acme/TestBundle/AcmeTestBundle.php
namespace Acme\TestBundle;

use Symfony\Component\HttpKernel\Bundle\Bundle;

class AcmeTestBundle extends Bundle
{
}

This empty class is the only piece you need to create the new bundle. Though commonly empty, this class is powerful and can be used to customize the behavior of the bundle.

Now that you’ve created the bundle, enable it via the AppKernel class:

// app/AppKernel.php
public function registerBundles()
{
    $bundles = array(
        // ...

        // register your bundles
        new Acme\TestBundle\AcmeTestBundle(),
    );
    // ...

    return $bundles;
}

And while it doesn’t do anything yet, AcmeTestBundle is now ready to be used.

And as easy as this is, Symfony also provides a command-line interface for generating a basic bundle skeleton:

php app/console generate:bundle --namespace=Acme/TestBundle

The bundle skeleton generates with a basic controller, template and routing resource that can be customized. You’ll learn more about Symfony2’s command-line tools later.

Bundle Directory Structure¶

The directory structure of a bundle is simple and flexible. By default, the bundle system follows a set of conventions that help to keep code consistent between all Symfony2 bundles. Take a look at AcmeHelloBundle, as it contains some of the most common elements of a bundle:

• Controller/ contains the controllers of the bundle (e.g. HelloController.php);
• Resources/config/ houses configuration, including routing configuration (e.g. routing.yml);
• Resources/views/ holds templates organized by controller name (e.g. Hello/index.html.twig);
• Resources/public/ contains web assets (images, stylesheets, etc) and is copied or symbolically linked into the project web/ directory via the assets:install console command;
• Tests/ holds all tests for the bundle.

A bundle can be as small or large as the feature it implements. It contains only the files you need and nothing else.

As you move through the book, you’ll learn how to persist objects to a database, create and validate forms, create translations for your application, write tests and much more. Each of these has their own place and role within the bundle.

Default Configuration Dump¶

You can dump the default configuration for a bundle in yaml to the console using the config:dump-reference command. Here is an example of dumping the default FrameworkBundle configuration:

app/console config:dump-reference FrameworkBundle

Environment Configuration¶

The AppKernel class is responsible for actually loading the configuration file of your choice:

// app/AppKernel.php
public function registerContainerConfiguration(LoaderInterface $loader)
{
    $loader->load(__DIR__.'/config/config_'.$this->getEnvironment().'.yml');
}

You already know that the .yml extension can be changed to .xml or .php if you prefer to use either XML or PHP to write your configuration. Notice also that each environment loads its own configuration file. Consider the configuration file for the dev environment.

The imports key is similar to a PHP include statement and guarantees that the main configuration file (config.yml) is loaded first. The rest of the file tweaks the default configuration for increased logging and other settings conducive to a development environment.

Both the prod and test environments follow the same model: each environment imports the base configuration file and then modifies its configuration values to fit the needs of the specific environment. This is just a convention, but one that allows you to reuse most of your configuration and customize just pieces of it between environments.

Route Parameters as Controller Arguments¶

You already know that the _controller parameter AcmeHelloBundle:Hello:index refers to a HelloController::indexAction() method that lives inside the AcmeHelloBundle bundle. What’s more interesting is the arguments that are passed to that method:

<?php
// src/Acme/HelloBundle/Controller/HelloController.php

namespace Acme\HelloBundle\Controller;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class HelloController extends Controller
{
    public function indexAction($name)
    {
      // ...
    }
}

The controller has a single argument, $name, which corresponds to the {name} parameter from the matched route (ryan in our example). In fact, when executing your controller, Symfony2 matches each argument of the controller with a parameter from the matched route. Take the following example:

The controller for this can take several arguments:

public function indexAction($first_name, $last_name, $color)
{
    // ...
}

Notice that both placeholder variables ({first_name}, {last_name}) as well as the default color variable are available as arguments in the controller. When a route is matched, the placeholder variables are merged with the defaults to make one array that’s available to your controller.

Mapping route parameters to controller arguments is easy and flexible. Keep the following guidelines in mind while you develop.

• The order of the controller arguments does not matter

  Symfony is able to match the parameter names from the route to the variable names in the controller method’s signature. In other words, it realizes that the {last_name} parameter matches up with the $last_name argument. The arguments of the controller could be totally reordered and still work perfectly:

  public function indexAction($last_name, $color, $first_name)
  {
      // ..
  }
  

• Each required controller argument must match up with a routing parameter

  The following would throw a RuntimeException because there is no foo parameter defined in the route:

  public function indexAction($first_name, $last_name, $color, $foo)
  {
      // ..
  }
  

  Making the argument optional, however, is perfectly ok. The following example would not throw an exception:

  public function indexAction($first_name, $last_name, $color, $foo = 'bar')
  {
      // ..
  }
  

• Not all routing parameters need to be arguments on your controller

  If, for example, the last_name weren’t important for your controller, you could omit it entirely:

  public function indexAction($first_name, $color)
  {
      // ..
  }
  

The Request as a Controller Argument¶

For convenience, you can also have Symfony pass you the Request object as an argument to your controller. This is especially convenient when you’re working with forms, for example:

use Symfony\Component\HttpFoundation\Request;

public function updateAction(Request $request)
{
    $form = $this->createForm(...);

    $form->bindRequest($request);
    // ...
}

Redirecting¶

If you want to redirect the user to another page, use the redirect() method:

public function indexAction()
{
    return $this->redirect($this->generateUrl('homepage'));
}

The generateUrl() method is just a helper function that generates the URL for a given route. For more information, see the Routing chapter.

By default, the redirect() method performs a 302 (temporary) redirect. To perform a 301 (permanent) redirect, modify the second argument:

public function indexAction()
{
    return $this->redirect($this->generateUrl('homepage'), 301);
}

use Symfony\Component\HttpFoundation\RedirectResponse;

return new RedirectResponse($this->generateUrl('homepage'));

Forwarding¶

You can also easily forward to another controller internally with the forward() method. Instead of redirecting the user’s browser, it makes an internal sub-request, and calls the specified controller. The forward() method returns the Response object that’s returned from that controller:

public function indexAction($name)
{
    $response = $this->forward('AcmeHelloBundle:Hello:fancy', array(
        'name'  => $name,
        'color' => 'green'
    ));

    // further modify the response or return it directly

    return $response;
}

Notice that the forward() method uses the same string representation of the controller used in the routing configuration. In this case, the target controller class will be HelloController inside some AcmeHelloBundle. The array passed to the method becomes the arguments on the resulting controller. This same interface is used when embedding controllers into templates (see Embedding Controllers). The target controller method should look something like the following:

public function fancyAction($name, $color)
{
    // ... create and return a Response object
}

And just like when creating a controller for a route, the order of the arguments to fancyAction doesn’t matter. Symfony2 matches the index key names (e.g. name) with the method argument names (e.g. $name). If you change the order of the arguments, Symfony2 will still pass the correct value to each variable.

$httpKernel = $this->container->get('http_kernel');
$response = $httpKernel->forward('AcmeHelloBundle:Hello:fancy', array(
    'name'  => $name,
    'color' => 'green',
));

Rendering Templates¶

Though not a requirement, most controllers will ultimately render a template that’s responsible for generating the HTML (or other format) for the controller. The renderView() method renders a template and returns its content. The content from the template can be used to create a Response object:

$content = $this->renderView('AcmeHelloBundle:Hello:index.html.twig', array('name' => $name));

return new Response($content);

This can even be done in just one step with the render() method, which returns a Response object containing the content from the template:

return $this->render('AcmeHelloBundle:Hello:index.html.twig', array('name' => $name));

In both cases, the Resources/views/Hello/index.html.twig template inside the AcmeHelloBundle will be rendered.

The Symfony templating engine is explained in great detail in the Templating chapter.

$templating = $this->get('templating');
$content = $templating->render('AcmeHelloBundle:Hello:index.html.twig', array('name' => $name));

Accessing other Services¶

When extending the base controller class, you can access any Symfony2 service via the get() method. Here are several common services you might need:

$request = $this->getRequest();

$templating = $this->get('templating');

$router = $this->get('router');

$mailer = $this->get('mailer');

There are countless other services available and you are encouraged to define your own. To list all available services, use the container:debug console command:

php app/console container:debug

For more information, see the Service Container chapter.

Flash Messages¶

You can also store small messages that will be stored on the user’s session for exactly one additional request. This is useful when processing a form: you want to redirect and have a special message shown on the next request. These types of messages are called “flash” messages.

For example, imagine you’re processing a form submit:

public function updateAction()
{
    $form = $this->createForm(...);

    $form->bindRequest($this->getRequest());
    if ($form->isValid()) {
        // do some sort of processing

        $this->get('session')->setFlash('notice', 'Your changes were saved!');

        return $this->redirect($this->generateUrl(...));
    }

    return $this->render(...);
}

After processing the request, the controller sets a notice flash message and then redirects. The name (notice) isn’t significant - it’s just what you’re using to identify the type of the message.

In the template of the next action, the following code could be used to render the notice message:

By design, flash messages are meant to live for exactly one request (they’re “gone in a flash”). They’re designed to be used across redirects exactly as you’ve done in this example.

Basic Route Configuration¶

Defining a route is easy, and a typical application will have lots of routes. A basic route consists of just two parts: the pattern to match and a defaults array:

This route matches the homepage (/) and maps it to the AcmeDemoBundle:Main:homepage controller. The _controller string is translated by Symfony2 into an actual PHP function and executed. That process will be explained shortly in the Controller Naming Pattern section.

Routing with Placeholders¶

Of course the routing system supports much more interesting routes. Many routes will contain one or more named “wildcard” placeholders:

The pattern will match anything that looks like /blog/*. Even better, the value matching the {slug} placeholder will be available inside your controller. In other words, if the URL is /blog/hello-world, a $slug variable, with a value of hello-world, will be available in the controller. This can be used, for example, to load the blog post matching that string.

The pattern will not, however, match simply /blog. That’s because, by default, all placeholders are required. This can be changed by adding a placeholder value to the defaults array.

Required and Optional Placeholders¶

To make things more exciting, add a new route that displays a list of all the available blog posts for this imaginary blog application:

So far, this route is as simple as possible - it contains no placeholders and will only match the exact URL /blog. But what if you need this route to support pagination, where /blog/2 displays the second page of blog entries? Update the route to have a new {page} placeholder:

Like the {slug} placeholder before, the value matching {page} will be available inside your controller. Its value can be used to determine which set of blog posts to display for the given page.

But hold on! Since placeholders are required by default, this route will no longer match on simply /blog. Instead, to see page 1 of the blog, you’d need to use the URL /blog/1! Since that’s no way for a rich web app to behave, modify the route to make the {page} parameter optional. This is done by including it in the defaults collection:

By adding page to the defaults key, the {page} placeholder is no longer required. The URL /blog will match this route and the value of the page parameter will be set to 1. The URL /blog/2 will also match, giving the page parameter a value of 2. Perfect.

Adding Requirements¶

Take a quick look at the routes that have been created so far:

Can you spot the problem? Notice that both routes have patterns that match URL’s that look like /blog/*. The Symfony router will always choose the first matching route it finds. In other words, the blog_show route will never be matched. Instead, a URL like /blog/my-blog-post will match the first route (blog) and return a nonsense value of my-blog-post to the {page} parameter.

The answer to the problem is to add route requirements. The routes in this example would work perfectly if the /blog/{page} pattern only matched URLs where the {page} portion is an integer. Fortunately, regular expression requirements can easily be added for each parameter. For example:

The \d+ requirement is a regular expression that says that the value of the {page} parameter must be a digit (i.e. a number). The blog route will still match on a URL like /blog/2 (because 2 is a number), but it will no longer match a URL like /blog/my-blog-post (because my-blog-post is not a number).

As a result, a URL like /blog/my-blog-post will now properly match the blog_show route.

Since the parameter requirements are regular expressions, the complexity and flexibility of each requirement is entirely up to you. Suppose the homepage of your application is available in two different languages, based on the URL:

For incoming requests, the {culture} portion of the URL is matched against the regular expression (en|fr).

Adding HTTP Method Requirements¶

In addition to the URL, you can also match on the method of the incoming request (i.e. GET, HEAD, POST, PUT, DELETE). Suppose you have a contact form with two controllers - one for displaying the form (on a GET request) and one for processing the form when it’s submitted (on a POST request). This can be accomplished with the following route configuration:

Despite the fact that these two routes have identical patterns (/contact), the first route will match only GET requests and the second route will match only POST requests. This means that you can display the form and submit the form via the same URL, while using distinct controllers for the two actions.

Like the other requirements, the _method requirement is parsed as a regular expression. To match GET or POST requests, you can use GET|POST.

Advanced Routing Example¶

At this point, you have everything you need to create a powerful routing structure in Symfony. The following is an example of just how flexible the routing system can be:

As you’ve seen, this route will only match if the {culture} portion of the URL is either en or fr and if the {year} is a number. This route also shows how you can use a period between placeholders instead of a slash. URLs matching this route might look like:

• /articles/en/2010/my-post
• /articles/fr/2010/my-post.rss

Special Routing Parameters¶

As you’ve seen, each routing parameter or default value is eventually available as an argument in the controller method. Additionally, there are three parameters that are special: each adds a unique piece of functionality inside your application:

• _controller: As you’ve seen, this parameter is used to determine which controller is executed when the route is matched;
• _format: Used to set the request format (read more);
• _locale: Used to set the locale on the request (read more);

Prefixing Imported Routes¶

You can also choose to provide a “prefix” for the imported routes. For example, suppose you want the acme_hello route to have a final pattern of /admin/hello/{name} instead of simply /hello/{name}:

The string /admin will now be prepended to the pattern of each route loaded from the new routing resource.

Generating Absolute URLs¶

By default, the router will generate relative URLs (e.g. /blog). To generate an absolute URL, simply pass true to the third argument of the generate() method:

$router->generate('blog_show', array('slug' => 'my-blog-post'), true);
// http://www.example.com/blog/my-blog-post

$request->headers->set('HOST', 'www.example.com');

Generating URLs with Query Strings¶

The generate method takes an array of wildcard values to generate the URI. But if you pass extra ones, they will be added to the URI as a query string:

$router->generate('blog', array('page' => 2, 'category' => 'Symfony'));
// /blog/2?category=Symfony

Generating URLs from a template¶

The most common place to generate a URL is from within a template when linking between pages in your application. This is done just as before, but using a template helper function:

Absolute URLs can also be generated.

Twig Template Caching¶

Twig is fast. Each Twig template is compiled down to a native PHP class that is rendered at runtime. The compiled classes are located in the app/cache/{environment}/twig directory (where {environment} is the environment, such as dev or prod) and in some cases can be useful while debugging. See Environments for more information on environments.

When debug mode is enabled (common in the dev environment), a Twig template will be automatically recompiled when changes are made to it. This means that during development you can happily make changes to a Twig template and instantly see the changes without needing to worry about clearing any cache.

When debug mode is disabled (common in the prod environment), however, you must clear the Twig cache directory so that the Twig templates will regenerate. Remember to do this when deploying your application.

Template Suffix¶

The bundle:controller:template format of each template specifies where the template file is located. Every template name also has two extensions that specify the format and engine for that template.

• AcmeBlogBundle:Blog:index.html.twig - HTML format, Twig engine
• AcmeBlogBundle:Blog:index.html.php - HTML format, PHP engine
• AcmeBlogBundle:Blog:index.css.twig - CSS format, Twig engine

By default, any Symfony2 template can be written in either Twig or PHP, and the last part of the extension (e.g. .twig or .php) specifies which of these two engines should be used. The first part of the extension, (e.g. .html, .css, etc) is the final format that the template will generate. Unlike the engine, which determines how Symfony2 parses the template, this is simply an organizational tactic used in case the same resource needs to be rendered as HTML (index.html.twig), XML (index.xml.twig), or any other format. For more information, read the Debugging section.