Can the Symfony Forms Framework be Domesticated? A Simple Todo List

Please stop crapping on my carpet

you can trust me...

The modest task that is our charge

Today we're going to create a very simple todo list. I've purposefully left out all the bells and whistles. I need to crawl before I walk. Notice that I always give you 3 boxes for new todo items. I choose that arbitrarily and to keep things simple.

Our simple todo list

The Very Simple Setup

Simple: our module is called "todo" and we have the following schema. All of this code is common to almost any situation.

schema.yml:

propel:
  todo:
    _attributes:    { phpName: Todo }
    id:
    task:           varchar(255)

actions.class.php

class todoActions extends sfActions
{
  public function executeSimple(sfWebRequest $request)
  {
    $this->form = new simpleTodoForm();
  }
  
  public function executeSimpleProcess(sfWebRequest $request)
  {
    $this->form = new simpleTodoForm();
    
    if($request->isMethod('post'))
    {
      $this->form->bind($request->getParameter('todo_list'));
      if($this->form->isValid())
      {
        $this->form->save();
        $this->redirect('todo/index');
      }
    }
    
    $this->setTemplate('simple');
  }
}

TodoForm.class.php

class TodoForm extends BaseTodoForm
{
  public function configure()
  {
    unset($this['id']);
  }
}

Background - Symfony's embedForm method

Let me talk for a moment about Symfony's mysterious, powerful and aggravating embedForm method. As it sounds, the embedForm method allows you to essentially combine many forms into one form. More accurately, the embedForm method creates a hierarchy inside your form that functions almost like a multi-level array. It does this all very nicely, but causes some confusion along the way.

The Forms

