Redo The Web

It’s Oh So Quiet

Francois Zaninotto — Thu, 30 Oct 2008 08:24:48 +0000

It’s so quiet in this blog, because it is closed. Forever. No more post will ever be published, you can’t send any comment, and you can unsubscribe safely from its RSS feed. More than 8,000 unique visitors a month now have time to procrastinate elsewhere.

I have finally admitted that I have better things to do in my free time than contributing to the symfony project. So I can say goodbye to all the following, without regret:

Writing a book,
Publishing 54 blog posts here and a certain amount in the symfony project blog,
Reading 715 comments here and countless emails in the symfony mailing-lists,
Following the symfony timeline every day, and reviewing the code contributed to the framework core,
Developing, testing, and documenting more than 20 plugins,
Giving a few conferences and trainings,
And helping newcomers find their way in the symfony ecosystem via IRC, chat, and email.

You can’t imagine how much time all that takes. Well, that’s how much free time I get by leaving symfony completely.

Since summer 2005, my involvement in symfony has been more and more thorough, more and more visceral, and more and more painful. I did my best to push symfony in the direction that I considered to be the right one, but I failed. Symfony used to be simple, well documented, and powerful; today it’s just powerful. Long forgotten are the days where symfony’s motto was “Professional Tools for Lazy Folks”. I see no future in a project where release dates are never satisfied, where new features are released undocumented, where discussions either never start or die without a generally accepted decision, where the community is tolerated only for its praises, and most of all, where the average user is despised.

If you use any of the symfony plugins that I developed and maintained, and if you want to contribute back to their code, you should contact Kris Wallsmith, the new symfony community manager. He’s responsible for these plugins now, and will give developer access at his own discretion. As for me, I may use my commit access for modifications regarding the projects I work on, without further notice.

DbFinderPlugin
sfAssetsLibraryPlugin
sfControlPanelPlugin
sfFeed2Plugin
sfMediaLibraryPlugin
sfModerationPlugin
sfPagerNavigationPlugin
sfPropelActAsSortableBehaviorPlugin
sfPropelAlternativeSchemaPlugin
sfPropelSpamTagBehaviorPlugin
sfSimpleBlogPlugin
sfSimpleCMSPlugin
sfSimpleForumPlugin
sfSpyPlugin
sfStatsPlugin
sfUFOPlugin
sfUJSPlugin
sfWebBrowserPlugin

Redoing the web was an ambitious task. Who knows, I might still manage to do it in the future.

The Good, The Bad and the Ugly

Francois Zaninotto — Wed, 08 Oct 2008 07:39:31 +0000

There is a lot to learn from Fabien Potencier, the creator of the symfony framework. He often comments people's work on other frameworks, but almost never when someone works on his own framework. So his recent reaction about my DDD experiment is rare enough to be thoroughly analyzed, and distilled. Let's look for the very substance of his latest post.

The Good

It's been more than ten months since my original Forms post, about which Fabien basically told me that I knew nothing about programming (which is true) but nothing else. So I'm very glad that he finally decided to give more feedback about the ideas I suggest. My previous post asked for developers' thoughts about a reworked Chapter 10, and who could better do this than him?

Not only does Fabien talk about my DDD experiment, he actually implemented some features I suggested. Thanks to commits made to the symfony 1.2 branch early this week, building a form object using the sfForm class alone is easier. Added is the ability to define default values for each widget, the ability to iterate on a form object, the ability to directly set a widget or a validator from the from object. I proposed all those changes to make the documentation easier to read (and write), and it seems that they also have an interest for the developers.

Fabien points some mistakes I did, like the 'multiple' validator, which is a bad idea. Since there are two kinds of multiple validators (on the uncleaned value and on the cleaned value), the 'multiple' keyword is not the best choice. I still thing that 'pre' and 'post' validators could get a better name, but that's a detail.

Also, the modified version of my proposed Chapter 10, published as an attachment to Fabien's post, keeps about 90% of the original text unchanged. It seems that he disagrees mostly on some technical details, and didn't touch the order in which things were introduced, nor the length of the Chapter.

The Bad

But the idea to define form widgets and validators based on an associative array got no credit to his eyes. It is probably a matter of preference; I introduced this array syntax for two reasons:

To avoid introducing too many classes too early in the documentation
To make the YAML form definition syntax completely natural

To my eyes, this array syntax has always been a layer on top of the existing syntax; that means that the ability to define custom widgets and validators is still there, and the ability to pass an object instead of an associative array is still there as well. That's how I tried to remove the coding style preference problem: whatever you like more, symfony supports it. You get both simplicity of use and power.

"[The suggested API] is not shorter, it is not easier to understand, and it is more difficult to explain.". Let me respectfully disagree. It is shorter, easier to understand, and easier to explain. Compare what a single chapter explains and the confusion introduced by an unfinished and lengthy book. Or better, compare:

// in PHP

class ContactForm extends sfForm
{
protected static $subjects = array('Subject A', 'Subject B', 'Subject C');

public function configure()
{
$this->widgetSchema->setNameFormat('contact[%s]');
$this->widgetSchema->setIdFormat('my_form_%s');
$this->setWidgets(array(
'name' => new sfWidgetFormInput(),
'email' => new sfWidgetFormInput(),
'subject' => new sfWidgetFormSelect(array('choices' => self::$subjects)),
'message' => new sfWidgetFormTextarea(),
'file' => new sfWidgetFormInputFile(),
));

$this->setValidators(array(
'name' => new sfValidatorString(array('required' => false)),
'email' => new sfValidatorEmail(),
'subject' => new sfValidatorChoice(array('choices' => array_keys(self::$subjects))),
'message' => new sfValidatorString(array('min_length' => 4), array('min_length' => 'Your message is too short')),
'file' => new sfValidatorFile(),
));
$this->setDefault('email', 'me@example.com');
}
}
?>

And:

# in YAML
&subjects:     [Subject A, Subject B, Subject C]
name_format:  contact[%s]
id_format:    my_form_%s
widgets:
  name:       text
  email:      { type: text, default: me@example.com }
  subject:    { type: select, choices: *subjects }
  message:    textarea
  file:       file
validators:
  name:       { type: string, required: false }
  email:      email
  subject:    { type: choice, choices: *subjects }
  message:    { type: string, min_length: 4, errors: { min_length: Your message is too short } }
  file:       file

According to Fabien, using associative arrays to make the YAML syntax easier to explain is of no use, since YAML is bad and shall be dropped altogether. "Learn from our mistakes" means that symfony should never had used YAML in the first place, despite the fact that it appealed numerous users to it and that it's only a simplicity layer. That means that the symfony 1.2 admin generator will not be controlled from a YAML file at all - defining form widgets in YAML is an indispensable brick to a YAML syntax for an administration interface. So be prepared to use XML or plain PHP for your database schemas, configuration files, generated modules, etc.

"Learn from our mistakes" also means not using strings to define HTML attributes anymore. I suggested to keep on using the abilities of symfony 1.0 to output clean XHTML attributes from a string looking like 'id=contact_subject class=bar'. But that is something else you should forget about. Apparently, this brings no benefit over array('id' => 'contact_subject', 'class' => 'bar'). Once again, I can understand it's a matter of preference, but I'm convinced that this kind of syntactic sugar is what appealed many users to symfony in the first place.

In the documentation I wrote, I introduced a way to bind a form object to the request object ($form->bind($request)). I explained later in the chapter why it's better to do otherwise, but at least it shows that a form can be used without necessarily using the array syntax for widget names. Fabien explains why this is wrong (as I did) and fails to see the interest of introducing the setNameFormat() in the documentation only when it becomes necessary. However, the current symfony book uses this technique several times (think of in Chapter 2 for instance), because it is easier to know why a practice is wrong once you've seen the advantages of the good practice in comparison. His revised version of the Chapter 10 doesn't solve the problem, either.

But honestly, I don't care much about all these points. If if was just for Fabien's remarks on the technical side of things, I'd be more than willing to continue working on a modified Chapter 10 to make it worthy of The Guide.

The Ugly

But Fabien is really going to a nasty place with his post.

Does he bring a response to my request for comment? No, he replies to a commenter of my post, who challenged him to give his opinion. He never actually addresses me directly - I'm a persona non grata.

Does he agree on the DDD experiment? Of course not, DDD is the "Biggest problem" according to him (not sure why). How could documentation and teaching influence a developer's design decisions? The forms API is "good enough" as is, and its lack of documentation is not a problem to be solved by modifying the code. If someone (but not me) wants to write something to "help us improve the current documentation", he can still try again.

Is he grateful that I did in a week a work (Chapter 10) that he couldn't do in a year? Not at all. Not a word of thanks, he just feels insulted that someone dared to question parts of his work. What a childish reaction to someone who offers to help widen the symfony adoption.

Does he react in the interest of the community, proposing to use his own version of the Chapter 10 for the current guide? Not even that. He prefers no documentation at all rather than an equivalent to the symfony 1.0 documentation updated for symfony 1.1.

Does he care about the newcomers to symfony, those who don't know the 1.0 API by heart, don't follow the Trac timeline every day, don't read the framework code, and don't accept an UPGRADE text file for a documentation? No. Not a word about them in his post. Only the developers who already know good practices of web development can start using symfony. You can no longer learn these practices by learning symfony.

Does he write that he's been implementing some of my ideas? No, that would be giving me too much credit. The goal, here, is to show that I am a bad developer, and nothing else. Well, I'm not even a developer, so why all the hate?

Is he trying to be constructive? No. He writes, in bad faith: "[Francois'] API is so unintuitive that we must explain a lot of things to describe the way it works". God, I thought that I managed to explain in 1 hour what he needs a day to teach in an expensive training, and it's my API that is unintuitive?

Conclusion

All in all, Fabien reacts with pride rather than reason. He does as much as he can do discredit my work, while my purpose has always been to help leverage the symfony adoption. He probably dreams that, with a single blog post, I'd leave the symfony community completely, because he finally demonstrated that none of my work is worthy to his eyes.

