Symfony Documentation¶

Installing Symfony¶

In the past, Symfony had to be installed manually for each new project. Now you can use the Symfony Installer, which has to be installed the very first time you use Symfony on a computer.

On Linux and Mac OS X systems, execute the following console commands:

$ curl -LsS http://symfony.com/installer > symfony.phar
$ sudo mv symfony.phar /usr/local/bin/symfony
$ chmod a+x /usr/local/bin/symfony

$ php -r "readfile('http://symfony.com/installer');" > symfony.phar
$ sudo mv symfony.phar /usr/local/bin/symfony
$ chmod a+x /usr/local/bin/symfony

After installing the Symfony installer, you’ll have to open a new console window to be able to execute the new symfony command:

$ symfony

On Windows systems, execute the following console command:

c:\> php -r "readfile('http://symfony.com/installer');" > symfony.phar

This command downloads a file called symfony.phar which contains the Symfony installer. Save or move that file to the directory where you create the Symfony projects and then, execute the Symfony installer right away with this command:

c:\> php symfony.phar

Creating Your First Symfony Project¶

Once the Symfony Installer is set up, use the new command to create new Symfony projects. Let’s create a new project called myproject:

# Linux and Mac OS X
$ symfony new myproject

# Windows
c:\> php symfony.phar new myproject

This command downloads the latest Symfony stable version and creates an empty project in the myproject/ directory so you can start developing your application right away.

Running Symfony¶

This tutorial leverages the internal web server provided by PHP to run Symfony applications. Therefore, running a Symfony application is a matter of browsing the project directory and executing this command:

$ cd myproject/
$ php app/console server:run

Open your browser and access the http://localhost:8000 URL to see the Welcome page of Symfony:

Congratulations! Your first Symfony project is up and running!

When you are finished working on your Symfony application, you can stop the server with the server:stop command:

$ php app/console server:stop

Understanding the Fundamentals¶

