Chapter 6 - Inside The Controller Layer

In symfony, the controller layer, which contains the code linking the business logic and the presentation, is split into several components that you use for different purposes:

• The front controller is the unique entry point to the application. It loads the configuration and determines the action to execute.
• Actions contain the applicative logic. They check the integrity of the request and prepare the data needed by the presentation layer.
• The request, response, and session objects give access to the request parameters, the response headers, and the persistent user data. They are used very often in the controller layer.
• Filters are portions of code executed for every request, before or after the action. For example, the security and validation filters are commonly used in web applications. You can extend the framework by creating your own filters.

This chapter describes all these components, but don't be intimidated by their number. For a basic page, you will probably need to write only a few lines in the action class, and that's all. The other controller components will be of use only in specific situations.

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.

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. Define the core constants.
2. Locate the symfony libraries.
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.

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
 
define('SF_ROOT_DIR',    realpath(dirname(__FILE__).'/..'));
define('SF_APP',         'myapp');
define('SF_ENVIRONMENT', 'prod');
define('SF_DEBUG',       false);
 
require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');
 
sfContext::getInstance()->getController()->dispatch();

The constants definition corresponds to the first step described in the previous section. Then the front controller includes the application config.php, 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.

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 in the SF_ENVIRONMENT constant.

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 symfony init-app task are index.php for the production environment and myapp_dev.php for the development environment (provided that your application is called myapp). 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/myapp_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/myapp_dev.php into web/myapp_staging.php, and change the value of the SF_ENVIRONMENT constant 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:    dummy@mysite.com
    contact:      dummy@mysite.com
all:
  mail:
    webmaster:    webmaster@mysite.com
    contact:      contact@mysite.com

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

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

Batch Files

You may want to execute a script from the command line (or via a cron table) with access to all the symfony classes and features, for instance to launch batch e-mail jobs or to periodically update your model through a process-intensive calculation. For such a script, you need to include the same lines as in a front controller at the beginning. Listing 6-3 shows an example of the beginning of a batch script.

Listing 6-3 - Sample Batch Script

<?php
 
define('SF_ROOT_DIR',    realpath(dirname(__FILE__).'/..'));
define('SF_APP',         'myapp');
define('SF_ENVIRONMENT', 'prod');
define('SF_DEBUG',       false);
 
require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');
 
// add code here

You can see that the only missing line is the call to the dispatch() method of the sfController object, which can be used only with a web server, not in a batch process. Defining an application and an environment gives you access to a specific configuration. Including the application config.php initiates the context and the autoloading.

Actions

The actions are the heart of an application, because they contain all the application's logic. They use the model and define variables for the view. When you make a web request in a symfony application, the URL defines an action and the request parameters.

The Action Class

Actions are methods named executeActionName of a class named moduleNameActions inheriting from the sfActions class, and grouped by modules. The action class of a module is stored in an actions.class.php file, in the module's actions/ directory.

Listing 6-4 shows an example of an actions.class.php file with only an index action for the whole mymodule module.

Listing 6-4 - Sample Action Class, in apps/myapp/modules/mymodule/actions/actions.class.php

class mymoduleActions extends sfActions
{
  public function executeIndex()
  {
 
  }
}

In order to request an action, you need to call the front controller script with the module name and action name as parameters. By default, this is done by appending the couple module_name/action_name to the script. This means that the action defined in Listing 6-4 can be called by this URL:

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

Adding more actions just means adding more execute methods to the sfActions object, as shown in Listing 6-5.

Listing 6-5 - Action Class with Two Actions, in myapp/modules/mymodule/actions/actions.class.php

class mymoduleActions extends sfActions
{
  public function executeIndex()
  {
    ...
  }
 
  public function executeList()
  {
    ...
  }
}

If the size of an action class grows too much, you probably need to do some refactoring and move some code to the model layer. Actions should often be kept short (not more than a few lines), and all the business logic should usually be in the model.

Still, the number of actions in a module can be important enough to lead you to split it in two modules.

Alternative Action Class Syntax

An alternative action syntax is available to dispatch the actions in separate files, one file per action. In this case, each action class extends sfAction (instead of sfActions) and is named actionNameAction. The actual action method is simply named execute. The file name is the same as the class name. This means that the equivalent of Listing 6-5 can be written with the two files shown in Listings 6-6 and 6-7.

Listing 6-6 - Single Action File, in myapp/modules/mymodule/actions/indexAction.class.php

class indexAction extends sfAction
{
  public function execute()
  {
    ...
  }
}

