How to build a basic contact form in symfony

Forms in symfony bring some fun to the table. They’re very, very powerful, but you have to know how to ask them, and figuring that out isn’t always the easiest thing. I have worked with forms extensively for the past several weeks, and primed with this knowledge, I believe I can show you a pretty solid way to start building customized forms.

We’re going to have six pieces building our contact form:

  1. Setup — We make our module
  2. Preparation — I have a helpful function for you to add to your BaseForm class that makes things easier later on
  3. Form — We build our form
  4. Action — We build the action to handle our form
  5. Templates — We build two templates to handle our contact form, the form page, and the thank you page.
  6. Routing — All this hard work, let’s make it look nice!

So with that being said, let’s get on the road to enlightenment!

1. Setup

At this point, I assume the following:

  • You have a working symfony install
  • You have an app named ‘frontend’

If you haven’t made a module before, you’re about to expand your horizons!

./symfony generate:module frontend contact_form

This will create apps/frontend/modules/contact_form, and related subdirectories.

2. Preparation

I promised you a helpful addition to your BaseForm class, and along with that, I will offer an explanation.

The sfForm class (and it’s children) will allow you to easily get only hidden fields, but it doesn’t offer you a simple way to allow you to easily get only visible fields. This little function solves that inequity.

  public function getVisibleFields()
  {
    $hidden_fields = $this->getFormFieldSchema()->getHiddenFields();
    $fields = array();
    foreach($this as $name => $field)
    {
      if (!in_array($field, $hidden_fields))
        $fields[$name] = $field;
    }
    return $fields;
  }

If you have nothing else added to your BaseForm.class.php file (lib/form/BaseForm.class.php), it will look like:

<?php
 
/**
 * Base project form.
 *
 * @package    your-package
 * @subpackage form
 * @author     YourNameHere
 * @version    SVN: $Id: BaseForm.class.php 20147 2009-07-13 11:46:57Z FabianLange $
 */
class BaseForm extends sfFormSymfony
{
  public function getVisibleFields()
  {
    $hidden_fields = $this->getFormFieldSchema()->getHiddenFields();
    $fields = array();
    foreach($this as $name => $field)
    {
      if (!in_array($field, $hidden_fields))
        $fields[$name] = $field;
    }
    return $fields;
  }
}

3. Form

For our contact form, we’ll have Name, Email, and Comments. Name and Email will be input fields, and Comments will be a text area. All fields will be required. Let’s take a look at what that form looks like:

lib/form/PublicContactForm.class.php

<?php
 
class PublicContactForm extends BaseForm
{
  public function setup()
  {
    // this is required, don't forget this!
    $this->widgetSchema->setNameFormat('contact_form[%s]');
 
    $this->setWidget('name', new sfWidgetFormInput());
    $this->setValidator('name', new sfValidatorString(array('required' => true)));
 
    $this->setWidget('email', new sfWidgetFormInput());
    $this->setValidator('email', new sfValidatorEmail(array('required' => true)));
 
    $this->setWidget('comments', new sfWidgetFormTextarea());
    $this->setValidator('comments', new sfValidatorString(array('required' => true)));
 
    parent::setup();
  }
}

Why did I use Public in the name? It reminds me that it’s a public facing form, most likely using a custom-ish template, which I may need to update if I change the form much.

4. The Action

Here’s a hearty chunk of where we’re going to end up. Let’s start by taking a look at the final form of the file, and then we’ll highlight portions.

apps/frontend/modules/contact_form/action/action.class.php

<?php
 
/**
 * contact_form actions.
 *
 * @package    your-project
 * @subpackage contact_form
 * @author     Jacob Mather
 * @version    SVN: $Id: actions.class.php 23810 2009-11-12 11:07:44Z Kris.Wallsmith $
 */
class contact_formActions extends sfActions
{
 /**
  * Executes index action
  *
  * @param sfRequest $request A request object
  */
  public function executeIndex(sfWebRequest $request)
  {
    $this->form = new PublicContactForm();
    if ($request->hasParameter('contact_form'))
    {
      // we're getting the parameters for the form, let's bind and see what happens
      $this->form->bind($request->getParameter('contact_form'));
 
      if ($this->form->isValid())
      {
        $values = $this->form->getValues();
        $text_msg = 'You have received a message!'."\r\n\r\n";
        $html_msg = 'You have received a message!<br /><br />';
        foreach($values as $name => $value)
        {
          $text_msg .= $name.':'."\r\n".$value."\r\n\r\n";
          $html_msg .= $name.':<br />'.$value.'<br /><br />';
        }
        $text_msg .= 'Thanks!';
        $html_msg .= 'Thanks!';
 
        $from = array('my-app@example.com' => 'My Application');
        $to = array('replace-with-your-email@example.com');
 
        $message = $this->getMailer()->compose($from, $to, 'Contact Form Submission');
        $message->setBody($html_msg, 'text/html');
        $message->addPart($text_msg, 'text/plain');
        $this->getMailer()->send($message);
 
        $this->getResponse()->setTitle('Thanks for contacting me');
        return 'Thanks';
      }
    }
    $this->getResponse()->setTitle('Contact Me');
    return 'Form';
  }
}