One of the main goals of a framework is to keep your code organized and to allow your application to evolve easily over time by avoiding the mixing 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/) to the resource associated with it (the Welcome to Symfony! 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/ 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.

namespace AppBundle\Controller;

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class DefaultController extends Controller
{
    /**
     * @Route("/", name="homepage")
     */
    public function indexAction()
    {
        return $this->render('default/index.html.twig');
    }
}

// src/AppBundle/Controller/DefaultController.php
namespace AppBundle\Controller;

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class DefaultController extends Controller
{
    /**
     * @Route("/", name="homepage")
     */
    public function indexAction()
    {
        return $this->render('default/index.html.twig');
    }
}

return $this->render('default/index.html.twig');

{# app/Resources/views/default/index.html.twig #}
{% extends 'base.html.twig' %}

{% block body %}
    <h1>Welcome to Symfony!</h1>
{% endblock %}

Working with Environments¶

Now that you have a better understanding of how Symfony works, take a closer look at the bottom of any Symfony rendered page. You should notice a small bar with the Symfony logo. This is the “Web Debug Toolbar”, and it is a Symfony developer’s best friend!

But what you see initially is only the tip of the iceberg; click on any of the bar sections to open the profiler and get much more detailed information about the request, the query parameters, security details, and database queries:

This tool provides so much internal information about your application that you may be worried about your visitors accessing sensible information. Symfony is aware of this issue and for that reason, it won’t display this bar when your application is running in the production server.

How does Symfony know whether your application is running locally or on a production server? Keep reading to discover the concept of execution environments.

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

web_profiler:
    toolbar: true
    intercept_redirects: false

Final Thoughts¶

Congratulations! You’ve had your first taste of Symfony code. That wasn’t so hard, was it? There’s a lot more to explore, but you should already see how Symfony makes it really easy to implement web sites better and faster. If you are eager to learn more about Symfony, dive into the next section: “The View”.

Getting familiar with Twig¶

The official Twig documentation is the best resource to learn everything about this template engine. This section just gives you a quick overview of its main concepts.

A Twig template is a text file that can generate any type of content (HTML, CSS, JavaScript, XML, CSV, LaTeX, etc.) Twig elements are separated from the rest of the template contents using any of these delimiters:

{{ ... }}

Prints the content of a variable or the result of evaluating an expression;

{% ... %}

Controls the logic of the template; it is used for example to execute for loops and if statements.

{# ... #}

Allows including comments inside templates. Contrary to HTML comments, they aren’t included in the rendered template.

Below is a minimal template that illustrates a few basics, using two variables page_title and navigation, which would be passed into the template:

<!DOCTYPE html>
<html>
    <head>
        <title>{{ page_title }}</title>
    </head>
    <body>
        <h1>{{ page_title }}</h1>

        <ul id="navigation">
            {% for item in navigation %}
                <li><a href="{{ item.url }}">{{ item.label }}</a></li>
            {% endfor %}
        </ul>
    </body>
</html>

To render a template in Symfony, use the render method from within a controller. If the template needs variables to generate its contents, pass them as an array using the second optional argument:

$this->render('default/index.html.twig', array(
    'variable_name' => 'variable_value',
));

Variables passed to a template can be strings, arrays or even objects. Twig abstracts the difference between them and lets you access “attributes” of a variable with the dot (.) notation. The following code listing shows how to display the content of a variable passed by the controller depending on its type:

{# 1. Simple variables #}
{# $this->render('template.html.twig', array('name' => 'Fabien') ) #}
{{ name }}

{# 2. Arrays #}
{# $this->render('template.html.twig', array('user' => array('name' => 'Fabien')) ) #}
{{ user.name }}

{# alternative syntax for arrays #}
{{ user['name'] }}

{# 3. Objects #}
{# $this->render('template.html.twig', array('user' => new User('Fabien')) ) #}
{{ user.name }}
{{ user.getName }}

{# alternative syntax for objects #}
{{ user.name() }}
{{ user.getName() }}

Decorating Templates¶

More often than not, templates in a project share common elements, like the well-known header and footer. Twig solves this problem elegantly with a concept called “template inheritance”. This feature allows you to build a base template that contains all the common elements of your site and defines “blocks” of contents that child templates can override.

The index.html.twig template uses the extends tag to indicate that it inherits from the base.html.twig template:

{# app/Resources/views/default/index.html.twig #}
{% extends 'base.html.twig' %}

{% block body %}
    <h1>Welcome to Symfony!</h1>
{% endblock %}

Open the app/Resources/views/base.html.twig file that corresponds to the base.html.twig template and you’ll find the following Twig code:

{# app/Resources/views/base.html.twig #}
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>{% block title %}Welcome!{% endblock %}</title>
        {% block stylesheets %}{% endblock %}
        <link rel="icon" type="image/x-icon" href="{{ asset('favicon.ico') }}" />
    </head>
    <body>
        {% block body %}{% endblock %}
        {% block javascripts %}{% endblock %}
    </body>
</html>

The {% block %} tags tell the template engine that a child template may override those portions of the template. In this example, the index.html.twig template overrides the body block, but not the title block, which will display the default content defined in the base.html.twig template.

Using Tags, Filters, and Functions¶

One of the best features of Twig is its extensibility via tags, filters, and functions. Take a look at the following sample template that uses filters extensively to modify the information before displaying it to the user:

<h1>{{ article.title|capitalize }}</h1>

<p>{{ article.content|striptags|slice(0, 255) }} ...</p>

<p>Tags: {{ article.tags|sort|join(", ") }}</p>

<p>Activate your account before {{ 'next Monday'|date('M j, Y') }}</p>

Don’t forget to check out the official Twig documentation to learn everything about filters, functions and tags.

{# app/Resources/views/ads/banner.html.twig #}
<div id="ad-banner">
    ...
</div>

{# app/Resources/views/default/index.html.twig #}
{% extends 'base.html.twig' %}

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

    {{ include('ads/banner.html.twig') }}
{% endblock %}

{# app/Resources/views/index.html.twig #}
{{ render(controller('AppBundle:Default:topArticles')) }}

// src/AppBundle/Controller/DefaultController.php

class DefaultController extends Controller
{
    public function topArticlesAction()
    {
        // look for the most popular articles in the database
        $articles = ...;

        return $this->render('default/top_articles.html.twig', array(
            'articles' => $articles,
        ));
    }

    // ...
}

<a href="{{ path('homepage') }}">Return to homepage</a>

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

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

Final Thoughts¶

Twig is simple yet powerful. Thanks to layouts, blocks, templates and action inclusions, it is very easy to organize your templates in a logical and extensible way.

You have only been working with Symfony for about 20 minutes, but you can already do pretty amazing stuff with it. That’s the power of Symfony. Learning the basics is easy, and you will soon learn that this simplicity is hidden under a very flexible architecture.

But I’m getting ahead of myself. First, you need to learn more about the controller and that’s exactly the topic of the next part of this tutorial. Ready for another 10 minutes with Symfony?

Returning Raw Responses¶

Symfony defines itself as a Request-Response framework. When the user makes a request to your application, Symfony creates a Request object to encapsulate all the information related to that request. Similarly, the result of executing any action of any controller is the creation of a Response object which Symfony uses to generate the HTML content returned to the user.

So far, all the actions shown in this tutorial used the $this->render() shortcut to return a rendered response as result. In case you need it, you can also create a raw Response object to return any text content:

// src/AppBundle/Controller/DefaultController.php
namespace AppBundle\Controller;

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Response;

class DefaultController extends Controller
{
    /**
     * @Route("/", name="homepage")
     */
    public function indexAction()
    {
        return new Response('Welcome to Symfony!');
    }
}

Route Parameters¶

Most of the time, the URLs of applications include variable parts on them. If you are creating for example a blog application, the URL to display the articles should include their title or some other unique identifier to let the application know the exact article to display.

In Symfony applications, the variable parts of the routes are enclosed in curly braces (e.g. /blog/read/{article_title}/). Each variable part is assigned a unique name that can be used later in the controller to retrieve each value.

Let’s create a new action with route variables to show this feature in action. Open the src/AppBundle/Controller/DefaultController.php file and add a new method called helloAction with the following content:

// src/AppBundle/Controller/DefaultController.php
namespace AppBundle\Controller;

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class DefaultController extends Controller
{
    // ...

    /**
     * @Route("/hello/{name}", name="hello")
     */
    public function helloAction($name)
    {
        return $this->render('default/hello.html.twig', array(
            'name' => $name
        ));
    }
}

Open your browser and access the http://localhost:8000/hello/fabien URL to see the result of executing this new action. Instead of the action result, you’ll see an error page. As you probably guessed, the cause of this error is that we’re trying to render a template (default/hello.html.twig) that doesn’t exist yet.

Create the new app/Resources/views/default/hello.html.twig template with the following content:

{# app/Resources/views/default/hello.html.twig #}
{% extends 'base.html.twig' %}

{% block body %}
    <h1>Hi {{ name }}! Welcome to Symfony!</h1>
{% endblock %}

Browse again the http://localhost:8000/hello/fabien URL and you’ll see this new template rendered with the information passed by the controller. If you change the last part of the URL (e.g. http://localhost:8000/hello/thomas) and reload your browser, the page will display a different message. And if you remove the last part of the URL (e.g. http://localhost:8000/hello), Symfony will display an error because the route expects a name and you haven’t provided it.

Using Formats¶

Nowadays, a web application should be able to deliver more than just HTML pages. From XML for RSS feeds or Web Services, to JSON for Ajax requests, there are plenty of different formats to choose from. Supporting those formats in Symfony is straightforward thanks to a special variable called _format which stores the format requested by the user.

Tweak the hello route by adding a new _format variable with html as its default value:

// src/AppBundle/Controller/DefaultController.php
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;

// ...

/**
 * @Route("/hello/{name}.{_format}", defaults={"_format"="html"}, name="hello")
 */
public function helloAction($name, $_format)
{
    return $this->render('default/hello.'.$_format.'.twig', array(
        'name' => $name
    ));
}

Obviously, when you support several request formats, you have to provide a template for each of the supported formats. In this case, you should create a new hello.xml.twig template:

<!-- app/Resources/views/default/hello.xml.twig -->
<hello>
    <name>{{ name }}</name>
</hello>

Now, when you browse to http://localhost:8000/hello/fabien, you’ll see the regular HTML page because html is the default format. When visiting http://localhost:8000/hello/fabien.html you’ll get again the HTML page, this time because you explicitly asked for the html format. Lastly, if you visit http://localhost:8000/hello/fabien.xml you’ll see the new XML template rendered in your browser.

That’s all there is to it. For standard formats, Symfony will also automatically choose the best Content-Type header for the response. To restrict the formats supported by a given action, use the requirements option of the @Route() annotation:

// src/AppBundle/Controller/DefaultController.php
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;

// ...

/**
 * @Route("/hello/{name}.{_format}",
 *     defaults = {"_format"="html"},
 *     requirements = { "_format" = "html|xml|json" },
 *     name = "hello"
 * )
 */
public function helloAction($name, $_format)
{
    return $this->render('default/hello.'.$_format.'.twig', array(
        'name' => $name
    ));
}

The hello action will now match URLs like /hello/fabien.xml or /hello/fabien.json, but it will show a 404 error if you try to get URLs like /hello/fabien.js, because the value of the _format variable doesn’t meet its requirements.

Redirecting and Forwarding¶

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

// src/AppBundle/Controller/DefaultController.php
class DefaultController extends Controller
{
    /**
     * @Route("/", name="homepage")
     */
    public function indexAction()
    {
        return $this->redirectToRoute('hello', array('name' => 'Fabien'));
    }
}

The redirectToRoute() method takes as arguments the route name and an optional array of parameters and redirects the user to the URL generated with those arguments.

You can also internally forward the action to another action of the same or different controller using the forward() method:

// src/AppBundle/Controller/DefaultController.php
class DefaultController extends Controller
{
    /**
     * @Route("/", name="homepage")
     */
    public function indexAction()
    {
        return $this->forward('AppBundle:Blog:index', array(
            'name'  => $name
        );
    }
}

Displaying Error Pages¶

Errors will inevitably happen during the execution of every web application. In the case of 404 errors, Symfony includes a handy shortcut that you can use in your controllers:

// src/AppBundle/Controller/DefaultController.php
// ...

class DefaultController extends Controller
{
    /**
     * @Route("/", name="homepage")
     */
    public function indexAction()
    {
        // ...
        throw $this->createNotFoundException();
    }
}

For 500 errors, just throw a regular PHP exception inside the controller and Symfony will transform it into a proper 500 error page:

// src/AppBundle/Controller/DefaultController.php
// ...

class DefaultController extends Controller
{
    /**
     * @Route("/", name="homepage")
     */
    public function indexAction()
    {
        // ...
        throw new \Exception('Something went horribly wrong!');
    }
}

Getting Information from the Request¶

Sometimes your controllers need to access the information related to the user request, such as their preferred language, IP address or the URL query parameters. To get access to this information, add a new argument of type Request to the action. The name of this new argument doesn’t matter, but it must be preceded by the Request type in order to work (don’t forget to add the new use statement that imports this Request class):

// src/AppBundle/Controller/DefaultController.php
namespace AppBundle\Controller;

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

class DefaultController extends Controller
{
    /**
     * @Route("/", name="homepage")
     */
    public function indexAction(Request $request)
    {
        // is it an Ajax request?
        $isAjax = $request->isXmlHttpRequest();

        // what's the preferred language of the user?
        $language = $request->getPreferredLanguage(array('en', 'fr'));

        // get the value of a $_GET parameter
        $pageName = $request->query->get('page');

        // get the value of a $_POST parameter
        $pageName = $request->request->get('page');
    }
}

In a template, you can also access the Request object via the special app.request variable automatically provided by Symfony:

{{ app.request.query.get('page') }}

{{ app.request.request.get('page') }}

Persisting Data in the Session¶

Even if the HTTP protocol is stateless, Symfony provides a nice session object that represents the client (be it a real person using a browser, a bot, or a web service). Between two requests, Symfony stores the attributes in a cookie by using native PHP sessions.

Storing and retrieving information from the session can be easily achieved from any controller:

use Symfony\Component\HttpFoundation\Request;

public function indexAction(Request $request)
{
    $session = $request->getSession();

    // store an attribute for reuse during a later user request
    $session->set('foo', 'bar');

    // get the value of a session attribute
    $foo = $session->get('foo');

    // use a default value if the attribute doesn't exist
    $foo = $session->get('foo', 'default_value');
}

You can also store “flash messages” that will auto-delete after the next request. They are useful when you need to set a success message before redirecting the user to another page (which will then show the message):

public function indexAction(Request $request)
{
    // ...

    // store a message for the very next request
    $this->addFlash('notice', 'Congratulations, your action succeeded!');
}

And you can display the flash message in the template like this:

<div>
    {{ app.session.flashbag.get('notice') }}
</div>

Final Thoughts¶

That’s all there is to it, and I’m not even sure you’ll have spent the full 10 minutes. You were briefly introduced to bundles in the first part, and all the features you’ve learned about so far are part of the core framework bundle. But thanks to bundles, everything in Symfony can be extended or replaced. That’s the topic of the next part of this tutorial.

Understanding the Directory Structure¶

The directory structure of a Symfony application is rather flexible, but the recommended structure is as follows:

app/

The application configuration, templates and translations.

src/

The project’s PHP code.

vendor/

The third-party dependencies.

web/

The web root directory.

// 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();
$request = Request::createFromGlobals();
$response = $kernel->handle($request);
$response->send();

Understanding the Bundle System¶

This section introduces one of the greatest and most powerful features of Symfony, the bundle system.

A bundle is kind of like a plugin in other software. So why is it called a bundle and not a plugin? This is because everything is a bundle in Symfony, from the core framework features to the code you write for your application.

All the code you write for your application is organized in bundles. In Symfony 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.

Bundles are first-class citizens in Symfony. This gives you the flexibility to use pre-built features packaged in third-party bundles or to distribute your own bundles. It makes it easy to pick and choose which features to enable in your application and optimize them the way you want. And at the end of the day, your application code is just as important as the core framework itself.

Symfony already includes an AppBundle that you may use to start developing your application. Then, if you need to split the application into reusable components, you can create your own bundles.

// 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 AppBundle\AppBundle();
    );

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

    return $bundles;
}

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

framework:
    #esi:             ~
    #translator:      { fallback: "%locale%" }
    secret:          "%secret%"
    router:
        resource: "%kernel.root_dir%/config/routing.yml"
        strict_requirements: "%kernel.debug%"
    form:            true
    csrf_protection: true
    validation:      { enable_annotations: true }
    templating:      { engines: ['twig'] }
    default_locale:  "%locale%"
    trusted_proxies: ~
    session:         ~

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

# Swift Mailer Configuration
swiftmailer:
    transport: "%mailer_transport%"
    host:      "%mailer_host%"
    username:  "%mailer_user%"
    password:  "%mailer_password%"
    spool:     { type: memory }

# ...

# 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

# ...

Using Vendors¶

Odds are that your application will depend on third-party libraries. Those should be stored in the vendor/ directory. You should never touch anything in this directory, because it is exclusively managed by Composer. This directory already contains the Symfony libraries, the SwiftMailer library, the Doctrine ORM, the Twig templating system and some other third party libraries and bundles.

Understanding the Cache and Logs¶

Symfony applications can contain several configuration files defined in several formats (YAML, XML, PHP, etc.) Instead of parsing and combining all those files for each request, Symfony uses its own cache system. In fact, the application configuration is only parsed for the very first request and then compiled down to plain PHP code stored in the app/cache/ directory.

In the development environment, Symfony is smart enough to update the cache when you change a file. But in the production environment, to speed things up, it is your responsibility to clear the cache when you update your code or change its configuration. Execute this command to clear the cache in the prod environment:

$ php app/console cache:clear --env=prod

When developing a web application, things can go wrong in many ways. The log files in the app/logs/ directory tell you everything about the requests and help you fix the problem quickly.

Using the Command Line Interface¶

Each application comes with a command line interface tool (app/console) that helps you maintain your application. It provides commands that boost your productivity by automating tedious and repetitive tasks.

Run it without any arguments to learn more about its capabilities:

$ php app/console

The --help option helps you discover the usage of a command:

$ php app/console router:debug --help

Final Thoughts¶

Call me crazy, but after reading this part, you should be comfortable with moving things around and making Symfony work for you. Everything in Symfony is designed to get out of your way. So, feel free to rename and move directories around as you see fit.

And that’s all for the quick tour. From testing to sending emails, you still need to learn a lot to become a Symfony master. Ready to dig into these topics now? Look no further - go to the official The Book and pick any topic you want.

HTTP is Simple¶

HTTP (Hypertext Transfer Protocol to the geeks) is a text language that allows two machines to communicate with each other. That’s it! For example, when checking for the latest xkcd comic, the following (approximate) conversation takes place:

And while the actual language used is a bit more formal, it’s still dead-simple. HTTP is the term used to describe this simple text-based language. No matter how you develop on the web, the goal of your server is always to understand simple text requests, and return simple text responses.

Symfony is built from the ground up around that reality. Whether you realize it or not, HTTP is something you use every day. With Symfony, you’ll learn how to master it.

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, a smartphone 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:

GET	Retrieve the resource from the server
POST	Create a resource on the server
PUT	Update the resource on the server
DELETE	Delete the resource from the server

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

注解

There are actually nine HTTP methods defined by the HTTP specification, but many of them are not widely used or supported. In reality, many modern browsers don’t even support the PUT and DELETE methods.

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 and Responses in PHP¶

So how do you interact with the “request” and create a “response” when using PHP? In reality, PHP abstracts you a bit from the whole process:

$uri = $_SERVER['REQUEST_URI'];
$foo = $_GET['foo'];

header('Content-Type: text/html');
echo 'The URI requested is: '.$uri;
echo 'The value of the "foo" parameter is: '.$foo;

As strange as it sounds, this small application is in fact taking information from the HTTP request and using it to create an HTTP response. Instead of parsing the raw HTTP request message, PHP prepares superglobal variables such as $_SERVER and $_GET that contain all the information from the request. Similarly, instead of returning the HTTP-formatted text response, you can use the header() function to create response headers and simply print out the actual content that will be the content portion of the response message. PHP will create a true HTTP response and return it to the client:

HTTP/1.1 200 OK
Date: Sat, 03 Apr 2011 02:14:33 GMT
Server: Apache/2.2.17 (Unix)
Content-Type: text/html

The URI requested is: /testing?foo=symfony
The value of the "foo" parameter is: symfony

Requests and Responses in Symfony¶

Symfony provides an alternative to the raw PHP approach via two classes that allow you to interact with the HTTP request and response in an easier way. The Request class is a simple object-oriented representation of the HTTP request message. With it, you have all the request information at your fingertips:

use Symfony\Component\HttpFoundation\Request;

$request = Request::createFromGlobals();

// the URI being requested (e.g. /about) minus any query parameters
$request->getPathInfo();

// retrieve GET and POST variables respectively
$request->query->get('foo');
$request->request->get('bar', 'default value if bar does not exist');

// retrieve SERVER variables
$request->server->get('HTTP_HOST');

// retrieves an instance of UploadedFile identified by foo
$request->files->get('foo');

// retrieve a COOKIE value
$request->cookies->get('PHPSESSID');

// retrieve an HTTP request header, with normalized, lowercase keys
$request->headers->get('host');
$request->headers->get('content_type');

$request->getMethod();    // GET, POST, PUT, DELETE, HEAD
$request->getLanguages(); // an array of languages the client accepts

As a bonus, the Request class does a lot of work in the background that you’ll never need to worry about. For example, the isSecure() method checks the three different values in PHP that can indicate whether or not the user is connecting via a secured connection (i.e. HTTPS).

Symfony also provides a Response class: a simple PHP representation of an HTTP response message. This allows your application to use an object-oriented interface to construct the response that needs to be returned to the client:

use Symfony\Component\HttpFoundation\Response;

$response = new Response();

$response->setContent('<html><body><h1>Hello world!</h1></body></html>');
$response->setStatusCode(200);
$response->headers->set('Content-Type', 'text/html');

// prints the HTTP headers followed by the content
$response->send();

If Symfony offered nothing else, you would already have a toolkit for easily accessing request information and an object-oriented interface for creating the response. Even as you learn the many powerful features in Symfony, keep in mind that the goal of your application is always to interpret a request and create the appropriate response based on your application logic.

The Journey from the Request to the Response¶

Like HTTP itself, the Request and Response objects are pretty simple. The hard part of building an application is writing what comes in between. In other words, the real work comes in writing the code that interprets the request information and creates the response.

Your application probably does many things, like sending emails, handling form submissions, saving things to a database, rendering HTML pages and protecting content with security. How can you manage all of this and still keep your code organized and maintainable?

Symfony was created to solve these problems so that you don’t have to.

index.php
contact.php
blog.php

// index.php
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

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

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

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! To 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.

// src/AppBundle/Controller/MainController.php
namespace AppBundle\Controller;

use Symfony\Component\HttpFoundation\Response;

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

Symfony: Build your App, not your Tools¶

You now know that the goal of any app is to interpret each incoming request and create an appropriate response. As an application grows, it becomes more difficult to keep your code organized and maintainable. Invariably, the same complex tasks keep coming up over and over again: persisting things to the database, rendering and reusing templates, handling form submissions, sending emails, validating user input and handling security.

The good news is that none of these problems is unique. Symfony provides a framework full of tools that allow you to build your application, not your tools. With Symfony, nothing is imposed on you: you’re free to use the full Symfony framework, or just one piece of Symfony all by itself.

先用纯 PHP 写一个简单的博客程序¶

首先，让我们不使用框架写一个博客程序。创建一个来显示数据库里保存的文章的页面。纯 PHP 的话非常简单，但看起来并不舒服：

<?php
// index.php
$link = mysql_connect('localhost', 'myuser', 'mypassword');
mysql_select_db('blog_db', $link);

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

<!DOCTYPE html>
<html>
    <head>
        <title>文章列表</title>
    </head>
    <body>
        <h1>文章列表</h1>
        <ul>
            <?php while ($row = mysql_fetch_assoc($result)): ?>
            <li>
                <a href="/show.php?id=<?php echo $row['id'] ?>">
                    <?php echo $row['title'] ?>
                </a>
            </li>
            <?php endwhile ?>
        </ul>
    </body>
</html>

<?php
mysql_close($link);
?>

这样写起来并不费事，运行起来也不慢，但有没有想过随着你程序规模的增大，你该如何维护它。这里列出了几个你可能遇到的问题：

• 没有出错检查：如果数据库连接失败怎么办？
• 代码结构性差：随着代码的增多，文件将越来越多 最后导致你没法继续维护。如果你要处理表单，对应的代码放在 哪儿？如何验证用户提交上来的数据？发邮件的代码写在 哪儿呢？
• 代码重复利用率低：因为所有的代码都写在一个文件里， 也就没法在这个博客的别的“页面”里重复使用任何一段代码了。

<?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);

// 导入 HTML 表现层文件
require 'templates/list.php';

<!DOCTYPE html>
<html>
    <head>
        <title>文章列表</title>
    </head>
    <body>
        <h1>文章列表</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>

<?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;
}

<?php
require_once 'model.php';

$posts = get_all_posts();

require 'templates/list.php';

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

<?php $title = '文章列表' ?>

<?php ob_start() ?>
    <h1>文章列表</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' ?>

添加一个显示博文的页面¶

我们已经重构了博客的“列表”页，使它的代码具有了更好的组织性和可重复使用性。为了检验这一点，让我们添加一个显示博文的页面，来显示被通过 id 参数标记了的单篇博文。

首先在 model.php 文件中新增一个函数，用来通过给定的 id 检索单篇博文:

// model.php
function get_post_by_id($id)
{
    $link = open_database_connection();

    $id = intval($id);
    $query = 'SELECT date, title, body FROM post WHERE id = '.$id;
    $result = mysql_query($query);
    $row = mysql_fetch_assoc($result);

    close_database_connection($link);

    return $row;
}

接下来创建一个新的叫做 show.php 文件，作为新页面的控制器:

<?php
require_once 'model.php';

$post = get_post_by_id($_GET['id']);

require 'templates/show.php';

最后创建新的模板文件 templates/show.php ，来渲染单篇博文:

<?php $title = $post['title'] ?>

<?php ob_start() ?>
    <h1><?php echo $post['title'] ?></h1>

    <div class="date"><?php echo $post['date'] ?></div>
    <div class="body">
        <?php echo $post['body'] ?>
    </div>
<?php $content = ob_get_clean() ?>

<?php include 'layout.php' ?>

现在创建第二页已经非常容易了，也没有写重复的代码。然而这一页还有一堆的问题。选择一个框架吧，把这些问题交给它来解决。例如，缺失或无效的 id 参数会导致页面崩溃。如果能够触发 404 页面将会更好，但做到这一点并不容易。更糟的是，如果你忘记了用 intval() 函数对 id 参数进行清理的话，你将会让整个数据库陷入 SQL 注入攻击的危险之中。

另一个问题就是每一个单独的控制器都必须包含 model.php 文件。如果每个控制器都突然需要包含一个别的文件或者执行其它全局任务（如安全管理）呢？按照目前的情况，这些代码必须添加到每个控制器文件中。如果你忘了包含某个文件，希望这不会给我们带来不安全的因素…

用一个“前端控制器”来解救¶

现在，使用 front controller: 来解救我们的程序吧，它是一个单独的 PHP 文件，我们可以通过它来处理 所有 的请求。有了前端控制器，程序的 URI 略有变化，但开始变得更灵活了：

没有前端控制器
/index.php          => 博客的列表页（index.php 被运行）
/show.php           => 博客的博文展示页（show.php 被运行）

使用 index.php 作为前端控制器
/index.php          => 博客的列表页（index.php 被运行）
/index.php/show          => 博客的博文展示页（index.php 被运行）

当使用前端控制器时，单个 PHP 文件（在这里是 index.php ）将渲染 所有的 请求，对于博文展示页来说， /index.php/show 最终实际执行的是 index.php ，它现在负责用完整的 URI 来进行内部路由请求。。如你所见，前端控制器是个非常强大的工具。

<?php
// index.php

// 加载并初始化任何全局库
require_once 'model.php';
require_once 'controllers.php';

// 在内部路由用户的请求
$uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
if ('/index.php' == $uri) {
    list_action();
} elseif ('/index.php/show' == $uri && isset($_GET['id'])) {
    show_action($_GET['id']);
} else {
    header('Status: 404 Not Found');
    echo '<html><body><h1>页面未找到！</h1></body></html>';
}

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';
}

{
    "require": {
        "symfony/symfony": "2.3.*"
    },
    "autoload": {
        "files": ["model.php","controllers.php"]
    }
}

$ composer install

<?php
// index.php
require_once 'vendor/autoload.php';

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

$request = Request::createFromGlobals();

$uri = $request->getPathInfo();
if ('/' == $uri) {
    $response = list_action();
} elseif ('/show' == $uri && $request->query->has('id')) {
    $response = show_action($request->query->get('id'));
} else {
    $html = '<html><body><h1>页面未找到！</h1></body></html>';
    $response = new Response($html, 404);
}

// 输出响应头并发回响应
$response->send();

// 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);
}

// 模板渲染帮手函数
function render_template($path, array $args)
{
    extract($args);
    ob_start();
    require $path;
    $html = ob_get_clean();

    return $html;
}

// src/AppBundle/Controller/BlogController.php
namespace AppBundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

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

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

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

        if (!$post) {
            // 抛出 404 错误
            throw $this->createNotFoundException();
        }

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

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

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

<h1>文章列表</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>

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

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

blog_show:
    path:     /blog/show/{id}
    defaults: { _controller: AppBundle:Blog:show }

// 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();

更好的模板¶

Symfony 标配的模板引擎叫 Twig，如果你选择使用它，它将让你可以更快地书写更有可读性的模板。这意味着我们的博客程序可以用更少的代码来写。比如，列表模板用 Twig 写的话是下面的样子：

{# app/Resources/views/Blog/list.html.twig #}
{% extends "layout.html.twig" %}

{% block title %}文章列表{% endblock %}

{% block body %}
    <h1>文章列表</h1>
    <ul>
        {% for post in posts %}
        <li>
            <a href="{{ path('blog_show', {'id': post.id}) }}">
                {{ post.title }}
            </a>
        </li>
        {% endfor %}
    </ul>
{% endblock %}

同样的， layout.html.twig 也不难写：

{# app/Resources/views/layout.html.twig #}
<!DOCTYPE html>
<html>
    <head>
        <title>{% block title %}默认标题{% endblock %}</title>
    </head>
    <body>
        {% block body %}{% endblock %}
    </body>
</html>

Symfony 很好地支持 Twig。虽然 Symfony 永远支持 PHP 风格模板，但我们将继续讨论 Twig 的更多优势。更多信息请参阅 模板章节。

从技巧书中再学一些¶

• How to Use PHP instead of Twig for Templates
• How to Define Controllers as Services

Installing the Symfony Installer¶

Using the Symfony Installer is the only recommended way to create new Symfony applications. This installer is a PHP application that has to be installed only once and then it can create any number of Symfony applications.

Depending on your operating system, the installer must be installed in different ways.

$ curl -LsS http://symfony.com/installer > symfony.phar
$ sudo mv symfony.phar /usr/local/bin/symfony
$ chmod a+x /usr/local/bin/symfony

c:\> php -r "readfile('http://symfony.com/installer');" > symfony.phar

c:\> move symfony.phar c:\projects
c:\projects\> php symfony.phar

Creating the Symfony Application¶

Once the Symfony Installer is ready, create your first Symfony application with the new command:

# Linux, Mac OS X
$ symfony new my_project_name

# Windows
c:\> cd projects/
c:\projects\> php symfony.phar new my_project_name

This command creates a new directory called my_project_name that contains a fresh new project based on the most recent stable Symfony version available. In addition, the installer checks if your system meets the technical requirements to execute Symfony applications. If not, you’ll see the list of changes needed to meet those requirements.

# Linux, Mac OS X
$ symfony new my_project_name 2.3.23

# Windows
c:\projects\> php symfony.phar new my_project_name 2.3.23

Creating Symfony Applications without the Installer¶

If you still use PHP 5.3, or if you can’t execute the installer for any reason, you can create Symfony applications using the alternative installation method based on Composer.

Composer is the dependency manager used by modern PHP applications and it can also be used to create new applications based on the Symfony framework. If you don’t have installed it globally, start by reading the next section.

$ composer create-project symfony/framework-standard-edition my_project_name

$ composer create-project symfony/framework-standard-edition my_project_name "2.3.*"

Running the Symfony Application¶

Symfony leverages the internal web server provided by PHP to run applications while developing them. Therefore, running a Symfony application is a matter of browsing the project directory and executing this command:

$ cd my_project_name/
$ php app/console server:run

Then, open your browser and access the http://localhost:8000 URL to see the Welcome page of Symfony:

Instead of the Welcome Page, you may see a blank page or an error page. This is caused by a directory permission misconfiguration. There are several possible solutions depending on your operating system. All of them are explained in the Setting up Permissions section.

The server:run command is only suitable while developing the application. In order to run Symfony applications on production servers, you’ll have to configure your Apache or Nginx web server as explained in Configuring a Web Server.

When you are finished working on your Symfony application, you can stop the server with the server:stop command:

$ php app/console server:stop

Checking Symfony Application Configuration and Setup¶

Symfony applications come with a visual server configuration tester to show if your environment is ready to use Symfony. Access the following URL to check your configuration:

http://localhost:8000/config.php

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

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

$ HTTPDUSER=`ps aux | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
$ sudo chmod +a "$HTTPDUSER 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

$ HTTPDUSER=`ps aux | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
$ sudo setfacl -R -m u:"$HTTPDUSER":rwX -m u:`whoami`:rwX app/cache app/logs
$ sudo setfacl -dR -m u:"$HTTPDUSER":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

Updating Symfony Applications¶

At this point, you’ve created a fully-functional Symfony application in which you’ll start to develop your own project. A Symfony application depends on a number of external libraries. These are downloaded into the vendor/ directory and they are managed exclusively by Composer.

Updating those third-party libraries frequently is a good practice to prevent bugs and security vulnerabilities. Execute the update Composer command to update them all at once:

$ cd my_project_name/
$ composer update

Depending on the complexity of your project, this update process can take up to several minutes to complete.

Installing a Symfony Distribution¶

Symfony project packages “distributions”, which are fully-functional applications that include the Symfony core libraries, a selection of useful bundles, a sensible directory structure and some default configuration. In fact, when you created a Symfony application in the previous sections, you actually downloaded the default distribution provided by Symfony, which is called Symfony Standard Edition.

The Symfony Standard Edition is by far the most popular distribution and it’s also the best choice for developers starting with Symfony. However, the Symfony Community has published other popular distributions that you may use in your applications:

• The Symfony CMF Standard Edition is the best distribution to get started with the Symfony CMF project, which is a project that makes it easier for developers to add CMS functionality to applications built with the Symfony framework.
• The Symfony REST Edition shows how to build an application that provides a RESTful API using the FOSRestBundle and several other related bundles.

Using Source Control¶

If you’re using a version control system like Git, you can safely commit all your project’s code. The reason is that Symfony applications already contain a .gitignore file specially prepared for Symfony.

For specific instructions on how best to set up your project to be stored in Git, see How to Create and Store a Symfony Project in Git.

$ cd my_project_name/
$ composer install

Beginning Development¶

Now that you have a fully-functional Symfony application, you can begin development! Your distribution may contain some sample code - check the README.md file included with the distribution (open it as a text file) to learn about what sample code was included with your distribution.

If you’re new to Symfony, check out “Creating Pages in Symfony”, where you’ll learn how to create pages, change configuration, and do everything else you’ll need in your new application.

Be sure to also check out the Cookbook, which contains a wide variety of articles about solving specific problems with Symfony.

Environments & Front Controllers¶

Every Symfony application runs within an environment. An environment is a specific set of configuration and loaded bundles, represented by a string. The same application can be run with different configurations by running the application in different environments. Symfony comes with three environments defined — dev, test and prod — but you can create your own as well.

Environments are useful by allowing a single application to have a dev environment built for debugging and a production environment optimized for speed. You might also load specific bundles based on the selected environment. For example, Symfony comes with the WebProfilerBundle (described below), enabled only in the dev and test environments.

Symfony comes with two web-accessible front controllers: app_dev.php provides the dev environment, and app.php provides the prod environment. All web accesses to Symfony normally go through one of these front controllers. (The test environment is normally only used when running unit tests, and so doesn’t have a dedicated front controller. The console tool also provides a front controller that can be used with any environment.)

When the front controller initializes the kernel, it provides two parameters: the environment, and also whether the kernel should run in debug mode. To make your application respond faster, Symfony maintains a cache under the app/cache/ directory. When debug mode is enabled (such as app_dev.php does by default), this cache is flushed automatically whenever you make changes to any code or configuration. When running in debug mode, Symfony runs slower, but your changes are reflected without having to manually clear the cache.

http://localhost/app_dev.php/random/100

Before you begin: Create the Bundle¶

Before you begin, you’ll need to create a bundle. In Symfony, a bundle is like a plugin, except that all 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).

Depending on the way you installed Symfony, you may already have a bundle called AcmeDemoBundle. Browse the src/ directory of your project and check if there is a DemoBundle/ directory inside an Acme/ directory. If those directories already exist, skip the rest of this section and go directly to create the route.

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

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

Behind the scenes, a directory is created for the bundle at src/Acme/DemoBundle. 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\DemoBundle\AcmeDemoBundle(),
    );
    // ...

    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 Symfony application is located at app/config/routing.yml. Like all configuration in Symfony, 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 AcmeDemoBundle:

This entry is pretty basic: it tells Symfony to load routing configuration from the Resources/config/routing.yml (routing.xml or routing.php in the XML and PHP code example respectively) file that lives inside the AcmeDemoBundle. 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 path, 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 path ({limit}) is a wildcard. It means that /random/10, /random/327 or any other similar URL will match this route. The {limit} placeholder parameter will also be passed to the controller so that you can use its value to generate the proper random number.

Step 2: Create the Controller¶

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

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

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

class RandomController
{
}

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 Symfony Response object.

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

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

use Symfony\Component\HttpFoundation\Response;

class RandomController
{
    public function indexAction($limit)
    {
        return new Response(
            '<html><body>Number: '.rand(1, $limit).'</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 generate a random number for you:

http://localhost/app_dev.php/random/10

http://localhost/app.php/random/10

$ 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 allow you to move all the presentation code (e.g. HTML) 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
16
17
18
19
20
21
22
23

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

use Symfony\Bundle\FrameworkBundle\Controller\Controller;

class RandomController extends Controller
{
    public function indexAction($limit)
    {
        $number = rand(1, $limit);

        return $this->render(
            'AcmeDemoBundle:Random:index.html.twig',
            array('number' => $number)
        );

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

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, Symfony 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 AcmeDemoBundle:Random: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, AcmeDemoBundle is the bundle name, Random is the controller, and index.html.twig the template:

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 bundle 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 Symfony application and its job is to use a Kernel class, AppKernel, to bootstrap the application.

http://localhost/app.php/random/10

http://localhost/random/10

Though front controllers are essential in handling every request, you’ll rarely need to modify or even think about them. They’ll be mentioned 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\DemoBundle\Controller\RandomController
Path:
    src/Acme/DemoBundle/Controller/RandomController.php

The Source (src) Directory¶

Put simply, the src/ directory contains all 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?

// 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(),
    );

    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;
}

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 bundle
        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 Symfony’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 Symfony bundles. Take a look at AcmeDemoBundle, as it contains some of the most common elements of a bundle:

Controller/

Contains the controllers of the bundle (e.g. RandomController.php).

DependencyInjection/

Holds certain dependency injection extension classes, which may import service configuration, register compiler passes or more (this directory is not necessary).

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

The extension alias (configuration key) can also be used:

$ app/console config:dump-reference framework

http://localhost/app_dev.php/random/10

http://localhost/app.php/random/10

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

$kernel = new AppKernel('prod', false);

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.

请求（Requests）、控制器（Controller）、响应（Response）生命周期¶

每一个 Symfony 项目处理的请求都经过这个简单的生命周期。框架将接管所有重复的活动，这意味着你只需要把你自己的特有的代码写入控制器的函数即可：

1. 每个请求都被交给一个单一的前端控制器（Front Controller）处理并引导整个程序（如 app.php 或 app_dev.php）；
2. Router（路由器） 从请求中读取信息（比如 URI)，并 寻找一条符合这个信息的路由，然后读取路由信息中的 _controller 参数；
3. 被命中的路由信息中给出的控制器将被执行，控制器中的代码将 创建并返回一个 Response 对象；
4. Response 对象中的 HTTP 头和内容将被送回 客户端。

创建一个页面简单到只需要创建一个控制器（第三步中用到），再添加一条路由将 URL 映射到控制器上（第二步中用到）。

一个简单的控制器¶

虽然刚才说到控制器可以是任何一段可以被调用的 PHP 代码（比如一个函数、对象中的方法或者一个 Closure（闭包）），但控制器一般都是控制器类中的一个方法。控制器也被叫做 Action（动作）。

// src/AppBundle/Controller/HelloController.php
namespace AppBundle\Controller;

use Symfony\Component\HttpFoundation\Response;

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

这个控制器相当明了：

• 第4行： Symfony 使用 PHP 5.3 的命名空间这一很方便的功能来 命名整个控制器类。use 关键字将导入 控制器必须返回的 Response 类。
• 第6行：类名是在你给控制器类起的名字 （比如 Hello）后面加上 Controller 这个单词构成的。这个规范 保持控制器的一致性并且将允许你只使用 类名的第一个部分 （在这里是 Hello）来配置路由。
• 第8行：控制器类中的每一个动作都要以 Action 结尾 这样你就可以在配置路由时只写动作本身的名字（这里是 index ）了。 在下一节你将创建一条路由将 URL 映射到这个动作上。 你也将学到如何把路由中的占位符（这里是``{name}``）变成 动作的方法的参数（这里是``$name``）。
• 第10行：控制器创建并返回一个 Response 对象。

将 URL 映射到控制器上¶

这个新控制器返回一个简单的 HTML 页面。要想真正地访问这个页面，你需要创建一条将指定 URL 路径映射到对应控制器的路由：