Listing 6-7 - Single Action File, in myapp/modules/mymodule/actions/listAction.class.php

class listAction extends sfAction
{
  public function execute()
  {
    ...
  }
}

Retrieving Information in the Action

The action class offers a way to access controller-related information and the core symfony objects. Listing 6-8 demonstrates how to use them.

Listing 6-8 - sfActions Common Methods

class mymoduleActions extends sfActions
{
  public function executeIndex()
  {
    // Retrieving request parameters
    $password    = $this->getRequestParameter('password');
 
    // Retrieving controller information
    $moduleName  = $this->getModuleName();
    $actionName  = $this->getActionName();
 
    // Retrieving framework core objects
    $request     = $this->getRequest();
    $userSession = $this->getUser();
    $response    = $this->getResponse();
    $controller  = $this->getController();
    $context     = $this->getContext();
 
    // Setting action variables to pass information to the template
    $this->setVar('foo', 'bar');
    $this->foo = 'bar';            // Shorter version
 
  }
}

Action Termination

Various behaviors are possible at the conclusion of an action's execution. The value returned by the action method determines how the view will be rendered. Constants of the sfView class are used to specify which template is to be used to display the result of the action.

If there is a default view to call (this is the most common case), the action should end as follows:

return sfView::SUCCESS;

Symfony will then look for a template called actionNameSuccess.php. This is defined as the default action behavior, so if you omit the return statement in an action method, symfony will also look for an actionNameSuccess.php template. Empty actions will also trigger that behavior. See Listing 6-9 for examples of successful action termination.

Listing 6-9 - Actions That Will Call the indexSuccess.php and listSuccess.php Templates

public function executeIndex()
{
  return sfView::SUCCESS;
}
 
public function executeList()
{
}

If there is an error view to call, the action should end like this:

return sfView::ERROR;

Symfony will then look for a template called actionNameError.php.

To call a custom view, use this ending:

return 'MyResult';

Symfony will then look for a template called actionNameMyResult.php.

If there is no view to call--for instance, in the case of an action executed in a batch process--the action should end as follows:

return sfView::NONE;

No template will be executed in that case. It means that you can bypass completely the view layer and set the response HTML code directly from an action. As shown in Listing 6-10, symfony provides a specific renderText() method for this case. This can be useful when you need extreme responsiveness of the action, such as for Ajax interactions, which will be discussed in Chapter 11.

Listing 6-10 - Bypassing the View by Echoing the Response and Returning sfView::NONE

public function executeIndex()
{
  $this->getResponse()->setContent("<html><body>Hello, World!</body></html>");
 
  return sfView::NONE;
}
 
// Is equivalent to
public function executeIndex()
{
  return $this->renderText("<html><body>Hello, World!</body></html>");
}

In some cases, you need to send an empty response but with some headers defined in it (especially the X-JSON header). Define the headers via the sfResponse object, discussed in the next chapter, and return the sfView::HEADER_ONLY constant, as shown in Listing 6-11.

Listing 6-11 - Escaping View Rendering and Sending Only Headers

public function executeRefresh()
{
  $output = '<"title","My basic letter"],["name","Mr Brown">';
  $this->getResponse()->setHttpHeader("X-JSON", '('.$output.')');
 
  return sfView::HEADER_ONLY;
}

If the action must be rendered by a specific template, ignore the return statement and use the setTemplate() method instead.

$this->setTemplate('myCustomTemplate');

Skipping to Another Action

In some cases, the action execution ends by requesting a new action execution. For instance, an action handling a form submission in a POST request usually redirects to another action after updating the database. Another example is an action alias: the index action is often a way to display a list, and actually forwards to a list action.

The action class provides two methods to execute another action:

• If the action forwards the call to another action:

  $this->forward('otherModule', 'index');

• If the action results in a web redirection:

  $this->redirect('otherModule/index');
  $this->redirect('http://www.google.com/');

The choice between a redirect or a forward is sometimes tricky. To choose the best solution, keep in mind that a forward is internal to the application and transparent to the user. As far as the user is concerned, the displayed URL is the same as the one requested. In contrast, a redirect is a message to the user's browser, involving a new request from it and a change in the final resulting URL.

If the action is called from a submitted form with method="post", you should always do a redirect. The main advantage is that if the user refreshes the resulting page, the form will not be submitted again; in addition, the back button works as expected by displaying the form and not an alert asking the user if he wants to resubmit a POST request.

