Add an i18n Static Page to Symfony

My last post explained the basics on how to add static pages in symfony, this post expands on that and shows you how to do it for a multilingual site.

We split the template finding code out for code maintainability, and we enhance it on where to look for the file. First it tries to find the template in the language and country eg: en_CA, then it tries to find the template in the matching language, and if that is not found, it falls back to the default language.

/**
 * Load a static page.
 * @param sfRequest $request A request object
 */
public function executePage(sfWebRequest $request)
{
  $template = $this->findTemplate($request->getParameter('view'), $this->getUser()->getCulture());
  $this->forward404Unless($template);
  $this->setTemplate($template);
}

/**
 * Check if a template page exists for a given culture.
 * Be intelligent and check if language & country exist, try language, and then default to english.
 * @param string $name Template filename to check
 * @param string $culture Symfony culture string
 */
protected function findTemplate($name, $culture)
{
  // for safety, strip out all non-alphanumeric characters
  $name = preg_replace('/[^a-zA-Z0-9\s]/', '', $name);

  $directory = $this->getContext()->getModuleDirectory() . DIRECTORY_SEPARATOR ."templates";
  // try language and country: en_CA
  if (is_readable($directory . DIRECTORY_SEPARATOR . $culture. DIRECTORY_SEPARATOR . $name ."Success.php"))
  {
    return $culture. DIRECTORY_SEPARATOR . $name;
  }
  // try langage only: en
  elseif (is_readable($directory . DIRECTORY_SEPARATOR . substr($culture, 0, 2). DIRECTORY_SEPARATOR . $name ."Success.php"))
  {
    return substr($culture, 0, 2). DIRECTORY_SEPARATOR . $name;
  }
  // try default language
  elseif (is_readable($directory . DIRECTORY_SEPARATOR . $name ."Success.php"))
  {
    return $name;
  }
  return false;
}

The template directory should have the default language file as usual, eg: templates/helpSuccess.php, and then there should be folders for each language and possibly language & country with the same filename, but localized. eg: templates/fr/helpSuccess.php

Add a Static Page to Symfony

Static pages can be added to Symfony quite easily.

Edit your routing.yml file which is probably located at apps/frontend/config/routing.yml, and add the following routes to add an about, a privacy, and a terms and conditions page.

# static pages
about:
  url:   /about
  param: { module: home, action: page, view: about }
privacy:
  url:   /privacy
  param: { module: home, action: page, view: privacy }
terms:
  url:   /terms
  param: { module: home, action: page, view: terms }

If you are going to keep the generic rules, make sure you add these new rules before the default actions.

Clear your cache:
./symfony clear-cache

Then inside the module named home (create it if it doesn’t exist), add the following action:

  /** 
   * Load a static page.
   * @param sfRequest $request A request object
   */
  public function executePage(sfWebRequest $request)
  {
    $directory = $this->getContext()->getModuleDirectory().DIRECTORY_SEPARATOR."templates";
    $name = $request->getParameter('view');
    // for safety, strip out all non-alphanumeric characters
    $name = preg_replace('/[^a-zA-Z0-9\s]/', '', $name);
    if (is_readable($directory.DIRECTORY_SEPARATOR.$name."Success.php"))
    { 
      return $this->setTemplate($name);
    }
    else
    { 
      $this->forward404();
    }
  }

The template files will be on the home/templates directory, called aboutSuccess.php, privacySuccess.php, and termsSuccess.php

This action will check if the template file exists, and if so load the template, if not it will forward to the 404 not found page. Easy and safe static templates. Add more routes and the appropriate template file as required.

Debugging Form Errors in symfony 1.3+

Symfony 1.3 (or symfony 1.4) provides an incredibly helpful feature to help debug forms. This new feature is included in the developer toolbar and shows valuable information about the forms on the page. To access the detailed form information, click on the view button, click on the template or partial that the form is in, and then click to expand the form. It lists each form widget and if any errors for a given widget exist they are shown right under it. Errors are also highlighted to make them easy to spot.

The symfony debug toolbar will look like this when there is a validation error in one of the forms on the current page. This is one of the most incredibly useful features I’ve seen and greatly improves productivity while building forms in the symfony framework. Congratulations to the symfony developers who came up with this tool!

Have symfony 1.1 or 1.2? read catch symfony form errors.

An Alternative to symfony’s schema.yml

The symfony web framework provides two methods for building the database model files when using the Propel Object-relational mapping (ORM) toolkit. The recommended method by the symfony team is to use the schema.yml file, where you explicitly explain your table structure. The second method is to generate a schema.xml file directly from the database.

schema.yml:symfony schema yml

Just edit config/schema.yml and list your tables, columns, column types, and foreign keys in YAML form. Build the model files by running:

./symfony propel-build-model

Pros:

  • Interfaces better with plugins because most, if not all, plugins use the schema.yml method
  • Can be used to create the database tables
  • Overall easier to use because it is the most common method

Cons:

  • Requires duplicate data by having the database structure in a text file, which can be outdated when the database is updated directly

schema.xml:

To create the model files simply run:

./symfony propel-build-schema xml
./symfony propel-build-model

Pros:

  • Supports ALL  database features
  • Supports the most complex schemas

Cons:

  • Errors while building the XML file are cryptic and time consuming to track down (eg: om-template)

Comparison

The schema.yml method supports most projects with relative ease, but is limiting if you need to use more advanced database features that are not supported (propel only supports limited column types). Although, there are tricks to get around these limitations. For example, if you need to use column types that aren’t supported, like ENUM, you can simply declare the column as a varchar and Propel won’t know any better. This works fine for ENUM because it’s simply a text field, but may work for other column types too.

I recommend the schema.xml file for projects that have a very complex schema that cannot be represented in the yml file, or for projects already using XML files to define the database scheme.

I have used both methods on different large projects and have found the schema.yml method to provide faster  application development, have more developer support, and easier to work with. I full recommend use of the schema.yml method in all but the most exceptional projects.

Catch Symfony Form Errors

Have you built a form while developing with the symfony form framework that appears to work fine but fails because of an unknown error? Here is the simplest and easiest way to catch most errors.

First open the web page with the form and fill it in with valid input. Then, open the form php file, temporarily delete all your custom form render code and replace it with echo $form. Go back to the web page and click your form submit button. It should show you any validation errors that appear in the form but were missing on your customized version, because this time it’s rendering the form with the default settings. At the very least it could show you something you missed and hint at the solution.

Your test form would look like this:

<form action="<?php echo url_for('user/'.($form->getObject()->isNew() ? 'create' : 'update').(!$form->getObject()->isNew() ? '?id='.$form->getObject()->getId() : '')) ?>" method="post" <?php $form->isMultipart() and print 'enctype="multipart/form-data" ' ?>>
<table>
  <tfoot>
  <tr>
    <td>
      <?php echo $form->renderHiddenFields() ?>
      <input type="submit" value="Save">
    </td>
  </tr>
  </tfoot>
  <tbody>
    <?php echo $form ?>
  </tbody>
</table>
</form>