6.1. The Front Controller

All web requests are handled by a single front controller, which is the unique entry point to the whole application in a given environment.

When the front controller receives a request, it uses the routing system to match an action name and a module name with the URL typed (or clicked) by the user. For instance, the following request URL calls the index.php script (that's the front controller) and will be understood as a call to the action myAction of the module mymodule:

http://localhost/index.php/mymodule/myAction

If you are not interested in symfony's internals, that's all that you need to know about the front controller. It is an indispensable component of the symfony MVC architecture, but you will seldom need to change it. So you can jump to the next section unless you really want to know about the guts of the front controller.

6.1.1. The Front Controller's Job in Detail

The front controller does the dispatching of the request, but that means a little more than just determining the action to execute. In fact, it executes the code that is common to all actions, including the following:

1. Load the project configuration class and the symfony libraries.
2. Create an application configuration and a symfony context.
3. Load and initiate the core framework classes.
4. Load the configuration.
5. Decode the request URL to determine the action to execute and the request parameters.
6. If the action does not exist, redirect to the 404 error action.
7. Activate filters (for instance, if the request needs authentication).
8. Execute the filters, first pass.
9. Execute the action and render the view.
10. Execute the filters, second pass.
11. Output the response.

6.1.2. The Default Front Controller

The default front controller, called index.php and located in the web/ directory of the project, is a simple PHP file, as shown in Listing 6-1.

Listing 6-1 - The Default Production Front Controller

<?php

require_once(dirname(__FILE__).'/../config/ProjectConfiguration.class.php');

$configuration = ProjectConfiguration::getApplicationConfiguration('frontend', 'prod', false);
sfContext::createInstance($configuration)->dispatch();

The front controller includes the application configuration, which takes care of steps 2 through 4. The call to the dispatch() method of the sfController object (which is the core controller object of the symfony MVC architecture) dispatches the request, taking care of steps 5 through 7. The last steps are handled by the filter chain, as explained later in this chapter.

6.1.3. Calling Another Front Controller to Switch the Environment

One front controller exists per environment. As a matter of fact, it is the very existence of a front controller that defines an environment. The environment is defined by the second argument you pass to the ProjectConfiguration::getApplicationConfiguration() method call.

To change the environment in which you're browsing your application, just choose another front controller. The default front controllers available when you create a new application with the generate:app task are index.php for the production environment and frontend_dev.php for the development environment (provided that your application is called frontend). The default mod_rewrite configuration will use index.php when the URL doesn't contain a front controller script name. So both of these URLs display the same page (mymodule/index) in the production environment:

http://localhost/index.php/mymodule/index
http://localhost/mymodule/index

and this URL displays that same page in the development environment:

http://localhost/frontend_dev.php/mymodule/index

Creating a new environment is as easy as creating a new front controller. For instance, you may need a staging environment to allow your customers to test the application before going to production. To create this staging environment, just copy web/frontend_dev.php into web/frontend_staging.php, and change the value of the second argument of the ProjectConfiguration::getApplicationConfiguration() call to staging. Now, in all the configuration files, you can add a new staging: section to set specific values for this environment, as shown in Listing 6-2.

Listing 6-2 - Sample app.yml with Specific Settings for the Staging Environment

staging:
  mail:
    webmaster:    [email protected]
    contact:      [email protected]
all:
  mail:
    webmaster:    [email protected]
    contact:      [email protected]

If you want to see how the application reacts in this new environment, call the related front controller:

http://localhost/frontend_staging.php/mymodule/index