As you can see in the above code, we are using a form called simpleTodoForm. Create this form from scratch (simpleTodoForm.class.php) and place it somewhere appropriate (e.g., create a form directory inside your application's lib folder and place it in there). Here's where we start

simpleTodoForm.class.php
  
class simpleTodoForm extends sfForm
{
  public function configure()
  {    
    $todoWrapperForm = new sfForm();
    foreach(TodoPeer::doSelect(new Criteria()) as $todo)
    {
      $todoWrapperForm->embedForm($todo->getId(), new TodoForm($todo));
    }
    // add 3 blank todos (the #3 was chosen arbitrarily)
    $todoWrapperForm->embedForm('new_1', new TodoForm());
    $todoWrapperForm->embedForm('new_2', new TodoForm());
    $todoWrapperForm->embedForm('new_3', new TodoForm());
    
    $this->embedForm('todos', $todoWrapperForm);
    
    $this->widgetSchema->setNameFormat('todo_list[%s]');
  }
}

Visualizing our Forms

On the surface: Our form displays multiple "todo" text boxes
Under the hood: Our form embeds multiple TodoForm forms

(left) Our 3 levels of forms      (right) The output of those forms

Back to the code

Keeping in mind the above model, the configure() code above makes more sense. First, I create a new sfForm called $todoWrapperForm. This intermediate form is here only for organization and serves no other purpose. I could have embedded my TodoForm forms directly to simpleTodoForm, but (as you'll see) my method makes life easier down the road.

One more quick comment. The first argument in the embedForm method is the name to give the form, and is used in the actual name attribute of the resulting form elements. In this case, the names don't matter too much - they'll just be used as keys later to retrieve the data and save the Todo objects. To prevent any weirdness (like if concurrent users were adding/removing todos), I use the primary key of the existing Todo items as their names. For the new todo items, I simply give them the arbitrarily chosen names new_1, new_2, and new_3. You'll see later how I use this to save our todo items.

The View

<form action="<?php echo url_for('todo/simpleProcess'); ?>" method="post">
  <?php echo $form->renderGlobalErrors(); ?>
    
  <?php foreach($form['todos'] as $fieldSchema): ?>
    <?php echo $fieldSchema['task']->render(); ?>
    <?php echo $fieldSchema['task']->renderError(); ?>
  <?php endforeach; ?>
    
  <?php echo $form['_csrf_token']; ?>
  <input type="submit" value="save" />
</form>

This rings of the simplicity that I've been looking for. With the exception of the foreach statement in the middle, most forms will have these essential parts.

Remember that our embedded forms work like a multilayered array. In fact, our form functions exactly like the array I've constructed below. Notice how each of our 3 forms is represented as an array here:

array(
  '_csrf_token' => new sfWidgetInput(...),
  'todos' => array(
    'new_1' => array(
      'task' => new sfWidgetInput(...),
    ),
    'new_2' => array(
      'task' => new sfWidgetInput(...),
    ),
    'new_3' => array(
      'task' => new sfWidgetInput(...),
    ),
  ),
)

It's with this in mind that we render our form in the manner above. By creating a foreach loop through the $form['todos'] elements, we're actually going through each of our embedded TodoForm forms one by one. We then output the elements of our TodoForm form just like we normally would if it were a standalone form. In this (unique) case, our TodoForm forms only have one widget, called task. So, all we have to do is output our task widget. I omitted the common renderRow() command here, instead using render() and renderError(). I did this simply for aesthetics: I didn't want to use the element's label tag in this case.

Saving all the objects

If you were to comment out the $this->form->save() call in the simpleProcess action, you'd find that you have a multilayered form that binds and validates as you'd expect. In fact, it should do everything except actually save your new Todo objects. Add this:

class simpleTodoForm extends sfForm
{  
  ...
  public function save()
  {
    $values = $this->getValues();
    
    foreach($this->embeddedForms['todos']->getEmbeddedForms() as $key=>$todoForm)
    {
      if ($values['todos'][$key]['task'])
      {
        // only save todos that aren't blank
        $todoForm->updateObject($values['todos'][$key]);
        $todoForm->getObject()->save();
      } elseif(!$todoForm->getObject()->isNew()) {
        // delete any existing todos that are now blank
        $todoForm->getObject()->delete();
      }
    }
  }
}

The world is 2 worlds

We've entered the twilight zone of saving embedded forms. Although you've probably never realized the division, here are the 2 very separate worlds of embedded forms:

1. Parent form: Propel/Doctrine form
   Embedded forms: Propel/Doctrine forms related to the parent form by some foreign key
   To save: Simply call the parent's save() method, which automatically saves all the embedded forms
2. Parent form: some normal sfForm form that holds everything together
   Embedded forms: A group of Propel/Doctrine forms (e.g., you're adding many Todo objects at once)
   To save: Since the parent form has no save() method, you must cycle through all the subforms, update their Propel/Doctrine objects, and save those objects

Obviously, we fall into world #2. The foreach statement is designed to cycle through each of our original TodoForm forms in very much the same way that we used a foreach statement to cycle through them in our view. The difference in those foreach statements is due to some underlying mechanics of the embedForm method. If you're interested, keep reading below.

Each $todoForm in our foreach must first have its object updated (updateObject()) then saved (getObject()->save()). These two statements have really nothing to do with the Forms world: they simply update each Todo object with the input data. The extra if/then statement used here is just to make things work a little better: I don't want to save new Todo objects if their task is blank and I want to delete any existing Todo items whose task has been deleted (made blank).

Summary

Creating a simple todo form really can be simple once you get the hang of it. Forms, which act just like arrays, can be used to help organize your overall form through the embedForm method. The most confusing thing about embedForm is exactly how to then output your embedded forms and save them. Using the above as a guide, you should be in good shape. If you ever get confused, remember to view your forms as an array - they truly function in this way.

One stumbling block is the fact that, to access your embedded forms, you must use a different foreach statement in your view than in the form itself. Specifically, when you need to access an embedded form's widgets (for the purpose of outputting them), you should use the method used in the view. However, when you need to access the embedded form object itself, you should use the method seen in the form's save() method. There's a very good reason for this, but it confused the hell out of me. If you want to learn me, see my explanation below.

There's black magic in those forms

Behind the scenes of this embedForm business, some black magic is hiding, and it's a bit difficult to explain. The underlying weirdness, as eluded to in the above paragraph, is that you must use a different foreach statement depending on whether you want to get at the embedded form's widgets or the form object itself. Another place of weirdness is why I used updateObject() and getObject()->save() to save my embedded forms instead of using their prebuilt save() methods. What gives?

What really happens when you embed a form

The explanation lies in what really happens when you embed a form. To be straightforward, if you use embedForm to embed form B into form A, the Widget schema and Validator schema of form B are copied into form A. That's it. The embedded form itself (form B) isn't actually used. Instead, the widgets and validators for form B become part of form A. Most importantly, when data is bound to form A, that data is passed through to all its validators, which now include the validators originally from form B. Very importantly, however, is the fact that form B itself is never bound to the data. As far as validation and errors are concerned, everything works perfectly. Since all of form B's validators have become part of form A, they all throw their validation errors correctly. The added complication occurs when you try to save the embedded form B.

Let's go back to our save() method and propose a new piece of (incorrect) code:

// Original code to save the embedded Todo forms:
  $todoForm->updateObject($values['todos'][$key]);
  $todoForm->getObject()->save();

// My incorrect what-if proposed code to save the embedded Todo forms:
  $todoForm->save()

Remember that the $todoForm was embedded into our simpleTodoForm form (through an intermediate form - there were 3 layers in total). That means that its widgets and validators became a part of simpleTodoForm. It also means that $todoForm was never actually bound. So, if you try to save $todoForm, you'll get a nasty error because that form hasn't actually been bound with the input data. There is a disconnect between embedded form objects and the data bound to their parent form. Because of this fact, we must update then save the embedded form's object.

Some of you my be wondering, as I did, if there is a security concern with simply updating then saving the objects on these unbound, embedded forms. Fear not. Even though the form objects themselves are unbound, the forms' validators have still been passed the input data and thrown validation errors as necessary (because a bound form's validators become part of the main form).

Going back to my 2 worlds of embedded forms above, some of you may be wondering how Symfony handles everything so smoothly in world #1. The answer: Symfony uses the exact method I propose above for world #2 - it just does it all behind the scenes.

Final Words

Can the Symfony forms framework be domesticated and become helpful in 100% of the situations? I answer a resounding yes. To begin, it HAS to work - the old system is terribly inferior to this one, even if this system has some learning curves. I hope that this article, despite its complex details, will show that the forms framework can approach these types of situations without choking. Like any great system, we've just gotta figure out how to use it right.

Happy embedding, good luck and good night.

Attachments