There is a special kind of forward that is used very commonly. The forward404() method forwards to a "page not found" action. This method is often called when a parameter necessary to the action execution is not present in the request (thus detecting a wrongly typed URL). Listing 6-12 shows an example of a show action expecting an id parameter.

Listing 6-12 - Use of the forward404() Method

public function executeShow()
{
  $article = ArticlePeer::retrieveByPK($this->getRequestParameter('id'));
  if (!$article)
  {
    $this->forward404();
  }
}

Experience shows that, most of the time, an action makes a redirect or a forward after testing something, such as in Listing 6-12. That's why the sfActions class has a few more methods, named forwardIf(), forwardUnless(), forward404If(), forward404Unless(), redirectIf(), and redirectUnless(). These methods simply take an additional parameter representing a condition that triggers the execution if tested true (for the xxxIf() methods) or false (for the xxxUnless() methods), as illustrated in Listing 6-13.

Listing 6-13 - Use of the forward404If() Method

// This action is equivalent to the one shown in Listing 6-12
public function executeShow()
{
  $article = ArticlePeer::retrieveByPK($this->getRequestParameter('id'));
  $this->forward404If(!$article);
}
 
// So is this one
public function executeShow()
{
  $article = ArticlePeer::retrieveByPK($this->getRequestParameter('id'));
  $this->forward404Unless($article);
}

Using these methods will not only keep your code short, but it will also make it more readable.

Repeating Code for Several Actions of a Module

The convention to name actions executeActionName() (in the case of an sfActions class) or execute() (in the case of an sfAction class) guarantees that symfony will find the action method. It gives you the ability to add other methods of your own that will not be considered as actions, as long as they don't start with execute.

There is another useful convention for when you need to repeat several statements in each action before the actual action execution. You can then extract them into the preExecute() method of your action class. You can probably guess how to repeat statements after every action is executed: wrap them in a postExecute() method. The syntax of these methods is shown in Listing 6-14.

Listing 6-14 - Using preExecute, postExecute, and Custom Methods in an Action Class

class mymoduleActions extends sfActions
{
  public function preExecute()
  {
    // The code inserted here is executed at the beginning of each action call
    ...
  }
 
  public function executeIndex()
  {
    ...
  }
 
  public function executeList()
  {
    ...
    $this->myCustomMethod();  // Methods of the action class are accessible
  }
 
  public function postExecute()
  {
    // The code inserted here is executed at the end of each action call
    ...
  }
 
  protected function myCustomMethod()
  {
    // You can also add your own methods, as long as they don't start with "execute"
    // In that case, it's better to declare them as protected or private
    ...
  }
}

Accessing the Request

You're familiar with the getRequestParameter('myparam') method, used to retrieve the value of a request parameter by its name. As a matter of fact, this method is a proxy for a chain of calls to the request's parameter holder getRequest()->getParameter('myparam'). The action class has access to the request object, called sfWebRequest in symfony, and to all its methods, via the getRequest() method. Table 6-1 lists the most useful sfWebRequest methods.

Table 6-1 - Methods of the sfWebRequest Object

* Works with prototype, Prototype, Mootools, and jQuery

** Sometimes blocked by proxies

The sfActions class offers a few proxies to access the request methods more quickly, as shown in Listing 6-15.

Listing 6-15 - Accessing the sfRequest Object Methods from an Action

class mymoduleActions extends sfActions
{
  public function executeIndex()
  {
    $hasFoo = $this->getRequest()->hasParameter('foo');
    $hasFoo = $this->hasRequestParameter('foo');  // Shorter version
    $foo    = $this->getRequest()->getParameter('foo');
    $foo    = $this->getRequestParameter('foo');  // Shorter version
  }
}

For multipart requests to which users attach files, the sfWebRequest object provides a means to access and move these files, as shown in Listing 6-16.

Listing 6-16 - The sfWebRequest Object Knows How to Handle Attached Files

class mymoduleActions extends sfActions
{
  public function executeUpload()
  {
    if ($this->getRequest()->hasFiles())
    {
      foreach ($this->getRequest()->getFileNames() as $uploadedFile)
      {
        $fileName  = $this->getRequest()->getFileName($uploadedFile);
        $fileSize  = $this->getRequest()->getFileSize($uploadedFile);
        $fileType  = $this->getRequest()->getFileType($uploadedFile);
        $fileError = $this->getRequest()->hasFileError($uploadedFile);
        $uploadDir = sfConfig::get('sf_upload_dir');
        $this->getRequest()->moveFile($uploadedFile, $uploadDir.'/'.$fileName);
      }
    }
  }
}