I think you’ll find the form pretty self explanatory, though I’ll cover a couple things.

The first thing to point out, I didn’t return sfView::SUCCESS, or sfView::ERROR. Why not? Simple. I wanted to keep the names of the files within the context of what they’re doing. We have two views we will use, the form, and the thank you page, so we will use two templates, indexForm.php, and indexThanks.php. I think that keeps things pretty obvious, how about you?

The next thing to point out, is we’re just using a single action! Why? Well, why do we need more than one action? We need the form object to display an error, and we can easily detect if someone has submitted the form (that is what $request->hasParameter(‘contact_form’) does), so why not just roll it into one compact bit.

Lastly, yes, I put a lot of effort into the outgoing emails. I always send an HTML and a plaintext part. It’s my personal preference, but it takes so little effort to deliver a professional solution even in a simple example, it feels sloppy not to.

5. The Templates

As I mentioned in the last section, we need two templates. indexForm.php and indexThanks.php.

apps/frontend/modules/contact_form/templates/indexForm.php

<style>
  .contact-form li { list-style: none; margin-bottom: 10px; }
  .error_list { padding: 0px; }
  .error_list li { background-color: red; color: white; font-weight: bold; padding: 3px;}
</style>
<?php echo $form->renderFormTag(url_for('contact_form/index')); ?>
<?php echo $form->renderGlobalErrors(); ?>
<?php echo $form->renderHiddenFields(); ?>
<ul class="contact-form form">
<?php foreach($form->getVisibleFields() as $name => $field): ?>
  <li>
    <?php echo $field->renderError(); ?>
    <?php echo $field->renderLabel(); ?>
    <div class="value"><?php echo $field->render(); ?>
    <span class="help"><?php echo $field->renderHelp(); ?></span></div>
  </li>
<?php endforeach; ?>
  <li><input type="submit" value="Submit Contact Form" /></li>
</ul>
</form>

apps/frontend/modules/contact_form/templates/indexThanks.php

<p>Thanks for contacting me!</p>

As you can see, it’s a pretty simple setup. I did some inline styles for the form, though in a larger project you would want those to be in a stylesheet include. The indexForm.php should serve you well as a base for further forms, as it includes support for a few things we don’t use in this form (help, global errors), which should help you make things ‘just work’ in the future.

6. Routing

Ok, so we’ve made everything, set it up, made it look visually nice enough to not want to stab our eyes out too much, now it’s time to put the icing on the cake: the route.

This is real simple. Open apps/frontend/config/routing.yml

contact_form:
  url: /contact-me
  param: { module: contact_form, action: index }

And you’re all set! Clear your cache, and you’re ready to go:

./symfony cc

Now navigate to your /contact-me page, and you will see your contact form!

Let’s try something a little new, and show a screencast of the finished product! Let me know how you like it!

It’s “symfony” not “Symfony”. Whoops.

Apparently I have been misusing the symfony name. It is “symfony” not “Symfony”, not “Symfony 1”, just “symfony”. I recently went through a slideshow by Kris Wallsmith. Ten of the first thirteen slides are dedicated to this. Anyone else find that oddly statistically significant?

I am terribly sorry, I beg forgiveness, please let me keep my fingers!

Ok, that’s over. Phew. 🙂

Taking base_convert past base 36

When building my URL shortener, ZapX, I ran into a bit of a problem. I wanted to be able to make the shortest possible urls using the characters 0-9, a-z, and A-Z, otherwise known as base 62.

PHP’s native base_convert only goes up to base 36, so I was forced to resort to my own devices to get the job done. Long story short, here’s one that goes up to base 62:

function extended_base_convert($dec, $base)
{
 $numchart = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
 $min_base = 2;
 $max_base = strlen($numchart);
 if ($base < $min_base || $base > $max_base)
  return 'N/A';
 $value = $dec;
 $ptr = ceil($value / $base);
 $buf = array();
 do {
  $buf[$ptr] = substr($numchart, ($value % $base), 1);
  $value = intval($value / $base);
  $ptr--;
 } while ($value > 0);
 $buf = array_reverse($buf);
 return implode('', $buf);
}

