New in symfony 1.2: Error Templates and Request Formats

symfony 1.1 introduced native support for different formats and mime-types.

But there was one missing piece: error support. That's fixed in symfony 1.2, thanks to the great work of Kris Wallsmith. He created a plugin to implement this feature. His plugin was later integrated into the core and further enhanced.

So, symfony 1.2 now respects the current request format when rendering any uncaught exception.

Let's take an example to make it easier to explain. You have an application with an API module which returns an HTML, XML, or JSON representation of the Article model.

Here is the routing configuration that makes it work:

// apps/frontend/config/routing.yml
api_article:
  url:   /api/article/:id.:sf_format
  param: { module: api, action: article }
  requirements:
    sf_format: (?:html|xml|json)
 

And the associated module:

class apiActions extends sfActions
{
  public function executeArticle($request)
  {
    $this->article = ArticlePeer::retrieveByPK($request->getParameter('id'));
 
    $this->forward404Unless($this->article);
  }
 
  // ...
}
 

If you pass a non existent id in the request, the action is forwarded to the 404 page. If you use the HTML format (http://localhost/frontend_dev.php/api/article/1.html) in the development environment, you will have an error message that looks like this:

404.html in the development environment

In the production environment (http://localhost/frontend_dev.php/api/article/1.html), the page is quite different for obvious security reasons:

404.html in the production environment

Now, let's see how it behaves when we change the format to XML in the development environment (http://localhost/frontend_dev.php/api/article/1.xml):

404.xml in the development environment

And now, in the production environment (http://localhost/api/article/1.xml):

404.xml in the production environment

As you can see for yourself, the error message returned by symfony is now in the requested format, XML.

This example demonstrates how the error messages are customized for a 404 page, but the same goes for any other uncaught exception.

You can even customize each format's output by adding a template to your project directory (config/error/) or application directory (apps/frontend/config/error/).

For example, to customize the output for XML error messages, create a config/error/error.xml.php file. symfony is smart enough to use the customized template if it exists instead of the default one:

<?xml version="1.0" encoding="<?php echo sfConfig::get('sf_charset', 'UTF-8') ?>"?>
<error>
   <code><?php echo $code ?></code>
   <message><?php echo $text ?></message>
</error>

404.xml customized in the production environment

When you customize an error message template, you have access to the following variables:

  • $code: The response status code
  • $text: The response status text
  • $name: The class name of the exception
  • $message: The message of the exception message
  • $traces: An array containing the full PHP trace
  • $format: The requested format

It is also possible to customize the output in the development environment, even if it is a bit less interesting, by creating a config/error/exception.xml.php.

The default templates are stored in the lib/exception/data/ directory of symfony and are a good starting point for your customized templates.

When you create your very own format, you will need to create the appropriate error message templates (config/error/error.FORMAT_NAME.php and config/error/exception.FORMAT_NAME.php).

To ease the task, you can include an existing error template. For example, if your format is XML like, you can include the default XML error message template:

<?php include sfException::getTemplatePathForError('xml', true) ?>
 

Format support is yet another example of symfony 1.2 embracing HTTP as much as possible.

Comments

http://sfweb/fo_dev.php/blog/2008/06/09/how-to-create-an-optimized-version-of-your-website-for-the-iphone-in-symfony-1-1 ??
This is really useful! Great work .. :)
The first link should be:

http://www.symfony-project.org/blog/2008/06/09/how-to-create-an-optimized-version-of-your-website-for-the-iphone-in-symfony-1-1
I don't want to start the "short tags flame", but the current default xml templates cause parse error with short tags on.

Replacing the first line with the following would solve the problem.


Zoltan> you should never set short_tags on
As I said I don't want a flame to begin...
I just wanted to point out, that as soon as someone moves his project to a server, where short tags is on, the templates will cause an error.
Zoltan> Okay. But you should never set short_tags on =)
But how could I find out that the code would fail if I switched short tags on, if I didn't switch short tags on ? :)
@Zoltan Lajos Kis: I have changed XML templates to also work when short_tags are on.
just checking

Comments are closed.

To ensure that comments stay relevant, they are closed for old posts.