You don't have to worry about whether your server supports the $_SERVER or the $_ENV variables, or about default values or server-compatibility issues--the sfWebRequest methods do it all for you. Besides, their names are so evident that you will no longer need to browse the PHP documentation to find out how to get information from the request.

User Session

Symfony automatically manages user sessions and is able to keep persistent data between requests for users. It uses the built-in PHP session-handling mechanisms and enhances them to make them more configurable and easier to use.

Accessing the User Session

The session object for the current user is accessed in the action with the getUser() method and is an instance of the sfUser class. This class contains a parameter holder that allows you to store any user attribute in it. This data will be available to other requests until the end of the user session, as shown in Listing 6-17. User attributes can store any type of data (strings, arrays, and associative arrays). They can be set for every individual user, even if that user is not identified.

Listing 6-17 - The sfUser Object Can Hold Custom User Attributes Existing Across Requests

class mymoduleActions extends sfActions
{
  public function executeFirstPage()
  {
    $nickname = $this->getRequestParameter('nickname');
 
    // Store data in the user session
    $this->getUser()->setAttribute('nickname', $nickname);
  }
 
  public function executeSecondPage()
  {
    // Retrieve data from the user session with a default value
    $nickname = $this->getUser()->getAttribute('nickname', 'Anonymous Coward');
  }
}

Like many getters in symfony, the getAttribute() method accepts a second argument, specifying the default value to be used when the attribute is not defined. To check whether an attribute has been defined for a user, use the hasAttribute() method. The attributes are stored in a parameter holder that can be accessed by the getAttributeHolder() method. It allows for easy cleanup of the user attributes with the usual parameter holder methods, as shown in Listing 6-18.

Listing 6-18 - Removing Data from the User Session

class mymoduleActions extends sfActions
{
  public function executeRemoveNickname()
  {
    $this->getUser()->getAttributeHolder()->remove('nickname');
  }
 
  public function executeCleanup()
  {
    $this->getUser()->getAttributeHolder()->clear();
  }
}

The user session attributes are also available in the templates by default via the $sf_user variable, which stores the current sfUser object, as shown in Listing 6-19.

Listing 6-19 - Templates Also Have Access to the User Session Attributes

<p>
  Hello, <?php echo $sf_user->getAttribute('nickname') ?>
</p>

Flash Attributes

A recurrent problem with user attributes is the cleaning of the user session once the attribute is not needed anymore. For instance, you may want to display a confirmation after updating data via a form. As the form-handling action makes a redirect, the only way to pass information from this action to the action it redirects to is to store the information in the user session. But once the confirmation message is displayed, you need to clear the attribute; otherwise, it will remain in the session until it expires.

The flash attribute is an ephemeral attribute that you can define and forget, knowing that it will disappear after the very next request and leave the user session clean for the future. In your action, define the flash attribute like this:

$this->setFlash('attrib', $value);

The template will be rendered and delivered to the user, who will then make a new request to another action. In this second action, just get the value of the flash attribute like this:

$value = $this->getFlash('attrib');

Then forget about it. After delivering this second page, the attrib flash attribute will be flushed. And even if you don't require it during this second action, the flash will disappear from the session anyway.

If you need to access a flash attribute from a template, use the $sf_flash object:

<?php if ($sf_flash->has('attrib')): ?>
  <?php echo $sf_flash->get('attrib') ?>
<?php endif; ?>

or just:

<?php echo $sf_flash->get('attrib') ?>

Flash attributes are a clean way of passing information to the very next request.

Session Management

Symfony's session-handling feature completely masks the client and server storage of the session IDs to the developer. However, if you want to modify the default behaviors of the session-management mechanisms, it is still possible. This is mostly for advanced users.

On the client side, sessions are handled by cookies. The symfony session cookie is called symfony, but you can change its name by editing the factories.yml configuration file, as shown in Listing 6-20.

Listing 6-20 - Changing the Session Cookie Name, in apps/myapp/config/factories.yml

all:
  storage:
    class: sfSessionStorage
    param:
      session_name: my_cookie_name

Symfony's session handling is based on PHP sessions. This means that if you want the client-side management of sessions to be handled by URL parameters instead of cookies, you just need to change the use_trans_sid setting in your php.ini. Be aware that this is not recommended.

session.use_trans_sid = 1

On the server side, symfony stores user sessions in files by default. You can store them in your database by changing the value of the class parameter in factories.yml, as shown in Listing 6-21.