Taking cache invalidation further…

Someone pointed out to me (quite correctly) that while the solution I offered before would work, it wasn’t testable, so I just wanted to make a quick note on how I would solve that.

The easiest solution I see, would be using the Symfony Event system.

For the sake of simplicity, I’m going to keep the listener and init code within the object. I feel it keeps maintainability better, and it allows for easy mock extension and overriding with explicit test code.

WARNING: I have not played with events yet. This is how I see it playing out, but I’m sure this steps on a few best practices. Feel free to let me know if you have a better implementation idea and I will update this page or give you a direct reference to your blog, whichever you prefer.

Here’s how I see the Model looking with this change:

<?php
 
class MyObject extends Doctrine_Record
{
  public function setUp()
  {
    parent::setUp();
    static::initEventListener();
  }
 
  protected static $listenerInitialized = false;
  public static function initEventListener()
  {
    if (ProjectConfiguration::hasActive() && self::$listenerInitialized == false)
    {
      static::doInitEventListener();
      self::$listenerInitialized = true;
    }
  }
  public static function doInitEventListener()
  {
    $dispatcher = ProjectConfiguration::getActive()->getEventDispatcher();
    $dispatcher->connect('MyObject.object_updated', array('MyObject', 'clearCacheEntries'));
  }
  // We could force-type this to sfEvent, but we don't /actually/ look at the event object...
  //so there is no need to require it.
  public static function clearCacheEntries($event = null)
  {
    cacheAssistant::clearCachePattern('**/**/pages/index');
  }
 
  private $pendingChangeNotification= false;
  public function preSave($event)
  {
    if ($this->isModified())
      $this->pendingChangeNotification= true;
  }
  public function postSave($event)
  {
    if ($this->pendingChangeNotification && ProjectConfiguration::hasActive())
    {
      $dispatcher = ProjectConfiguration::getActive()->getEventDispatcher();
      $dispatcher->notify(new sfEvent($this, 'MyObject.object_updated'));
      $this->pendingChangeNotification= false;
    }
  }
}

This way, you could even attach a mock event listener by overriding doInitEventListener to attach a different processor to the event, or overriding clearCacheEntries. It does add quite a bit of complexity to the setup, but if you’re concerned about testability, this would let you accomplish the same goals.

Invalidating old cache content on dynamic data in Symfony

Here’s just a quick note for those of you working with caching solutions for dynamic data in Symfony.

Update: If testability is a concern, please read the follow up to this article.

One of the challenges with caching is deciding where the limit is. What’s worth caching, and what isn’t. Because cleaning up that old data is hard… isn’t it?

Not so much!

You just need to make a helper and a checks, and you’ll be expertly picking out the templates to invalidate!

The first hurdle with clearing out invalid data, is that usually your backend is separate from the frontend, so it’s a non-trivial reach to try and invalidate cache files of other applications. Or is it?

<?php
 
class cacheAssistant
{
  public static function clearCachePattern($pattern)
  {
    $envs = array('prod', 'dev');
    $apps = array('backend', 'frontend');
    foreach($envs as $env)
    {
      foreach($apps as $app)
      {
        $app_cache_dir = sfConfig::get('sf_cache_dir').DIRECTORY_SEPARATOR.$app. DIRECTORY_SEPARATOR.$env.DIRECTORY_SEPARATOR.'template';
 	$cache_vars = array(
          'cache_dir' => $app_cache_dir,
   	  'cache_key_use_vary_headers' => true,
          'cache_key_use_host_name' => true,
        );
        $cache = new sfFileCache($cache_vars);
        $cache->removePattern($pattern);
      }
    }
  }
}

Your $cache_vars will differ depending on your cache settings, but essentially, that’s your main helper setup.

Now here’s what I use in my objects for cache clear detection:

<?php
 
class MyObject extends Doctrine_Record
{
  private $pendingClearCacheEntries = false;
  public function preSave($event)
  {
    if ($this->isModified())
      $this->pendingClearCacheEntries = true;
  }
  public function postSave($event)
  {
    if ($this->pendingClearCacheEntries)
    {
      $this->clearCacheEntries();
      $this->pendingClearCacheEntries = false;
    }
  }
  public function clearCacheEntries()
  {
    cacheAssistant::clearCachePattern('**/**/pages/index');
  }
}

Of course, your patterns will change depending on your cache options (I.e. I use the **/** because I have enabled cache_key_use_host_name, other settings may not accept this pattern.)

Happy caching, and if you have any questions, feel free to let me know!

twitter