Too bad, Fabien, you have taken the wrong path. I'll be a pain in your ass for a long time. Count me in to constantly remind people that symfony is a one-man work, and that this is a very high risk for enterprise projects, given the man.

Chapter 10 - Forms

Francois Zaninotto — Sat, 27 Sep 2008 09:21:25 +0000

Dealing with the display of form inputs, the validation of a form submission, and all the particular cases of forms is one of the most complex tasks in web development. Luckily, symfony provides a simple interface to a very powerful form sub-framework, and helps you to design and handle forms of any level of complexity in just a few lines of code.

NOTICE: This document is the first draft of a methodology experiment explained earlier in this blog. It documents the sfForm framework found in symfony 1.1, but with some changes in the API and usage. As such, it describes a library that is not yet written (like that) and cannot be used to learn the usage of the current sfForm implementation. It is quite long, so you might prefer to download the Markdown version and read it offline. Being a first draft, this document is a call for comments, both about its structure and its content. And if you are interested in implementing the differences between what this document describes and what is currently implemented in the symfony framework, please contact me.

Displaying a Form

A simple contact form featuring a name, an email, a subject and a message fields typically renders as follows:

In symfony, a form is an object defined in the action and passed to the template. In order to display a form, you must first define the fields it contains - symfony uses the term "widget". The simplest way to do it is to create a new sfForm object in the action method.

[php]
// in modules/foo/actions/actions.class.php
public function executeContact($request)
{
  $this->form = new sfForm();
  $this->form->setWidgets(array(
    'name'    => 'text',
    'email'   => array('type' => 'text', 'default' => 'me@example.com'),
    'subject' => array('type' => 'choice', 'choices' => array('Subject A', 'Subject B', 'Subject C')),
    'message' => 'textarea'
  ));
}

sfForm::setWidgets() expects an associative array of widget name / widget definition. The definition must at least contain the widget type. text, choice, and textarea are some one the numerous widget types offered by symfony; you will find a complete list further in this chapter.

For simple widgets, specifying the widget type name is enough. If you need to define more than just the widget type, use an associative array with at least a type key. The previous example shows two widget options you can use: default sets the widget value, and is available for all widgets. choices is an option specific to the choice widget (which renders as a drop-down list): it defines the available options the user can select.

So the foo/contact action defines a form object, and then handles it to the contactSuccess template in a $form variable. The template can use this object to render the various parts of the form in HTML. The simplest way to do it is to call echo $form, and this will render all the fields as form controls with labels. You can also use the form object to generate the form tag:

[php]
// in modules/foo/templates/contactSuccess.php
renderFormTag('foo/contact') ?>

With the parameters passed to setWidgets(), symfony has enough information to display the form correctly. The resulting HTML renders exactly like the screenshot above, with this underlying code:

[php]

  
    
      Name
      
    
    
      Email
      
    
    
      Subject
      
        
      
    
    
      Message

Each widget results in a table row containing a tag, and a form input tag. Symfony deduces the label name from the widget name by uppercasing it (the subject widget name gives the 'Subject' label ). As for the input tag, it depends on the widget type. Symfony adds an id attribute to each widget, based on its name. Lastly, the rendering of the form is always XHTML-compliant.

Customizing the Form Display

Using echo $form is great for prototyping, but you probably want to control exactly the resulting HTML code. The form object contains an array of fields, and calling echo $form actually iterates over the fields and renders them one by one. To get more control, you can iterate over the fields manually, and call the renderRow() on each field. The following listing produces exactly the same HTML code as previously, but the template echoes each field individually:

[php]
// in modules/foo/templates/contactSuccess.php
renderFormTag('foo/contact') ?>
  renderRow() ?>
    renderRow() ?>
    renderRow() ?>
    renderRow() ?>

Rendering fields one by one allows you to change the order in which they are displayed, and also to customize their appearance. renderRow() expects an a list of HTML attributes as first argument, so you can define a custom class, id, or JavaScript event handler for instance. This list can be set as an associative array, or as a string with key=value pairs separated by spaces; symfony will understand both syntax. The second argument of renderRow() is an optional label that overrides the one deduced from the widget name. Here is an example of customization for the contact form:

[php]
// in modules/foo/templates/contactSuccess.php
renderFormTag('foo/contact') ?>
  renderRow(array('size' => 25, 'class' => 'foo'), 'Your Name') ?>
    renderRow(array('onclick' => 'this.value = "";'), 'Your Email') ?>
    renderRow('id=contact_subject class=bar') ?>
    renderRow('size=20x5') ?>

But maybe you need to output the label and the input of each field in

tags rather than in a tags. A field "row" is made of a label, an optional error message (added by the validation system, explained later in this chapter), a help text, and a widget (note that the widget can consist of more than one form control). Just as you can output the various fields of a form one by one, you can also render the various parts of a form independently. Instead of using renderRow(), use any of render() (for the widget), renderError(), renderLabel(), and renderHelp(). For instance, if you want to render the whole form with

tags, write the template as follows:

[php]
// in modules/foo/templates/contactSuccess.php
renderFormTag('foo/contact') ?>
  
    
    
      renderLabel() ?>
      render()>

This renders to HTML as follows:

[php]

  
    
      Name
      
    
    
      Email
      
    
    
      Subject
      
    
    
      Message

Tip: A field row is the representation of all the elements of a form field (label, error message, help text, form input) by a formatter. By default, symfony uses a table formatter, and that's why renderRow() returns a set of , and tags. Alternatively, you can obtain the same HTML code as above by simply specifying an alternative list formatter for the form, as follows:

    [php]
    // in modules/foo/templates/contactSuccess.php
    renderFormTag('foo/contact') ?>
      
        setFormatterName('list') ?>

Check the API documentation of the sfWidgetFormSchemaFormatter class to learn how to create your own formatter.

Form Widgets

There are many available form widgets at your disposal to compose your forms. All widgets accept at least the type parameter and the default parameter.

You can also define the label of a widget, and even its HTML attributes, when you create the form:

[php]
$this->form = new sfForm();
$this->form->setWidgets(array(
  'name'    => array('type' => 'text', 'label' => 'Your Name', 'attributes' => array('size' => 25, 'class' => 'foo')),
  'email'   => array('type' => 'text', 'default' => 'me@example.com', 'label' => 'Your Email', 'attributes' => array('onclick' => 'this.value = "";')),
  'subject' => array('type' => 'select', 'choices' => array('Subject A', 'Subject B', 'Subject C'), 'attributes' => 'id=contact_subject class=bar'),
  'message' => array('type' => 'textarea', 'attributes' => 'size=20x5')),
));

Symfony uses these parameters to display the widget, and you can still override them by passing custom parameters to renderRow() in the template.

TIP: As an alternative to calling setWidgets() with an associative array, you can call the setWidget($name, $properties) method several times.

Standard Widgets

Here is a list of available widget types, and how they translate into HTML (via renderRow()):

[php]
// Text input
$form->setWidget('full_name', array('type' => 'text', 'default' => 'John Doe'));
  FullName
  

// Textarea
$form->setWidget('address', array('type' => 'textarea', 'attributes' => 'size=20x5', 'default' => 'Enter your address here'));
  Address
  Enter your address here

// Password input
// Note that 'password' type widgets don't take a 'default' parameter for security reasons
$form->setWidget('pwd', array('type' => 'password'));
  Pwd
  

// Hidden input
$form->setWidget('id', array('type' => 'hidden', 'default' => 1234));
  

// Checkbox
$form->setWidget('single', array('type' => 'checkbox', 'value_attribute_value' => 'single', 'default' => true));
  Single

There are more options available for each widget than what is exposed here. Check the widget API documentation for a complete description of what each widget expects and how it renders.

List Widgets

Whenever users have to make a choice in a list of values, and whether they can select one or many option in this list, a single widget answers all the needs: the choice widget. According to two optional parameters (multiple and expanded), this widget renders in a different way:

                  | multiple=false       | multiple=true
                  | (default)            |
  ----------------|----------------------|---------------------
  expanded=false  |    Dropdown list     |    Dropdown box
  (default)       |    (``)
  ----------------|----------------------|----------------------
  expanded=true   | List of Radiobuttons | List of checkboxes
                  |                      |

The choice widget expects at least a choices parameter with an array of the possible options. +Using an associative array instead of a simple array allows to define both the value and the text of each option. Here is an example of each syntax:

[php]
// Dropdown list (select)
$form->setWidget('country', array(
  'type'      => 'choice',
  'choices'   => array('us' => 'USA', 'ca' => 'Canada', 'uk' => 'UK', 'other'),
  'default'   => 'uk',
  'add_empty' => 'Select from the list'
));
// symfony renders the widget in HTML as
Country


// Dropdown list with multiple choices
$form->setWidget('languages', array(
  'type'     => 'choice',
  'multiple' => 'true',
  'choices'  => array('en' => 'English', 'fr' => 'French', 'other'),
  'default'  => array('en', 0)
));
// symfony renders the widget in HTML as
Language


// List of Radio buttons
$form->setWidget('gender', array(
  'type'     => 'choice',
  'expanded' => 'true,
  'choices'  => array('m' => 'Male', 'f' => 'Female'),
  'class'    => 'gender_list'
));
// symfony renders the widget in HTML as
Gender

  Male
  Female


// List of checkboxes
$form->setWidget('interests', array(
  'type' => 'choice',
  'multiple' => 'true',
  'expanded' => true,
  'choices' => array('Programming', 'Other')
));
// symfony renders the widget in HTML as
Interests

  Programming
  Other

Tip: You probably noticed that symfony automatically defines an id attribute for each form input, based on a combination of the name and value of the widget. You can override the id attribute widget by widget, or alternatively set a global rule for the whole form with the setIdFormat() method:

[php]
// in modules/foo/actions/actions.class.php
$this->form = new sfForm();
$this->form->setIdFormat('my_form_%s');

Foreign Key Widgets

When editing Model objects through a form, a particular list of choices always comes up: the list of objects that can be related to the current one. This happens when models are related by a many-to-one relationship, or a many-to-many. Fortunately, the sfPropelPlugin bundled with symfony provides a propel_choice widget specifically for these cases (and sfDoctrinePlugin offers a similar doctrine_choice widget).