Listing 6-21 - Changing the Server Session Storage, in apps/myapp/config/factories.yml

all:
  storage:
    class: sfMySQLSessionStorage
    param:
      db_table: SESSION_TABLE_NAME      # Name of the table storing the sessions
      database: DATABASE_CONNECTION     # Name of the database connection to use

The available session storage classes are sfMySQLSessionStorage, sfPostgreSQLSessionStorage, and sfPDOSessionStorage; the latter is preferred. The optional database setting defines the database connection to be used; symfony will then use databases.yml (see Chapter 8) to determine the connection settings (host, database name, user, and password) for this connection.

Session expiration occurs automatically after sf_timeout seconds. This constant is 30 minutes by default and can be modified for each environment in the settings.yml configuration file, as shown in Listing 6-22.

Listing 6-22 - Changing Session Lifetime, in apps/myapp/config/settings.yml

default:
  .settings:
    timeout:     1800           # Session lifetime in seconds

Action Security

The ability to execute an action can be restricted to users with certain privileges. The tools provided by symfony for this purpose allow the creation of secure applications, where users need to be authenticated before accessing some features or parts of the application. Securing an application requires two steps: declaring the security requirements for each action and logging in users with privileges so that they can access these secure actions.

Access Restriction

Before being executed, every action passes by a special filter that checks if the current user has the privileges to access the requested action. In symfony, privileges are composed of two parts:

• Secure actions require users to be authenticated.
• Credentials are named security privileges that allow organizing security by group.

Restricting access to an action is simply made by creating and editing a YAML configuration file called security.yml in the module config/ directory. In this file, you can specify the security requirements that users must fulfill for each action or for all actions. Listing 6-23 shows a sample security.yml.

Listing 6-23 - Setting Access Restrictions, in apps/myapp/modules/mymodule/config/security.yml

read:
  is_secure:   off       # All users can request the read action

update:
  is_secure:   on        # The update action is only for authenticated users

delete:
  is_secure:   on        # Only for authenticated users
  credentials: admin     # With the admin credential

all:
  is_secure:  off        # off is the default value anyway

Actions are not secure by default, so when there is no security.yml or no mention of an action in it, actions are accessible by everyone. If there is a security.yml, symfony looks for the name of the requested action and, if it exists, checks the fulfillment of the security requirements. What happens when a user tries to access a restricted action depends on his credentials:

• If the user is authenticated and has the proper credentials, the action is executed.
• If the user is not identified, he will be redirected to the default login action.
• If the user is identified but doesn't have the proper credentials, he will be redirected to the default secure action, shown in Figure 6-1.

The default login and secure pages are pretty simple, and you will probably want to customize them. You can configure which actions are to be called in case of insufficient privileges in the application settings.yml by changing the value of the properties shown in Listing 6-24.

Figure 6-1 - The default secure action page

Listing 6-24 - Default Security Actions Are Defined in apps/myapp/config/settings.yml

all:
  .actions:
    login_module:           default
    login_action:           login

    secure_module:          default
    secure_action:          secure

Granting Access

To get access to restricted actions, users need to be authenticated and/or to have certain credentials. You can extend a user's privileges by calling methods of the sfUser object. The authenticated status of the user is set by the setAuthenticated() method and can be checked with isAuthenticated(). Listing 6-25 shows a simple example of user authentication.

Listing 6-25 - Setting the Authenticated Status of a User

class myAccountActions extends sfActions
{
  public function executeLogin()
  {
    if ($this->getRequestParameter('login') == 'foobar')
    {
      $this->getUser()->setAuthenticated(true);
    }
  }
 
  public function executeLogout()
  {
    if ($this->getUser()->isAuthenticated())
    {
      $this->getUser()->setAuthenticated(false);
    }
  }
}

Credentials are a bit more complex to deal with, since you can check, add, remove, and clear credentials. Listing 6-26 describes the credential methods of the sfUser class.

Listing 6-26 - Dealing with User Credentials in an Action

class myAccountActions extends sfActions
{
  public function executeDoThingsWithCredentials()
  {
    $user = $this->getUser();
 
    // Add one or more credentials
    $user->addCredential('foo');
    $user->addCredentials('foo', 'bar');
 
    // Check if the user has a credential
    echo $user->hasCredential('foo');                      =>   true
 
    // Check if the user has both credentials
    echo $user->hasCredential(array('foo', 'bar'));        =>   true
 
    // Check if the user has one of the credentials
    echo $user->hasCredential(array('foo', 'bar'), false); =>   true
 
    // Remove a credential
    $user->removeCredential('foo');
    echo $user->hasCredential('foo');                      =>   false
 
    // Remove all credentials (useful in the logout process)
    $user->clearCredentials();
    echo $user->hasCredential('bar');                      =>   false
  }
}

