创建页面

运行环境 & 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

在您开始之前请先创建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 Bundle系统).

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

    return $bundles;
}

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

第一步：创建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.

第二部：创建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 AcmeDemoBundleControllerRandomController. Start by creating this file inside your AcmeDemoBundle:

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

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

use SymfonyComponentHttpFoundationResponse;

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.

第三部（可选）：创建模板¶

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

use SymfonyBundleFrameworkBundleControllerController;

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.

Web目录¶

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

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

应用（ app ）目录¶

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 Bundle系统).
• 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:
    AcmeDemoBundleControllerRandomController
Path:
    src/Acme/DemoBundle/Controller/RandomController.php

代码（ src ）目录¶

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 SymfonyBundleFrameworkBundleFrameworkBundle(),
        new SymfonyBundleSecurityBundleSecurityBundle(),
        new SymfonyBundleTwigBundleTwigBundle(),
        new SymfonyBundleMonologBundleMonologBundle(),
        new SymfonyBundleSwiftmailerBundleSwiftmailerBundle(),
        new SymfonyBundleDoctrineBundleDoctrineBundle(),
        new SymfonyBundleAsseticBundleAsseticBundle(),
        new SensioBundleFrameworkExtraBundleSensioFrameworkExtraBundle(),
    );

    if (in_array($this->getEnvironment(), array('dev', 'test'))) {
        $bundles[] = new AcmeDemoBundleAcmeDemoBundle();
        $bundles[] = new SymfonyBundleWebProfilerBundleWebProfilerBundle();
        $bundles[] = new SensioBundleDistributionBundleSensioDistributionBundle();
        $bundles[] = new SensioBundleGeneratorBundleSensioGeneratorBundle();
    }

    return $bundles;
}

创建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 AcmeTestBundle;

use SymfonyComponentHttpKernelBundleBundle;

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

    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目录结构¶

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.

导入默认配置项¶

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

运行环境设置¶

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.