For instance, if a Section has many Articles, you should be able to choose a section among the list of existing ones when editing an article. To do so, an ArticleForm should use the propel_choice widget:

[php]
$articleForm = new sfForm();
$articleForm->setWidgets(array(
  'id' => 'hidden',
  'title' => 'text',
  'section_id' => array(
    'type'   => 'propel_choice',
    'model'  => 'Section',
    'column' => 'name'
  )
));

This will display a list of existing sections... provided you defined a __toString() method in the Section model class. That's because symfony first retrieves the available Section objects, and populates a choice widget with them by trying to echo each object. So the Section model should at least feature the following method:

[php]
// in lib/model/Section.php
public function __toString()
{
  return $this->getName();
}

The propel_choice widget is an extension of the choice widget, so you can use the multiple option to deal with many-to-many relationships, and the expanded option to change the way the widget is rendered.

If you want to order the list of choices in a special way, or filter it so that is displays only a portion of the available choices, use the criteria option to pass a Criteria object to the propel_choice widget. Doctrine supports the same kind of customization: you can pass a Doctrine_Query object to the doctrine_choice widget with the query option.

Date Widgets

Date and time widgets output a set of dropdown lists, populated with the available values for the day, month, year, hour or minute.

[php]
// Date
$form->setWidget('dob', array(
  'type' => 'date',
  'label' => 'Date of birth',
  'default' => '01/01/1950',  // can be a timestamp or a string understandable by strtotime()
  'years' => array(1950, 1951, .., 1990)
));
// symfony renders the widget in HTML as
Date of birth
 /
 /


// Time
$form->setWidget('start', array('type' => 'time', 'default' => '12:00'));
// symfony renders the widget in HTML as
Start
 :


// Date and time
$form->setWidget('end', array('type' => 'datetime', 'default' => '01/01/2008 12:00'))
// symfony renders the widget in HTML as 5 dropdown lists for month, day, year, hour, minute

Of course, you can customize the date format, to display it in European style instead of International style (%day%/%month%/%year% instead of %month%/%day%/%year%), you can switch to 2x12 hours per day instead of 24 hours, you can define custom values for the first option of each dropdown box, and you can define limits to the possible values. Once again, check the API documentation for more details about the options of the date and time widgets.

Date widgets are a good example of the power of widgets in symfony. A widget is not a simple form input. It can be a combination of several inputs, that symfony can render and read from in a transparent way.

I18n Widgets

In multilingual applications, dates must be displayed in a format according to the user culture (see Chapter 13 for details about culture and localization). To facilitate this localization in forms, symfony provides an i18n_date widget, which expects a user culture to decide of the date formatting parameters. You can also specify a month_format to have the month drop-down display month names (in the user language) instead of numbers.

[php]
// Date
$form->setWidget('dob', array(
  'type'         => 'i18n_date',
  'culture'      => $this->getUser()->getCulture(),
  'month_format' => 'name',   // Use any of 'name' (default), 'short_name', and 'number' 
  'label'        => 'Date of birth',
  'default'      => '01/01/1950',
  'years'        => array(1950, 1951, .., 1990)
));
// For an English-speaking user, symfony renders the widget in HTML as
Date of birth
 /
 /

// For an French-speaking user, symfony renders the widget in HTML as
Date of birth
 /
 /

Similar widgets exist for time (i18n_time), and datetime (i18n_datetime).

There are two dropdown lists that occur in many forms and that also rely on the user culture: country and language selectors. Symfony provides two widgets especially for this purpose. You don't need to define the choices in these widgets, as symfony will populate them with the list of countries and languages in the language of the user (provided the user speaks any of the 250 referenced languages in symfony).

// Country list
$form->setWidget('country', array(
  'type'      => 'i18n_country_choice',
  'culture'   => $this->getUser()->getCulture(),
  'default'   => 'UK'
));
// For an English-speaking user, symfony renders the widget in HTML as
Country


// Language list
$form->setWidget('language', array(
  'type'      => 'i18n_language_choice',
  'culture'   => $this->getUser()->getCulture(),
  'languages' => array('en', 'fr', 'de'),  // optional restriced list of languages
  'default'   => 'en'
));
// For an English-speaking user, symfony renders the widget in HTML as
Language

File Widgets

Dealing with file input tags is not more complicated than dealing with other wigets:

[php]
// Input file
$form->setWidget('picture', array('type' => 'file'));
// symfony renders the widget in HTML as
Picture

// Whenever a form has a file widget, renderFormTag() outputs a  tag with the multipart option

// Editable input file
$form->setWidget('picture', array('type' => 'file_editable', 'default' => '/images/foo.png'));
// symfony renders the widget in HTML as a file input tag, together with a preview of the current file

TIP: Third-party plugins provide many additional widgets. You can easily find a rich text editor widget, a calendar widget, or other "rich UI" widgets for various JavaScript libraries. Check the Plugins repository for more details.

Handling a Form Submission

When users fill a form and submit it, the web application server needs to rerieve the data from the request and do some stuff with it. The sfForm class provides all the necessary methods to do that in a couple lines of code.

Simple Form Handling

Since widgets output as regular HTML form fields, getting their value in the action that handles the form submission is as easy as checking the related request parameters. Symfony recommends the use of the same action to display and to handle the submission of a form. For the example contact form, the action could look like this:

[php]
// in modules/foo/actions/actions.class.php
public function executeContact($request)
{
  // Define the form
  $this->form = new sfForm();
  $this->form->setWidgets(array(
    'name'    => 'text',
    'email'   => array('type' => 'text', 'default' => 'me@example.com'),
    'subject' => array('type' => 'select', 'choices' => array('Subject A', 'Subject B', 'Subject C')),
    'message' => 'textarea'),
  ));

  // Deal with the request
  if(!$request->isMethod('post'))
  {
    // Handle the form submission
    $name = $request->getParameter('name');
    // Do stuff
    // ...
    $this->redirect('foo/bar');
  }
}

If the request method is 'GET', this action will terminate over a sfView::SUCCESS and therefore render the contactSuccess template to display the form. If the request method is 'POST', then the action handles the form submission and redirects to another action. For this to work, the target action must be the same as the one displaying it. That explains why the previous examples used foo/contact as a form target:

[php]
// in modules/foo/templates/contactSuccess.php
renderFormTag('foo/contact') ?>
...

Form Handling With Data Validation

In practice, there is much more to form submission handling than just getting the values entered by the user. For most form submissions, the application controller needs to:

Check that the data is conform to a set of predefined rules (required fields, format of the email, etc.)
Optionally transform some of the input data to make it understandable (trim whitespaces, convert dates to PHP format, etc)
If the data is not valid, display the form again, with error messages where applicable
If the data is correct, do some stuff and then redirect to another action

Symfony provides an automatic way to validate the submitted data against a set of predefined rules. First, define a set of validators for each field. Second, when the form is submitted, "bind" the form object with the request object (i.e., retrieve the values submitted by the user and put them in the form). Lastly, ask the form to check that the data is valid. The following example shows how to check that the value retrieved from the email widget is, indeed, an email address, and to check that the message has a minimum size of 4 characters:

[php]
// in modules/foo/actions/actions.class.php
public function executeContact($request)
{
  // Define the form
  $this->form = new sfForm();
  $this->form->setWidgets(array(
    'name'    => 'text',
    'email'   => array('type' => 'text', 'default' => 'me@example.com'),
    'subject' => array('type' => 'select', 'choices' => array('Subject A', 'Subject B', 'Subject C')),
    'message' => 'textarea'),
  ));
  $this->form->setValidators(array(
    'email'   => 'email',
    'message' => array('type' => 'string', 'min_length' => 4))
  ));

  // Deal with the request
  if(!$request->isMethod('post'))
  {
    $this->form->bind($request);
    if ($this->form->isValid())
    {
      // Handle the form submission
      $name = $request->getParameter('name');
      // Do stuff
      // ...
      $this->redirect('foo/bar');
    }
  }
}

setValidators() uses a similar syntax to the setWidgets() method: for each form field, you can set either a validator name (like email), or an array of parameters with a required type parameter. email and string are two of the numerous symfony validators, listed further in this chapter. Naturally, sfForm also provide a setValidator() method to add validators one by one.

To put the request data into the form and bind them together, use the sfForm::bind() method. A form must be bound with some data to check its validity.

isValid() checks that all the registered validators pass. If this is the case, isValid() returns true, and the action can proceed with the form submission. If the form is not valid, then the action terminates with the default sfView::SUCCESS and displays the form again. But the form isn't just displayed with the default values, as the first time it was displayed. The form inputs show up filled with the data previously entered by the user, and error messages appear wherever the validators didn't pass.

TIP: The validation process doesn't stop when the form meets an invalid field. isValid() processes the whole form data and checks all the fields for errors, to avoid displaying new error messages as the user corrects its mistakes and submits the form again.

Using Clean Form Data

In the previous listing, the form receives the whole request object during the binding process. The problem is that the request contains more than just the form data. It also contains headers, cookies, parameters passed as GET arguments, and all this might pollute the binding process. A good practice is to pass only the form data to the bind() method.

Fortunately, symfony offers a way to name all form inputs using an array syntax. Define the name attribute format width the setNameFormat() method in the action when you define the form, as follows:

[php]
// in modules/foo/actions/actions.class.php
// Define the form
$this->form->setNameFormat('contact[%s]');

That way, all the generated form inputs render with a name like form[WIDGET_NAME] instead of just WIDGET_NAME:

[php]
Name

...
Email

...
Subject

...
Message

The action can now retrieve the contact request parameter into a single variable. This variable contains an array of all the data entered by the user in the form:

[php]
// in modules/foo/actions/actions.class.php
// Deal with the request
if(!$request->isMethod('post'))
{
  $this->form->bind($request->getParameter('contact'));
  if ($this->form->isValid())
  {
    // Handle the form submission
    $contact = $this->form->getValues();
    $name = $contact['name'];
    // Do stuff
    // ...
    $this->redirect('foo/bar');
  }
}