If a user has the 'foo' credential, that user will be able to access the actions for which the security.yml requires that credential. Credentials can also be used to display only authorized content in a template, as shown in Listing 6-27.

Listing 6-27 - Dealing with User Credentials in a Template

<ul>
  <li><?php echo link_to('section1', 'content/section1') ?></li>
  <li><?php echo link_to('section2', 'content/section2') ?></li>
  <?php if ($sf_user->hasCredential('section3')): ?>
  <li><?php echo link_to('section3', 'content/section3') ?></li>
  <?php endif; ?>
</ul>

As for the authenticated status, credentials are often given to users during the login process. This is why the sfUser object is often extended to add login and logout methods, in order to set the security status of users in a central place.

Complex Credentials

The YAML syntax used in the security.yml file allows you to restrict access to users having a combination of credentials, using either AND-type or OR-type associations. With such a combination, you can build a complex workflow and user privilege management system--for instance, a content management system (CMS) back-office accessible only to users with the admin credential, where articles can be edited only by users with the editor credential and published only by the ones with the publisher credential. Listing 6-28 shows this example.

Listing 6-28 - Credentials Combination Syntax

editArticle:
  credentials: [ admin, editor ]              # admin AND editor

publishArticle:
  credentials: [ admin, publisher ]           # admin AND publisher

userManagement:
  credentials: [[ admin, superuser ]]         # admin OR superuser

Each time you add a new level of square brackets, the logic swaps between AND and OR. So you can create very complex credential combinations, such as this:

credentials: [[root, [supplier, [owner, quasiowner]], accounts]]
             # root OR (supplier AND (owner OR quasiowner)) OR accounts

Validation and Error-Handling Methods

Validating the action input--mostly request parameters--is a repetitive and tedious task. Symfony offers a built-in request validation system, using methods of the action class.

Let's start with an example. When a user makes a request for myAction, symfony always looks for a method called validateMyAction() first. If it is found, then symfony executes it. The return value of this validation method determines the next method to be executed: if it returns true, then executeMyAction() is executed; otherwise, handleErrorMyAction() is executed. And, if in the latter case, handleErrorMyAction() doesn't exist, symfony looks for a generic handleError() method. If that doesn't exist either, it simply returns sfView::ERROR to render the myActionError. php template. Figure 6-2 depicts this process.

Figure 6-2 - The validation process

So the key to validation is to respect the naming conventions for the action methods:

• validateActionName is the validation method, returning true or false. It is the first method looked for when the action ActionName is requested. If it doesn't exist, the action method is executed directly.
• handleErrorActionName is the method called when the validation method fails. If it doesn't exist, the Error template is displayed.
• executeActionName is the action method. It must exist for all actions.

Listing 6-29 shows an example of an action class with validation methods. Whether the validation passes or fails in this example, the myActionSuccess.php template will be executed, but not with the same parameters.

Listing 6-29 - Sample Validation Methods

class mymoduleActions extends sfActions
{
  public function validateMyAction()
  {
    return ($this->getRequestParameter('id') > 0);
  }
 
  public function handleErrorMyAction()
  {
    $this->message = "Invalid parameters";
 
    return sfView::SUCCESS;
  }
 
  public function executeMyAction()
  {
    $this->message = "The parameters are correct";
  }
}

You can put any code you want in the validate() methods. Just make sure they return either true or false. As it is a method of the sfActions class, it has access to the sfRequest and sfUser objects as well, which can be really useful for input and context validation.

You could use this mechanism to implement form validation (that is, control the values entered by the user in a form before processing it), but this is the type of repetitive task for which symfony provides automated tools, as described in Chapter 10.

Filters

The security process can be understood as a filter by which all requests must pass before executing the action. According to some tests executed in the filter, the processing of the request is modified--for instance, by changing the action executed (default/secure instead of the requested action in the case of the security filter). Symfony extends this idea to filter classes. You can specify any number of filter classes to be executed before the action execution or before the response rendering, and do this for every request. You can see filters as a way to package some code, similar to preExecute() and postExecute(), but at a higher level (for a whole application instead of for a whole module).

The Filter Chain

Symfony actually sees the processing of a request as a chain of filters. When a request is received by the framework, the first filter (which is always the sfRenderingFilter) is executed. At some point, it calls the next filter in the chain, then the next, and so on. When the last filter (which is always sfExecutionFilter) is executed, the previous filter can finish, and so on back to the rendering filter. Figure 6-3 illustrates this idea with a sequence diagram, using an artificially small filter chain (the real one contains more filters).

Figure 6-3 - Sample filter chain

This process justifies the structure of the filter classes. They all extend the sfFilter class, and contain one execute() method, expecting a $filterChain object as parameter. Somewhere in this method, the filter passes to the next filter in the chain by calling $filterChain->execute(). See Listing 6-30 for an example. So basically, filters are divided into two parts:

• The code before the call to $filterChain->execute() executes before the action execution.
• The code after the call to $filterChain->execute() executes after the action execution and before the rendering.

Listing 6-30 - Filter Class Struture

class myFilter extends sfFilter
{
  public function execute ($filterChain)
  {
    // Code to execute before the action execution
    ...
 
    // Execute next filter in the chain
    $filterChain->execute();
 
    // Code to execute after the action execution, before the rendering
    ...
  }
}

The default filter chain is defined in an application configuration file called filters.yml, and is shown in Listing 6-31. This file lists the filters that are to be executed for every request.

Listing 6-31 - Default Filter Chain, in myapp/config/filters.yml

rendering: ~
web_debug: ~
security:  ~

# Generally, you will want to insert your own filters here

cache:     ~
common:    ~
flash:     ~
execution: ~

These declarations have no parameter (the tilde character, ~, means "null" in YAML), because they inherit the parameters defined in the symfony core. In the core, symfony defines class and param settings for each of these filters. For instance, Listing 6-32 shows the default parameters for the rendering filter.

Listing 6-32 - Default Parameters of the rendering Filter, in $sf_symfony_data_dir/config/filters.yml

rendering:
  class: sfRenderingFilter   # Filter class
  param:                     # Filter parameters
    type: rendering

By leaving the empty value (~) in the application filters.yml, you tell symfony to apply the filter with the default settings defined in the core.

You can customize the filter chain in various ways:

• Disable some filters from the chain by adding an enabled: off parameter. For instance, to disable the web debug filter, write:

  web_debug:
    enabled: off
  

• Do not remove an entry from the filters.yml to disable a filter; symfony would throw an exception in this case.

• Add your own declarations somewhere in the chain (usually after the security filter) to add a custom filter (as discussed in the next section). Be aware that the rendering filter must be the first entry, and the execution filter must be the last entry of the filter chain.
• Override the default class and parameters of the default filters (notably to modify the security system and use your own security filter).

Building Your Own Filter

It is pretty simple to build a filter. Create a class definition similar to the one shown in Listing 6-30, and place it in one of the project's lib/ folders to take advantage of the autoloading feature.

As an action can forward or redirect to another action and consequently relaunch the full chain of filters, you might want to restrict the execution of your own filters to the first action call of the request. The isFirstCall() method of the sfFilter class returns a Boolean for this purpose. This call only makes sense before the action execution.

These concepts are clearer with an example. Listing 6-33 shows a filter used to auto-log users with a specific MyWebSite cookie, which is supposedly created by the login action. It is a rudimentary but working way to implement the "remember me" feature offered in login forms.

Listing 6-33 - Sample Filter Class File, Saved in apps/myapp/lib/rememberFilter.class.php

class rememberFilter extends sfFilter
{
  public function execute($filterChain)
  {
    // Execute this filter only once
    if ($this->isFirstCall())
    {
      // Filters don't have direct access to the request and user objects.
      // You will need to use the context object to get them
      $request = $this->getContext()->getRequest();
      $user    = $this->getContext()->getUser();
 
      if ($request->getCookie('MyWebSite'))
      {
        // sign in
        $user->setAuthenticated(true);
      }
    }
 
    // Execute next filter
    $filterChain->execute();
  }
}

In some cases, instead of continuing the filter chain execution, you will need to forward to a specific action at the end of a filter. sfFilter doesn't have a forward() method, but sfController does, so you can simply do that by calling the following:

return $this->getContext()->getController()->forward('mymodule', 'myAction');

Filter Activation and Parameters

Creating a filter file is not enough to activate it. You need to add your filter to the filter chain, and for that, you must declare the filter class in the filters.yml, located in the application or in the module config/ directory, as shown in Listing 6-34.

Listing 6-34 - Sample Filter Activation File, Saved in apps/myapp/config/filters.yml