When the bind() method receives an array of parameters rather than a request object, symfony automatically enables an special check on the bound fields, to avoid injection of additional fields on the client side. This security feature will make the form validation fail if the array of contact parameters contains a field that is not in the original form definition.

You will notice one more difference in the action code above with the one written previously. The action uses the array of values passed by the form object ($form->getValues()) rather than the one from the request. This is because the validators have the ability to filter the input and clean it, so it's always better to rely on the data retrieved from the form object (by way of getValues()) than the data from the request. And for composite fields (like date widgets), the data returned by getValues() is already recomposed into the original names:

[php]
// When submitted, the form controls of a 'date' widget...
Date of birth
 /
 /

// ...result in three request parameters in the action
$contact = $request->getParameter('contact');
$month = $contact['dob']['month'];
$day = $contact['dob']['day'];
$year = $contact['dob']['year'];
$dateOfBirth = mktime(0, 0, 0, $month, $day, $year);
// But if you use getValues(), you can retrieve directly a correct date
$contact = $this->form->getValues();
$dateOfBirth = $contact['dob'];

Make it a habit to:

Always use array syntax for your form fields (using $this->form->setNameFormat('contact[%s]'))
Always use the clean post-validation version of the user’s form input (using $this->form->getValues()).

Where do the error messages shown in the screenshot above come from? You know that a widget is made of four components, and the error message is one of them. In fact, the default (table) formatter renders a field row as follows:

[php]
hasError()): ?>

  
    renderError() ?>           // List of errors
  



  renderLabel() ?>    // Label
  
    render() ?>                // Widget
    hasHelp()): ?>
    
renderHelp() ?>      // Help

Using any of the methods above, you can customize where and how the error messages appear for each field. In addition, you can display a global error message on top of the form is if is not valid:

[php]
hasErrors()): ?>
  The form has some errors you need to fix.

Customizing Validators

In a form, all fields that do not carry a validator are optional, and all the fields that carry a validator are required. If you need to make an optional field required, just add an empty string validator on this field. On the other hand, if you need to set a field that already has a validator as optional, pass the optional parameter to the validator. For instance, the following listing shows how to make the name field required and the email field optional:

[php]
$this->form->setValidators(array(
  'name'    => 'string',    // simple string validator, to make the name required
  'email'   => array('type' => 'email', 'optional' => true),
  'message' => array('type' => 'string', 'min_length' => 4)
));

You can apply more than one validator on a field. For instance, you may want to check that the email field satisfies both the email and the string validators with a minimum size of 4 characters. In such a case, use the and validator to combine two validators, and put the two email and string validators into its validators:

[php]
$this->form->setValidators(array(
  'name'    => 'string',    // simple string validator, to make the name required
  'email'   => array('type' => 'and', 'optional' => true, 'validators' => array(
    array('type' => 'email'),
    array('type' => 'string', 'min_length' => 4)
  )
  'message' => array('type' => 'string', 'min_length' => 4)
));

If both validators are valid, then the email field is declared valid. Similarly, you can use the or validator to combine several validators. If one of the validators is valid, then the field is declared valid.

Each invalid validator results into an error message in the field. These error messages are in English but use the symfony internationalization helpers; if your project uses other languages, you can easily translate the error messages with an i18n dictionary. Alternatively, every validator provides an errors parameter to customize its error messages. Each validator has at least two error messages: the required message and the invalid message. Some validators can display error messages for a different purpose, and will always support the overriding of the error messages through their errors parameter:

[php]
[php]
// in modules/foo/actions/actions.class.php
$this->form->setValidators(array(
  'name'    => 'string',    // simple string validator, to make the name required
  'email'   => array('type' => 'email', 'errors' => array(
    'required'   => 'Please provide an email',
    'invalid'    => 'Please provide a valid email address (me@example.com)'
    )),
  'message' => array('type' => 'string', 'min_length' => 4, 'errors' => array(
    'required'   => 'Please provide a message',
    'min_length' => 'Please provide a longer message (at least 4 characters)'
    ))
));

Naturally, these custom messages will render in the templates through i18n helpers, so any multilingual application can also translate custom error messages in a dictionary (see Chapter 13 for details).

Applying a Validator To Several Fields

The syntax used above to define validators on a form does not allow to validate that two fields are valid together. For instance, in a registration form, there are often two password fields that must match, otherwise the registration is refused. Each password field is not valid on its own, it is only valid when associated with the other field.

That's why setValidators() accepts a multiple key to set the validators that work on several values. A typical registration form definition would look like this:

[php]
// in modules/foo/actions/actions.class.php
// Define the form
$this->form = new sfForm();
$this->form->setWidgets(array(
  'login'     => 'text',
  'password1' => 'text'
  'password2' => 'text'
);
$this->form->setValidators(array(
  'login'     => 'string', // login is required
  'password1' => 'string'  // password1 is required
  'password2' => 'string'  // password2 is required
  'multiple'  => array('type' => 'compare', 'left' => 'password1', 'right' => 'password2')
));

The compare validator is a special multiple validator that receives all the form input values and can pick up two of them for comparison. Naturally, you can define more than one multiple validator by using the and and the or validators.

Validators

Symfony offers quite a lot of validators. Remember that each validator expects at least a type parameter, and accepts an errors parameter where you can at least customize the required and invalid error messages.

[php]
// String validator
$form->setValidator('message', array(
  'type'       => 'string',
  'min_length' => 4,
  'max_length' => 50,
  'errors' => array(
    'min_length' => 'Please post a longer message',
    'max_length' => 'Please be less verbose',
  )
));

// Number validator
$form->setValidator('age', array(
  'type' => 'number',    // use the 'int' type instead if you want to force integer values
  'min'  => 18,
  'max'  => 99.99,
  'errors' => array(
    'min' => 'You must be 18 or more to use this service',
    'max' => 'Are you kidding me? People over 30 can\'t even use the Internet',
  )
)):

// Email validator
$form->setValidator('email', array('type' => 'email'));

// URL validator
$form->setValidator('website', array('type' => 'url'));

// Regular expression validator
$form->setValidator('IP', array(
  'type'    => 'regex',
  'pattern' => '^[0-9]{3}\.[0-9]{3}\.[0-9]{2}\.[0-9]{3}$'
));

Even though some form controls (like dropdown lists, checkboxes, radiobutton groups) restrict the possible choices, a malicious user can always try to hack your forms by manipulating the page with Firebug or submitting a query with a scripting language. Consequently, you should also validate fields that only accept a limited array of values:

[php]
// Boolean validator
$form->setValidator('has_signed_terms_of_service', array('type' => 'boolean'));

// Choice validator (to restrict values in a list)
$form->setValidator('subject', array(
  'type'    => 'choice',
  'choices' => array('Subject A', 'Subject B', 'Subject C')
));

// Multiple choice validator
$form->setValidator('languages', array(
  'type'    => 'choice_many',
  'choices' => array('en' => 'English', 'fr' => 'French', 'other')
));

I18n choice validators exist for country lists (i18n_country_choice) and language lists (i18_language_choice). These validators require a culture parameter, and accept a restricted list of countries and languages if you want to limit the possible options.

The choice validators are often used to validate choice widgets. And since you can use the choice widget for foreign key columns, so symfony also provides a validator to check that the foreign key value exists in the foreign table:

[php]
// Propel choice validator
$form->setValidator('section_id', array(
  'type'   => 'propel_choice',
  'model'  => 'Section',
  'column' => 'name'
));

Another useful Model-related validator is the unique validator, which checks that a new value entered via a form doesn't conflict with an existing value in a database column with a unique index. For instance, two users cannot have the same login, so when editing a User object with a form, you must add a unique validator on this column:

[php]
// Propel unique validator
$form->setValidator('nickname', array(
  'type'   => 'propel_unique',
  'model'  => 'User', 
  'column' => 'login'
));

To make your forms even more secure and avoid Cross-Site Request Forgery attacks, you can customize the CSRF_Token validator, which is enabled by default. Customizing this validator prevents the form from being submitted if it wasn't displayed before:

[php]
// CSRF_Token validator - set the 'token' parameter to a random string that nobody knows
$form->setValidator('_csrf_token', array(
  'type'  => 'CSRF_token',
  'token' => 'flkd445rvvrGV34G'
));

TIP: You can set the CSRF token once for the whole site in the settings.yml file:

[yml]
# in apps/myapp/config/settings.yml
all:
  .settings:
    # Form security secret (CSRF protection)
    csrf_secret:       ##CSRF_SECRET##     # Unique secret to enable CSRF protection or false to disable

The "multiple" validators work with the whole form, rather than a single input. You must register these validators under the multiple key. Here is a list of available multiple validators:

[php]
// compare validator - compare two fields 
$form->setValidator('multiple', array(
  'type'       => 'compare',
  'left'       => 'password1',
  'comparator' => '=',    // default value
  'right'      => 'password2'
));

// Extra field validator: looks for fields in the request not present in the form
// This validator is enabled by default as soon as you bind a form to an array rather than a request
$form->setValidator('multiple', array(
  'type'                => 'extra_field',
  'allow_extra_fields'  => false,
  'filter_extra_fields' => true
));

// Unique validator for models with a composite unique key
$form->setValidator('nickname', array(
  'type'   => 'propel_unique_composite',
  'model'  => 'User',
  'column' => array('login', 'email')
));

Alternative Ways to Use a Form

Using YAML for Fast Form Definition

With all the widget options, validators and form parameters, the contact form definition written in the actions class looks quite messy:

[php]
// in modules/foo/actions/actions.class.php
// Define the form
$this->form = new sfForm();
$this->form->setNameFormat('contact[%s]');
$this->form->setIdFormat('my_form_%s');
$this->form->setWidgets(array(
  'name'    => 'text',
  'email'   => array('type' => 'text', 'default' => 'me@example.com'),
  'subject' => array('type' => 'select', 'choices' => array('Subject A', 'Subject B', 'Subject C')),
  'message' => 'textarea'
));
$this->form->setValidators(array(
  'name'    => 'string', 
  'email'   => array('type' => 'email', 'errors' => array(
    'required'   => 'please provide an email',
    'invalid'    =>  'please provide a valid email address (me@example.com)'
  )),
  'message' => array('type' => 'string', 'min_length' => 4, 'errors' => array(
    'min_length' => 'Please provide a longer message (at least 4 characters)'
  ))
));

Not only is this set of associative arrays difficult to read, it is also error-prone. But there is a more readable equivalent to PHP associative arrays that you already know in symfony: YAML. And sfForm offers a fromYaml() method to populate a form object with the parameters found in a YAML form definition:

[php]
// in modules/foo/actions/actions.class.php
// Define the form
$this->form = new sfForm();
$this->form->fromYaml(dirname(__FILE__).'../config/contact_form.yml');

[yml]
# in modules/foo/config/contact_form.yml
name_format:  contact[%s]
id_format:    my_form_%s
widgets:
  name:       text
  email:      { type: text, default: me@example.com }
  subject:    { type: select, choices: [Subject A, Subject B, Subject C] }
  message:    textarea
validators:
  name:       string
  email:
    type:     email
    errors:
      required: please provide an email
      invalid:  please provide a valid email address (me@example.com)
  message:
    type:     string
    min_length: 4
    errors:   { min_length: Please provide a longer message (at least 4 characters) }

The syntax of the YAML form definition follows the sfForm object API. The first time symfony parses this file, it transforms the definition into an associative array equivalent and stores it in the cache. So using the YAML form definition is both fast to write and fast to execute.

Altering a Form Object

When you use YAML form definition, the form is defined outside the action. That makes dynamic default value assignment quite difficult. That's why the form object supports a setDefault($field, $default) and a setDefaults($array) methods that you can call in the action after importing the form from the YAML file:

[php]
// in modules/foo/actions/actions.class.php
// Define the form
$this->form = new sfForm();
$this->form->fromYaml(dirname(__FILE__).'../config/contact_form.yml');
$this->form->setDefaults(array('email' => 'me@example.com'));

You can also override existing widget or validator settings by calling setWidget() or setValidator() on an existing field name. Symfony will merge the new parameters with the existing ones - unless you change the type parameter, in which case the previous settings are erased. Also, if you set an empty widget or validator on a field, it erases the current widget/validator.

However, widgets and validators are objects in symfony, and offer a clean API to modify their properties. Your best option to alter a form defined in a YAML file is to use this API, which is pretty self-explanatory:

[php]
// in modules/foo/actions/actions.class.php
// Define the form
$this->form = new sfForm();
$this->form->fromYaml(dirname(__FILE__).'../config/contact_form.yml');

// Add an empty option to the list of choices of a 'choice' widget
$form->getWidget('language')->setOption('add_empty', 'Please choose a language);
// Add a 'gender' list of options widget
$form->setWidget('gender', array('type' => 'choice', 'expanded' => true, 'choices' => array('m' => 'Male', 'f' => 'Female'), 'class' => 'gender_list'));
// Change the HTML attributes of the 'subject' widget
$form->getWidget('subject')->setAttribute('disabled', 'disabled');
// Remove the 'subject' widget
$form->removeWidget('subject');
// Note: removing a widget will also remove the related validators
// Change the 'email' widget type to 'textarea'
$form->setWidget('email', array('type' => 'textarea'));

// Change the 'min_length' error in the 'message' validator
$form->getValidator('message')->setError('min_length', 'Message too short');
// Make the 'name' field required
$form->setValidator('name', 'string');
// Remove the 'email' validator
$form->removeValidator('email');

Widget and Validator classes

When you set a widget or a validator, instead of passing an array of parameters, you can pass directly a widget object or a validator object. Widget class names are prefixed by 'sfWidgetForm', and validator classes are prefixed by 'sfValidator'.

[php]
$choices = array('m' => 'Male', 'f' => 'Female');
$form->setWidget('gender', new sfWidgetFormSelectRadio(array('choices' => $choices, 'class' => 'gender_list')));
// Same as
$form->setWidget('gender', array('type' => 'choice', 'choices' => $choices, 'class' => 'gender_list'));

$form->addValidator('name', new sfValidatorString());
// Same as
$form->addValidator('name', 'string');

Symfony uses this alternative syntax internally. This syntax allows you to use your own widgets and validators. A custom widget is simply a class extending sfWidgetForm, and providing a configure() and a render() methods. Check the code of existing widget classes for a deeper understanding of the widgets system. The next listing exposes the code of the text widget to illustrate the widget structure:

[php]
class sfWidgetFormInput extends sfWidgetForm
{
  /**
   * Configures the current widget.
   * This method allows each widget to add options or HTML attributes during widget creation.
   * Available options:
   *  * type: The widget type (text by default)
   *
   * @param array $options     An array of options
   * @param array $attributes  An array of default HTML attributes
   * @see sfWidgetForm
   */
  protected function configure($options = array(), $attributes = array())
  {
    $this->addOption('type', 'text');
    $this->setOption('is_hidden', false);
  }

  /**
   * Renders the widget as HTML
   *
   * @param  string $name        The element name
   * @param  string $value       The value displayed in this widget
   * @param  array  $attributes  An array of HTML attributes to be merged with the default HTML attributes
   * @param  array  $errors      An array of errors for the field
   * @return string An HTML tag string
   * @see sfWidgetForm
   */
  public function render($name, $value = null, $attributes = array(), $errors = array())
  {
    return $this->renderTag('input', array_merge(
      array('type' => $this->getOption('type'), 'name' => $name, 'value' => $value), 
      $attributes
    ));
  }
}

A validator class must extend sfValidatorBase and provide a configure() and a doClean() methods. Why doClean() and not validate()? Because validators do two things: they check that the input fulfills a set of rules, and they optionally clean the input (for instance by forcing the type, trimming, converting date strings to timestamp, etc.). So the doClean() method must return the cleaned input, or throw a sfValidatorError exception if the input doesn't satisfy any of the validator rules. Here is an illustration of this concept, with the code of the int validator.

[php]
class sfValidatorInteger extends sfValidatorBase
{
  /**
   * Configures the current validator.
   * This method allows each validator to add options and error messages during validator creation.
   * Available options:
   *  * max: The maximum value allowed
   *  * min: The minimum value allowed
   * Available error codes:
   *  * max
   *  * min
   *
   * @param array $options   An array of options
   * @param array $messages  An array of error messages
   * @see sfValidatorBase
   */
  protected function configure($options = array(), $messages = array())
  {
    $this->addOption('min');
    $this->addOption('max');
    $this->addMessage('max', '"%value%" must be less than %max%.');
    $this->addMessage('min', '"%value%" must be greater than %min%.');
    $this->setMessage('invalid', '"%value%" is not an integer.');
  }

  /**
   * Cleans the input value.
   *
   * @param  mixed $value  The input value
   * @return mixed The cleaned value
   * @throws sfValidatorError
   */
  protected function doClean($value)
  {
    $clean = intval($value);
    if (strval($clean) != $value)
    {
      throw new sfValidatorError($this, 'invalid', array('value' => $value));
    }
    if ($this->hasOption('max') && $clean > $this->getOption('max'))
    {
      throw new sfValidatorError($this, 'max', array('value' => $value, 'max' => $this->getOption('max')));
    }
    if ($this->hasOption('min') && $clean < $this->getOption('min'))
    {
      throw new sfValidatorError($this, 'min', array('value' => $value, 'min' => $this->getOption('min')));
    }

    return $clean;
  }
}

Check the symfony API documentation for widget and validator classes names and syntax.

Form Classes

In a similar fashion, if you want to reuse a form object at several parts of your project, you should create a form class with the same properties and instantiate it in all the actions using it. For instance, here is how you could create a class for the contact form:

[php]
// in lib/form/ContactForm.class.php
class ContactForm extends sfForm
{
  protected static $subjects = array('Subject A', 'Subject B', 'Subject C');

  public function configure()
  {
    $this->setNameFormat('contact[%s]');
    $this->setIdFormat('my_form_%s');
    $this->setWidgets(array(
      'name'    => 'text',
      'email'   => 'text',
      'subject' => (array('type' => 'choice', 'choices' => self::$subjects)),
      'message' => 'textarea',
    ));
    $this->setValidators(array(
      'name'    => 'string', 
      'email'   => array('type' => 'email', 'errors' => array(
        'required'   => 'please provide an email',
        'invalid'    =>  'please provide a valid email address (me@example.com)'
      )),
      'message' => array('type' => 'string', 'min_length' => 4, 'errors' => array(
        'min_length' => 'Please provide a longer message (at least 4 characters)'
      ))
    ));
    $this->setDefaults(array(
      'email' => 'me@example.com'
    ));
  }
}

Now getting a contact form object in the action has never been easier:

[php]
// in modules/foo/actions/actions.class.php
// Define the form
$this->form = new ContactForm();

You can alter this form the same way as the form created from the YAML definition.

Forms Based on a Model

Forms are the primary way to edit database records in web applications. And most forms in symfony applications allow the editing of a Model object. But the information necessary to build a form to edit a model already exists: it is in the schema. So symfony provides a form generator for model objects, that makes the creation of model-editing forms a snap.

Note: Similar features to the ones described below exist for Doctrine.

Generating Model Forms

Symfony can deduce the widget types and the validators to use for a model editing form, based on the schema. Take the following schema, for instance:

[yml]
// config/schema.yml
propel:
  article:
    id:           ~
    title:        { type: varchar(255), required: true }
    slug:         { type: varchar(255), required: true, index: unique }
    content:      longvarchar
    is_published: { type: boolean, required: true }
    author_id:    { type: integer, required: true, foreignTable: author, foreignReference: id, OnDelete: cascade }
    created_at:   ~

  author:
    id:           ~
    first_name:   varchar(20)
    last_name:    varchar(20)
    email:        { type: varchar(255), required: true, index: unique }
    active:       boolean

A form to edit an Article object should use a hidden widget for the id, a text widget for the title, a string validator for the title, etc. Symfony generates the form for you, provided that you call the propel:build-forms task:

$ php symfony propel:build-forms

For each table in the model, this command creates two files under the lib/form/ directory: a BaseXXXForm class, overridden each time you call the propel:build-forms task, and an empty XXXForm class, extending the previous one. It is the same system as the Propel model classes generation.

The generated lib/form/base/BaseArticleForm.class.php contains the translation into widgets and validators of the columns defined for the article table in the schema.yml:

[php]
class BaseArticleForm extends BaseFormPropel
{
  public function setup()
  {
    $this->setWidgets(array(
      'id'           => 'hidden',
      'title'        => 'text',
      'slug'         => 'text',
      'content'      => 'textarea',
      'is_published' => 'checkbox',
      'author_id'    => array('type' => 'choice', 'model' => 'Author', 'add_empty' => false),
      'created_at'   => 'datetime',
    ));
    $this->setValidators(array(
      'id'           => array('type' => 'propel_choice', 'model' => 'Article', 'column' => 'id', 'required' => false),
      'title'        => array('type' => 'string', 'max_length' => 255),
      'slug'         => array('type' => 'string', 'max_length' => 255),
      'content'      => array('type' => 'string', 'required' => false),
      'is_published' => 'boolean',
      'author_id'    => array('type' => 'propel_choice', 'model' => 'Author', 'column' => 'id'),
      'created_at'   => array('type' => 'datetime', 'required' => false),
    ));
    $this->setMultipleValidator(
      array('type' => 'propel_unique', 'model' => 'Article', 'column' => array('slug'))
    );
    $this->setNameFormat('article[%s]');
    parent::setup();
  }

  public function getModelName()
  {
    return 'Article';
  }
}

Notice that even though the id column is an Integer, symfony checks that the submitted id exists in the table using a propel_choice validator. The form generator always sets the strongest validation rules, to ensure the cleanest data in the database.

Using Model Forms

You can customize generated form classes for your entire project by adding code to the empty ArticleForm::configure() method. If your modifications concern only one action, create an instance of the form in the action, and use the public form methods to override the default form settings in the action, as explained previously in this chapter.

Here is an example of model form handling in an action. In this form, the slug validator is modified to make it optional, and the author_id widget is customized to display only a subset of authors - the 'active' ones.

[php]
// in modules/foo/actions/actions.class.php
public function executeEditArticle($request)
{
  $this->form = new ArticleForm();
  $c = new Criteria();
  $c->add(AuthorPeer::ACTIVE, true);
  $this->form->getWidget('author_id')->setOption('criteria', $c);
  $this->form->getValidator('slug')->setOption('required', false);

  $this->form->setObject(ArticlePeer::retrieveByPk($request->getParameter('id')));

  if ($request->isMethod('post'))
  {
    $this->form->bind($request->getParameter('article'));
    if ($this->form->isValid())
    {
      $article = $this->form->save();

      $this->redirect('article/edit?id='.$author->getId());
    }
  }
}

Instead of setting default values through an associative array (using setDefaults()), Model forms use a Model object to initialize the widget values (with setObject()). To display an empty form, just pass a new Model object.

The form submission handling is greatly simplified by the fact that the form object has an embedded Model object. Calling $this->form->bind($request->getParameter('article')) updates the embedded Article object with the request values (the data submitted by the user). Then, calling $this->form->save() on a valid form triggers the save() method on the Article object, as well as on the related objects if they exist.

TIP: The action code required to deal with a form is pretty much always the same, but that's not a reason to copy it from one module to the other. Symfony provides a module generator that creates the whole action and template code to manipulate a Model object through symfony forms. Check the Chapter 14 for more details about the CRUD generator.

Conclusion

The symfony form component is an entire framework on its own. It facilitates the display of forms in the view through widgets, it facilitates validation and handling of forms in the controller through validators, and it facilitates the edition of Model objects through Model forms. Although designed with a clear MVC separation, the form sub-framework is always easy to use. Most of the time, code generation will reduce your custom form code to a few lines.

There is much more in symfony form classes than what this chapter exposes. In fact, there is an entire book describing all its features through usage examples. And if the form framework itself doesn't provide the widget or the validator you need, it is designed in such an extensible way that you will only need to write a single class to get exactly what you need.

Sorting By Custom Column in the Symfony Admin Generator

Francois Zaninotto — Thu, 25 Sep 2008 13:55:03 +0000

Did you ever wish you could sort by a partial column in the admin generator? Using DbFinder and a few lines of code, it is now possible.

The symfony admin generator allows you to select which properties of a model you want to display. You can include foreign key fields, or even a partial field to display pretty much everything you want in the list view. The following example uses this ability to display the name of article authors, based on the fact that the Article model has a many to one relationship to the User model:

# in mymodule/config/generator.yml
generator:
  class:          sfPropelAdminGenerator
  param:
    model_class:  Blog
    theme:        default

list:
  display:        [=title, user, category, _nb_posts, created_at]
  fields: 
    user:         { name: Author }

This generator configuration includes a partial field that counts the number of blog posts for each blog:

// in mymodule/templates/_nb_posts.php
echo $blog->countBlogPosts() ?>

The problem is that only the "True" fields (that is, the ones that correspond to a column in the main table) are sortable. The result is that, with the following example, only the title column is sortable.

With symfony alone, there is no way to make the other columns sortable except overriding the whole _list_th_tabular.php partial in your module, overriding the addSortCriteria() method in the action, and losing the ability to add or remove columns in the future.

Enters DbFinderPlugin. You probably know from this blog that DbFinder offers a very powerful and yet simple way to replace Propel Criteria queries. What you might not know is that the DbFinder plugin bundles a full admin generator theme. It has the exact same features and syntax as the standard symfony admin generator, but it is entirely written with DbFinder queries. And to make this generator theme very usable, it includes the batch_actions extension from symfony 1.1 (that's what allows to display the checkboxes on the left side of the list to perform an action on several records at a time), and the ability to sort by any type of column.

To use the DbFinder admin generator, no need to switch your entire project to DbFinder. Just install the plugin, edit the generator.yml of one of your generated modules, and change the class property from sfPropelAdminGenerator (or sfDoctrineAdminGenerator, if you use Doctrine) to DbFinderAdminGenerator. Refresh the page in your browser, and you should normally see no change. That's good news: despite the fact that all the generator code has been rewritten to work with DbFinder instead of Propel, it is completely backwards compatible.

And once a generated module uses DbFinder, you gain access to the new sort_method option for custom fields:

# in mymodule/config/generator.yml
generator:
  class:          DbFinderAdminGenerator
  param:
    model_class:  Blog
    theme:        default

list:
  display:        [=title, user, category, _nb_posts, created_at]
  fields: 
    user:         { name: Author, sort_method: orderByUsername }
    category:     { sort_method: orderByCategory }
    nb_posts:     { sort_method: orderByNbPosts }

Refresh the list view, and voila, the column headers are now clickable.

Don't click the new links yet: you've defined three methods for custom ordering, and you still have to write them. To do so, you need to create a BlogFinder, which is a finder class specific to the Blog model class. So create a lib/model/BlogFinder.php class with the following content:

// in lib/model/BlogFinder.php
class BlogFinder extends DbFinder
{
protected $class = 'Blog';

public function orderByUsername($order = 'asc')
{
return $this->orderBy('User.Name', $order);
}

public function orderByCategory($order = 'asc')
{
return $this->orderBy('Category.Name', $order);
}

public function orderByNbPosts($order = 'asc')
{
return $this->
leftJoin('BlogPost')->
groupBy('Blog.Id')->
withColumn('COUNT(BlogPost.Id)', 'nbPosts')->
orderBy('nbPosts', $order);
}
}

The finder is smart enough to guess the relationship between the Blog and the User model, as well as the relationship with the Category model, because the YAML schema defines foreign keys between the related tables.

Clear the cache (to allow the autoloading to find the new finder class), refresh your list, and enjoy fully sortable columns.

To finish, here is a small trick to drastically improve your backend performance. Every time the _nb_posts partial is called (and that's once per row in the list), symfony issues a COUNT query. That means that the current configuration will run n+1 queries, n being the number of results per page (typically 20). That's pretty bad for performance. What if you could hydrate an additional column in the main query and use this column in the _nb_posts partial? With DbFinder, that's very easy. Just add a finder_methods setting to your list configuration, as follows:

# in mymodule/config/generator.yml
list:
  display:        [=title, user, category, _nb_posts, created_at]
  fields: 
    user:         { name: Author, sort_method: orderByUsername }
    category:     { sort_method: orderByCategory }
    nb_posts:     { sort_method: orderByNbPosts }
    finder_methods: [withNbPosts]

Symfony executes all the methods defined in the finder_methods before displaying the list. It allows you to define a default ordering, to filter out some records, or, like here, to add custom column to the main query.

Now it's time to create this BlogFinder::withNbPosts() method. Since it contains part of the code of orderByNbPosts(), and that the finder generator executes sort methods at the end of the action, you can reduce the orderByNbPosts() code accordingly:

// in lib/model/BlogFinder.php
public function withNbPosts($order = 'asc')
{
return $this->
leftJoin('BlogPost')->
groupBy('Blog.Id')->
withColumn('COUNT(BlogPost.Id)', 'nbPosts');
}

public function orderByNbPosts($order = 'asc')
{
return $this->orderBy('nbPosts', $order);
}

Now the main list query includes the call for the calculated nbPosts column, and you can change the _nb_posts partial to use it:

// in mymodule/templates/_nb_posts.php
echo $blog->getColumn('nbPosts') ?>

Refresh the list view: Ta-da, the result is the same, but using a single query instead of n+1.

So the DbFinder generator offers the same features as the current symfony 1.1 generator, except more. Don't wait until you upgrade your project to symfony 1.2 to enhance your generated modules. Read the DbFinder admin generator documentation, and download the plugin right away.

Document-Driven Development in Practice: Rethinking sfForms

Francois Zaninotto — Tue, 23 Sep 2008 18:17:40 +0000

If you've watched or read my presentation on Documentation-Driven Development, you may wonder how to put that new methodology into action. A practical example is often better than a long explanation, so let's see ho to apply it to the new Forms sub-framework introduced by symfony 1.1.

Not DDD

In order to use the new sfForm library, you must either read a book (not yet completely written) or dive into the source code and guess how to use it. To my mind, this is pretty much the contrary of what leads to a large adoption.

The Form framework was designed with power in mind, and reaches this goal very well: you can use it to create forms of any level of complexity, including forms embedding other forms, forms with a variable number of fields, forms split into several steps ("wizards"), etc. It is very much object oriented, so everything can be reused or overridden.

But unfortunately, in order to create a simple form, you need to learn a lot more and write a lot more code than what you used to do in symfony 1.1. The current Forms documentation describes the API and justifies its implementation. It goes very much into the details of each part of the sub-framework, and quite early in the learning process. The result - for me, at least - is that the reader feels overwhelmed by the huge amount of classes, features and options, and dismisses the whole sub-framework for being too complex.

"Let's use that new Form stuff for complex forms and keep the current form helpers and YAML validation for everyday forms", I hear. That's a pity, because once you understand how the new Forms sub-framework works and accept its verbosity, there is no good reason to stick with the old system.

An Ideal sfForm Documentation

I think that a piece of documentation is missing. This piece is probably an introduction to the Form sub-framework.

In symfony 1.0, a single chapter of the book was enough to master forms for most use cases. Even if the new form sub-framework is more powerful than the 1.0 one, it should not be more complicated to learn and use in similar cases. So the sfForms introduction should be short, requiring at most one hour to read it.

After reading this documentation, an average developer should be able to use sfForms in 80% of the cases. That includes at least all the features described in the original Forms chapter of the symfony book:

Displaying a form
Available form helpers
Displaying a model-based form
Dealing with Foreign keys
Handling a form submission
Validating a form
Available validators
Repopulating a form
Complex use cases

The target audience would be people knowing some concepts about symfony, but not yet everything. In fact, they should know what the Chapters 1 to 9 of the symfony guide cover, not more. So some advanced concepts should probably be skipped, or explained only after the fundamental usage is clear.

This introduction should not require additional lookup in the Forms book. That means that it should be self-sufficient. It probably also means not including the justifications of the Forms implementation that you can find in the current Forms book. The reasons why the API was designed the way it is should become obvious at the end of the introduction. Expert customization and rare use cases should probably also be left aside.

The symfony 1.0 documentation introduces concepts and features in a certain order, with a precise purpose: not loading too much information into the reader's mind at a time. In a similar fashion, the forms introduction should be a linear piece of documentation, not a set of articles that you can read in any order with hyperlinks everywhere to break the reading flow.

The forms framework is powerful, but the current form book somehow translates that into length, and verbosity. On the contrary, I think the reader should feel exalted: the documentation should put him in a rush to start using the new forms. So the forms introduction should "tell a story", and gently lead the reader to a point where he feels he can grab the steering wheel and drive the car by himself.

API enhancements

The problem is that explaining the current API takes much longer than a single piece of documentation. That's because of the many options available, because of the many objects to learn, and because even the simplest things (like a list of form controls) look complicated (sfWidgetFormSchema).

There is not much choice to overcome this problem. In order to write a short and readable guide to the forms sub-framework, its API must be adapted. That's right, the API must be changed so that the documentation can be made shorter, and more usable. This is one of the principles of the Documentation-Driven Development methodology.

These API enhancements should be completely backward compatible, so that any existing application using the current sfForms implementation can continue to work seamlessly with the modified implementation. In a way, that qualifies the API enhancements as a simplicity layer on top if the existing code. As a side note, the current Forms book still remains indispensable for advanced usage.

Note that the API enhancements don't need to be implemented before the new documentation is published. The implementation comes second, after the documentation. That's another of the DDD principles: explain first, make it work afterwards. After all, project managers write requirements for web applications before they exist, all the time.

Do As I Do, Not As I Say

Some people are getting sick of reading me criticizing parts of the symfony framework. Well, I'm not criticizing: I'm actively improving.

Rethinking sfForms is a good example for a Documentation-Driven Development. To illustrate this methodology, I'm going to rewrite the Chapter 10 of the symfony book for symfony 1.1. That's right, the current Chapter 10, which describes the "old way" of doing forms, can be rewritten in a similar fashion and serve for symfony 1.1.

But since the current API requires too much explanation to be used, I'm going to introduce the necessary API changes to the sfForms library. I'll create and manage forms in a way slightly different from what the current API allows, to make it simpler to use - and to explain.

When the new Chapter 10 is published here in this very blog, this piece of documentation will be of no use since the features it describes won't be implemented yet. But I know that writing documentation is not enough to convince people (yet), so I will Implement the API changes as a second step to the exercise. As I'm not a very good developer, any help will be welcome during that phase (contact me If you want to give me a hand after the documentation is published).

If everything goes well, the implementation of the API changes will be be released as a symfony plugin - maybe called sfSimpleForms. I hope it can lead more developers to adopt the greatest open-source Forms framework around.

Designing a CMS Architecture

Francois Zaninotto — Fri, 19 Sep 2008 12:26:57 +0000

When faced with the alternative between an off-the-shelf CMS or a custom development, many companies pick solutions like ezPublish or Drupal. In addition to being free, these CMS seem to fulfill all possible requirements. But while choosing an open-source solution is a great idea, going for a full-featured CMS may prove more expensive than designing and developing your own Custom Management System.

Hidden Costs

What does it cost to integrate and deploy a website based on an open-source CMS? At first sight, not much. As for every CMS, you have to design your own templates and fill your website with initial data. But there are additional costs that pop up as soon as you need a little more than just plain content management.

Think about adding a blog or a forum to a website managed by a CMS. There are modules or plugins for that, but they never provide the same flexibility as plain blogging engines such as Wordpress, or plain forum engines like phpBB. So even if the basic requirement is fulfilled by a module, you will always need - always - to adapt its code.

And this is where it gets ugly. The code base of open source CMS engines and their plugin is nowhere as good as what you can see in RAD frameworks these days. Most of them are based on a very old architecture (PHP4, no object orientation, no proper error handling, direct access to the database, etc.). That means that changing something will be very painful, and very expensive. You will encounter numerous bugs, change the blogging plugin three times because neither of the ones you tested are capable of doing what you need, you will upgrade your CMS to the latest version to benefit from this single bug fix that should save your life but then you need to change all your existing configuration...

This is as bad as it sounds. Start changing one single line of code in an application build on top of Drupal or ezPublish, to name only the two major ones, and you are in trouble. The moment you need something that is not natively supported, you enter the Dark Zone of CMS hell. You are going to spend a lot of money on development. You will never see the end of the tunnel. That is, until someone says, a few years from now, "Do we need all that crap? Let's build something that fits our needs and that actually works".

Making Your Own CMS

Given number of available open-source CMS solutions, building one on your own sounds like a stupid idea. But if your website is 50% content management and 50% something else, you probably need to start with a web application framework like symfony or Django, rather than a CMS. These frameworks provide plugins that do part of the Content Management job already, so creating a CMS today is like assembling Lego bricks to build something that exactly fits your needs.

Take symfony, for instance. It provides native support, or support through plugins, for:

Symfony doesn't yet provide an Access Control List or a Workflow plugin, but you can already put all of the above together and have a pretty powerful CMS engine.

A tailor-made CMS will always have less code and show better performance than any of the existing full-featured solutions. Also, you will be able to tweak it completely, since all the components are decoupled, and built with extensibility in mind.

Your custom CMS will cost you more during the first year, but if you expect your website(s) to live longer than that, then the benefit will become obvious after a year and a half. Plugging the CMS features into other parts of the website, adding features unrelated to content management, scaling to a larger audience, replacing the database engine or the caching backend, all that will be painless.

That is, if you design your custom CMS carefully, and with the future in mind.

Environments

When you add features to an application, you need a testing environment - a place where you can check that the additions work and don't kill the rest of the application. That means that developers have a version of the website on their desktop computer, where they change stuff. Then, they upload the application to a test server, check that everything is OK, and only then can they deploy the application to the production server. This is a very common practice, often backed up by source version control and continuous integration tools.

But what happens when a new feature is not made of code, but of data? In ezPublish, for instance, in order to define a new type of content (they call it a "Class"), you have to use the backend web interface and fill in a few forms. The properties of the new type of content are stored in the database. In order to deploy this new type of content from the testing environment to the production environment, the developers need to transfer data from one database to another - without wiping off unrelated information on the production database, such as user comments, statistics, etc.

Deploying new features in this context means executing some SQL code on each server. This is much more dangerous than just pushing a new version of the codebase, especially when the data model is made of many tables glued together in complex joins. That's why, in many websites based on ezPublish, developers add features directly on the production environment, or repeat the configuration using the backend interface on every environment. This is either a high risk or a large waste of time.

Data, or Code?

This environment drawback tends to be a major influence over the choice of features a CMS should provide. For almost every CMS feature, you should wonder: Can the user do that through the backend interface, or do we need a programmer to add a new element? In other terms, is the feature made of data, or code?

Off-the-shelf CMS engines will almost always answer 'Data'. My personal opinion is that it is wrong in many cases. Content types are just one example, but think about workflows or page layouts for instance. They define a complex logic that always translates to code, and giving the user the ability to change them via a backend interface means storing code in the database and evaluating it at runtime. Then you can't use op-code cache engines like APC incriease your website performance. And deploying that to production is a nightmare.

Some companies think that most of the CMS features should be accessible via a backend interface in order to be able to enhance the application without additional developments. But this is an illusion. For one, the configuration of content classes in ezPublish is so complex that it does indeed require a PHP developer, and an expensive one, since experience with ezPublish is one of the most demanded skills in the IT market (at least in France). More features mean more development, and there is no CMS out there that replaces the power of a programming language with a web interface.

So that leads to one good rule of thumb: Design your features so that they can be made of code rather than data. That applies to elements that can be modified by a graphical user interface, or programatically:

Content classes
"Widgets" or "Components" for pages
Page layouts or "templates"
Content validation workflow
Tasks

Fundamental questions

The complexity of a CMS engine depends greatly on the answer you give to a few fundamental questions:

Can contents exist independently of a page?
Can contents exist at more than one place in the website?
Are there several views for a single piece of content?
Can contents have different versions simultaneously?
Can contents be modified in the backend and keep unchanged in the frontend?
Can users compose a page with "widgets" or "components" in a WYSIWYG interface?
Can predefined zones in a template contain more than one "widget" or "component"?
Can section pages have different templates?
Can section pages have different versions simultaneously?
Can users program the publishing of a section page, or of contents, in advance?
Can the CMS remember previous URLs for a content that changed title?

If the answer to the first question is no, then the concept of "page" and "content" coincide. You probably don't need to develop anything, since your CMS will be quite simple.

If you answer yes to all these questions, then the CMS might take three times longer to develop than what it would be otherwise.

That's why the idea of a tailor-made CMS is not that stupid. No existing CMS will be able to answer these questions in every possible way. But designing your own relational schema based on the answer to these questions makes sense, economically speaking. Don't make it complex if you don't need do, or, to put it otherwise, Keep It Simple, Stupid.

Bootstrapping the reflection

Now that you're trying to imagine what you actually need for your own CMS, here is a glimpse of the kind of technical challenge you will face all the time.

The question turns around the concept of content types. In a CMS, you mostly deal with "articles". This type of content has a title, an author, a summary, a body, and a few other attributes. But you probably also need to deal with some other content types, like movies, slide shows, quiz games, polls, or recipes. These content types are defined by properties distinct from that of an article. Some of them can fit in a single structure, others require several structures related to each other. For instance, quiz games require a structure for the quiz itself, one for the questions, one for the answers to each question, and one for the quiz results.

The question is: Do you store the data for all these content types in a single table, or do you create a table for each content type? The most "normalized" choice is probably to create one data structure for each. You could have an "article" table, a "recipe" table, and even a "quiz" table with foreign keys to a "quiz_question" and a "quiz_result" table. That would allow you to make queries on some specific attributes of a specific content type. You could build a custom search engine for your recipes and look for ingredients, foreign cuisine and preparation time.

But then, if each content type has its own table(s), what do you do when you have to list all the contents of a section, or worse (that happens in the backend) all the contents of the website? Does that mean that, in order to display a list of contents, you must query several tables and aggregate the results together? This solution simply doesn't scale, and a CMS built like that will become slower and slower as you add new content types.

So that probably means that you should store a reference to each content in a separate table, with a copy of the data that is generic to all content types (like title, publication date, section, etc.). Pages displaying a list of contents would use this aggregate table, while pages displaying content details would use the specific tables.

And that means that you must find a way to synchronize the specific tables and the generic tables whenever data changes in content. That's not a big deal, but it gives you an idea of the kind of complexity you will encounter in a large scale CMS.

A Challenging Exercise

Designing a CMS is difficult and fun, and you'll probably do it more than once. Every CMS is different, because every content management need is different, and mostly because every customer wants more than just plain content management.

If you are a developer, whenever you meet a client that asks you for a Drupal integration, try to sell your knowledge of CMS architectures rather than a few hours of developer time. Raise the important questions, talk about the possible problems of using off-the-shelf solutions. If you ever used one of those before, you will have plenty of issues to talk about. Then, try to convince your customer to trust you into a custom development. Make it small at the beginning, so that the customer can start using it right away and refine its requirements incrementally.

This will be a very satisfying experience, and the client will thank you later for leading him on the right path. And this will give you a lot to talk about for the next CMS you build...

Developing for Developers: my SymfonyCamp08 Presentation

Francois Zaninotto — Mon, 15 Sep 2008 07:30:02 +0000

Did you attend this year's Symfony Camp? It was a great event, the unique occasion to meet the core team of the symfony framework. I had the opportunity to give a talk there, and you can now watch it online:

Developing for Developers

View SlideShare presentation or Upload your own. (tags: symfony php)

Don't hesitate to comment on this presentation on SlideShare.

Thanks to all the great people that I met there who gave me a feedback on my work, encouragements or advice. Thanks to Dutch Open Projects for the organization - and for inviting me. It was a great pleasure to exchange about symfony, its past, present, and future, with so many enthusiastic people.

Update: It seems that my slideshow has been featured on the SlideShare homepage by the SlideShare editorial team.

Validating a YAML file against a schema in PHP

Francois Zaninotto — Tue, 09 Sep 2008 15:42:43 +0000

As of today, there is no simple way to validate the syntax of a YAML file in PHP. But with two simple tricks, it takes only a few dozens of lines of code to build a robust validator capable of checking the syntax of any YAML file against a given schema.

The problem

YAML is much easier to write and read than XML, but YAML has no schema validation capabilities. With DTD and XSD, you can check that an XML file is correctly formatted before actually using it, and it helps debugging a great lot. Modern web application frameworks like symfony encourage the use of YAML for configuration files, but the lack of validation tool sometimes make YAML a poor choice in a professional environment.

Such a validation tool exists in Ruby, it's called kwalify. But unless you want to spend a huge amount of time translating the 6,000+ lines of code of the library from Ruby into PHP, or to run Ruby code inside your PHP application, you're basically stuck.

First Idea

Did you just read that XML allows validation by way of XSD? Well, why not use this mechanism to validate a YAML file? After all, PHP has a great XML manipulation library, installed by default, and capable of validating any XML file against a DTD or an XSD. Actually, this mechanism is already in use in symfony, since the Propel schema.yml is transformed into an XML counterpart that has an XSD.

It is trivial to transform a YAML file into a PHP associative array. Symfony 1.1 provides a class that does exactly that, and it's called sfYaml. With a little bit of recursion and a few lines of PHP code, it is also quite easy to transform an associative array into a simple XML file.

Let's use the view.yml configuration file in symfony for example. In a typical module, it looks like the following:

# view.yml
default:
  http_metas:
    content-type:  text/html

  metas:
    title:         My symfony project
    robots:        index, follow
    description:   This is my first symfony project
    keywords:      symfony
    language:      en

  stylesheets:     [main.css, top.css]

  javascripts:     [jquery-1.2.6.js, main.js]

  has_layout:      on
  layout:          layout

indexSuccess:
  metas:
    title:        Welcome to my site

Now what does it take to transform this YAML into a simple XML equivalent? Not much. A bit of googling shows that someone already worked on transforming an associative array into XML, and as it is not a good idea to reinvent the wheel, let's reuse this work.

// Transform YAML into XML
include 'sfYaml.class.php';
$yamlString = file_get_contents('view.yml');
$yamlArray = sfYaml::load($yamlString);
$xmlString = ArrayToXml($yamlArray);

function ArrayToXml($data, $rootNodeName = 'root', $xml = null)
{
if ($xml == null)
{
$xml = simplexml_load_string("<$rootNodeName />");
}

// loop through the data passed in.
foreach($data as $key => $value)
{
// no numeric keys in our xml please!
if (is_numeric($key))
{
// make string key...
$key = "unknownNode_". (string) $key;
}

// replace anything not alpha numeric
$key = preg_replace('/[^a-z]/i', '', $key);

// if there is another array found recrusively call this function
if (is_array($value))
{
$node = $xml->addChild($key);
// recrusive call.
ArrayToXml($value, $rootNodeName, $node);
}
else
{
// add single node.
$xml->addChild($key, $value);
}
}

// pass back as string. or simple xml object if you want!
return $xml->asXML();
}

Second idea

The result of the simple YAML to XML transformation looks like this:

<?xml version="1.0" encoding="utf-8"?>

>
>
>
>text/html>
>
>
>My symfony project>
>index, follow>
>This is my first symfony project>
>symfony>
>en>
>
>
>main.css>
>top.css>
>
>
>jquery-1.2.6.js>
>main.js>
>
>1>
>layout>
>
>
>
>Welcome to my site>
>
>
>

The trouble here is that the and tags are not real tags. That means, they do not define a class of content but a value. Same for the nodes. To make sense, a real equivalent to the view.yml in XML should look like this:

<?xml version="1.0"?>

>
name="default">
>
>text/html>
>
>
>My symfony project>
>index, follow>
>This is my first symfony project>
>symfony>
>en>
>
>
>main.css>
>top.css>
>
>
>jquery-1.2.6.js>
>main.js>
>
>1>
>layout>
>
name="indexSuccess">
>
>Welcome to my site>
>
>
>

The difference is that main entries are

Redo The Web

It’s Oh So Quiet

The Good, The Bad and the Ugly

The Good

The Bad

The Ugly

Conclusion

Chapter 10 - Forms

Displaying a Form

Customizing the Form Display

Form Widgets

Standard Widgets

List Widgets

Foreign Key Widgets

Date Widgets

I18n Widgets

File Widgets

Handling a Form Submission

Simple Form Handling

Form Handling With Data Validation

Using Clean Form Data

Customizing Validators

Applying a Validator To Several Fields

Validators

Alternative Ways to Use a Form

Using YAML for Fast Form Definition

Altering a Form Object

Widget and Validator classes

Form Classes

Forms Based on a Model

Generating Model Forms

Using Model Forms

Conclusion

Sorting By Custom Column in the Symfony Admin Generator

Document-Driven Development in Practice: Rethinking sfForms

Not DDD

An Ideal sfForm Documentation

API enhancements

Do As I Do, Not As I Say

Designing a CMS Architecture

Hidden Costs

Making Your Own CMS

Environments

Data, or Code?

Fundamental questions

Bootstrapping the reflection

A Challenging Exercise

Developing for Developers: my SymfonyCamp08 Presentation

Validating a YAML file against a schema in PHP

The problem

First Idea

Second idea

Validating

Dealing with libxml errors

Wrapping it up

Ironic, isn't it?

Everybody Goes to Symfony Camp

sfPropelFinder becomes DbFinder - Announcing 1.0 release