rendering: ~
web_debug: ~
security:  ~

remember:                 # Filters need a unique name
  class: rememberFilter
  param:
    cookie_name: MyWebSite
    condition:   %APP_ENABLE_REMEMBER_ME%

cache:     ~
common:    ~
flash:     ~
execution: ~

When activated, the filter is executed for each request. The filter configuration file can contain one or more parameter definitions under the param key. The filter class has the ability to get the value of these parameters with the getParameter() method. Listing 6-35 demonstrates how to get a filter parameter value.

Listing 6-35 - Getting the Parameter Value, in apps/myapp/lib/rememberFilter.class.php

class rememberFilter extends sfFilter
{
  public function execute ($filterChain)
  {
      ...
      if ($request->getCookie($this->getParameter('cookie_name')))
      ...
  }
}

The condition parameter is tested by the filter chain to see if the filter must be executed. So your filter declarations can rely on an application configuration, just like the one in Listing 6-34. The remember filter will be executed only if your application app.yml shows this:

all:
  enable_remember_me: on

Sample Filters

The filter feature is useful to repeat code for every action. For instance, if you use a distant analytics system, you probably need to put a code snippet calling a distant tracker script in every page. You could put this code in the global layout, but then it would be active for all of the application. Alternatively, you could place it in a filter, such as the one shown in Listing 6-36, and activate it on a per-module basis.

Listing 6-36 - Google Analytics Filter

class sfGoogleAnalyticsFilter extends sfFilter
{
  public function execute($filterChain)
  {
    // Nothing to do before the action
    $filterChain->execute();
 
    // Decorate the response with the tracker code
    $googleCode = '
<script src="http://www.google-analytics.com/urchin.js"  type="text/javascript">
</script>
<script type="text/javascript">
  _uacct="UA-'.$this->getParameter('google_id').'";urchinTracker();
</script>';
    $response = $this->getContext()->getResponse();
    $response->setContent(str_ireplace('</body>', $googleCode.'</body>',$response->getContent()));
   }
}

Be aware that this filter is not perfect, as it should not add the tracker on responses that are not HTML.

Another example would be a filter that switches the request to SSL if it is not already, to secure the communication, as shown in Listing 6-37.

Listing 6-37 - Secure Communication Filter

class sfSecureFilter extends sfFilter
{
  public function execute($filterChain)
  {
    $context = $this->getContext();
    $request = $context->getRequest();
 
    if (!$request->isSecure())
    {
      $secure_url = str_replace('http', 'https', $request->getUri());
 
      return $context->getController()->redirect($secure_url);
      // We don't continue the filter chain
    }
    else
    {
      // The request is already secure, so we can continue
      $filterChain->execute();
    }
  }
}

Filters are used extensively in plug-ins, as they allow you to extend the features of an application globally. Refer to Chapter 17 to learn more about plug-ins, and see the online wiki (http://trac.symfony-project.org/) for more filter examples.

Module Configuration

A few module behaviors rely on configuration. To modify them, you must create a module.yml file in the module's config/ directory and define settings on a per-environment basis (or under the all: header for all environments). Listing 6-38 shows an example of a module.yml file for the mymodule module.

Listing 6-38 - Module Configuration, in apps/myapp/modules/mymodule/config/module.yml

all:                 # For all environments
  enabled:     true
  is_internal: false
  view_class:  sfPHP

The enabled parameter allows you to disable all actions of a module. All actions are redirected to the module_disabled_module/module_disabled_action action (as defined in settings.yml).

The is_internal parameter allows you to restrict the execution of all actions of a module to internal calls. For example, this is useful for mail actions that you must be able to call from another action, to send an e-mail message, but not from the outside.

The view_class parameter defines the view class. It must inherit from sfView. Overriding this value allows you to use other view systems, with other templating engines, such as Smarty.

Summary

In symfony, the controller layer is split into two parts: the front controller, which is the unique entry point to the application for a given environment, and the actions, which contain the page logic. An action has the ability to determine how its view will be executed, by returning one of the sfView constants. Inside an action, you can manipulate the different elements of the context, including the request object (sfRequest) and the current user session object (sfUser).

Combining the power of the session object, the action object, and the security configuration, symfony provides a complete security system, with access restriction and credentials. Special validate() and handleError() methods in actions allow handling of request validation. And if the preExecute() and postExecute() methods are made for reusability of code inside a module, the filters authorize the same reusability for all the applications by making controller code executed for every request.