© Nicolas Perriault

Thank you Andreas and Dennis for putting uncounted hours into planning the event, guiding us around the city, spending the night before fixing the wireless connection and for taking care of all the other small things that usually go by unnoticed. Thank you Isabelle for your Cologne crash course and for organizing our flights and the perfect accommodation. Thank you Nicolas for your many thoughtful advices, I really appreciate them. Thank you Xavier, Stefan, Jon and Sebastian for your refreshing company; I really enjoyed the lengthy walks around the city, even though my foot complained somewhat. Thank you all the attendees who gave me feedback about my work and my presentation. Thank you Interlution for letting us take part in your 10 year anniversary party. And thank you all the other people involved in making this event a success.

Events like this one are really important for the community. They put faces behind names, make friends, open up new opportunities and spread ideas. They are what open source truly is about.

As another result of the conference, this blog features a new page Talks where I included the slides of my presentation Best Practice Testing with Lime 2. And to those who annoyed me about Twitter – apparently some new account @webmozart has been created over there. Don’t know who it is, but don’t expect him to tweet too much.

Related posts:

1. Symfony Day Cologne 2009 Today, I will take the plane to Cologne to attend...

Image Courtesy of KoelnTriangle.de

The conference will offer a full-day workshop held by Stefan Koopmanschap for those who are just getting started with symfony. Advanced symfony users can attend five promising speeches by Nicolas Perriault, Xavier Lacot, Rob Bors and Jonathan Wage, who is accountable for two presentations. I had the pleasure to be invited as the fifth speaker, and I am going to talk about unit testing.

Automated software testing, when applied in a real context, is not always as easy as it may sometimes be portrayed. You need experience to design your software in a testable fashion, discipline to keep writing tests when pressure keeps increasing, tools to support your testing needs in the best way possible and knowledge to employ these tools efficiently. If any of these aspects is lacking, your team may very quickly end up not writing any tests at all. Even if you fight your way through the battle and manage to keep test coverage high, chances are that your tests become very slow. A bad test performance, in turn, prevents people from running them frequently enough – and turns all your testing efforts into a waste of time.

In my presentation I want to give you a deeper insight on what testing is all about. Not only do I want to present you best practices that worked for me, I also want you to understand the testing process so that you can go on developing best practices for yourself. I will try to focus on pratical examples; nevertheless I expect you to have a fair knowledge of writing and reading unit and functional tests with lime. For all those who won’t be able to join, the slides will be uploaded on this blog as soon as I probably can.

The presentation will also give you the opportunity to get a first glance of what Lime 2 is going to offer you. I have been busy developing the successor of lime over the last months and am happy to see that it is steadily approaching alpha release. The detailed release plan is soon to be published on the symfony blog.

I am already excitedly looking forward to meeting you all!

Related posts:

1. Thank You Yesterday I returned back to Vienna from Symfony Day Cologne...
2. Speedup: Profile your symfony app using Xdebug Hi! A warm welcome to Web Mozarts also from my...
3. Easy Unit Testing Unit testing is a very important task of professional, scalable...

The “default” context does not exist.

Is there any symfony developer out there who never stumbled upon this dreadful error message? I doubt it. Recently, a lot of posts have been made on the user mailing list asking for explanations and fixes. A quick search on Google for the exact phrase even returns 480 results!

The reason for this error is quite simple though: It’s because you used sfContext::getInstance(). And you should never do that.

MVC and the Context

The class sfContext is the glue of the controller layer in symfony. It keeps all the relevant controller classes together: sfUser, sfResponse, sfRequest, sfController as well as some others. The reason for its existence is simplicity. These classes now only need a reference to the context to access each other. The class sfController, for instance, contains a protected member variable $context, by which it can access all the other objects without having to store seperate references.

sfContext implements the Singleton design pattern. Thus you can retrieve one of the few context instances by calling sfContext::getInstance() with an optional first parameter: The name of the context. If the first parameter is not given, the name is assumed to be “default”. But sfContext is no real Singleton. No new instance will ever be created when you call sfContext::getInstance(). Instead, you need to call sfContext::createInstance() first. If you miss to do that, you will receive exactly the error at the introduction of my post.

Why to Avoid Singletons

The Singleton pattern is actually one of the worst design patterns by the Gang-of-Four[1]. Because you hard-code the name of the singleton class, you create a dependency that is hard and partially impossible to substitute from outside. As a result, your class becomes unflexible and very hard to unit-test. Let’s look at a common mistake:

class Product
{
  public function save()
  {
    if (sfContext::getInstance()->getUser()->hasAttribute('foobar'))
    {
      // do something
    }
  }
}

Listing 1

This implementation bears the following problems:

Problem #1: Flexibility

If you have multiple sfUser instances, you are not able to tell the product on which instance it should depend. The product always fetches the instance registered in the context. Also, if the context is not available (for instance in console tasks), the save() method fails.

Problem #2: Testability

For testing the Product class, you have to create the context including all of its dependencies. That means parsing factories.yml, reading the configuration files, instantiating sfController, sfRequest and many more classes. Doing so adds substantial overhead to your tests and makes them slow and prone to errors. If any of the operations during the context instantiation fails, your Product test will suddenly fail, even if the class Product is perfectly fine!

How to Avoid Singletons

Instead of hard-coding the call to sfContext::getInstance(), you should pass the context object directly to the object that needs it. If you don’t even need the context, but only one of its references like the user, pass that object instead.

class Product
{
  protected $user = null;

  protected function setUser(sfUser $user)
  {
    $this->user = $user;
  }

  public function save()
  {
    if ($this->user instanceof sfUser && $this->user->hasAttribute('foobar'))
    {
      // do something
    }
  }
}

Listing 2

This technique is called Dependency Injection. If you are not familiar with Dependency Injection, I recommend you to read Fabien Potencier’s introduction to Dependency Injection. Basically there are two ways two inject dependencies into an object:

Constructor Injection

This type of Dependency Injection is used when a dependency is required. Because the dependency needs to be passed in the constructor, no object can ever be created when this dependency is not fulfilled.

class Product
{
  protected $user = null;

  protected function __construct(sfUser $user)
  {
    $this->user = $user;
  }
}

Listing 3

Setter Injection

This type of Dependency Injection is used when a dependency is optional. Because you can never be sure whether the setter has been called, you always have to verify whether the object exists before accessing its operations and properties, as we did in Listing 2.

Alternatively, you can also use setter injection for required dependencies if you can not override the constructor without breaking the class (this is the case for Doctrine records). In that case, you simply throw an exception if the dependency is not available.

class Product
{
  public function save()
  {
    if (!$this->user instanceof sfUser)
    {
      throw new LogicException('The user must be set before saving');
    }
  }
}

Listing 4

What You Gained

Because you can now inject any user object into your class, you can test the Product class very easily:

class StubUser extends sfUser
{
  public function hasAttribute($name)
  {
    return $name == 'foobar';
  }
}

$t->comment('Products with the attribute "foobar" do something special upon saving');

  $p = new Product();
  $p->setUser(new StubUser());
  $p->save();
  $t->is(...);

Listing 5

Exceptions

In very few cases, you cannot avoid accessing the context by using sfContext::getInstance(). This is almost always the case when symfony manages the construction of an object. If you configure symfony to use a custom object by modifying factories.yml, you still won’t be able to inject custom objects.

This will change as soon as symfony uses the new Dependency Injection container for the construction of the core classes.

An example for this problem is extending sfResponse. You can tell symfony to use a custom response, but you cannot tell symfony to inject the context or other objects into it (except for if you write a custom sfFactoryConfigHandler). In this case, and because sfResponse is part of the controller layer, you should be pragmatic and just use sfContext::getInstance().

Conclusion

Always try to avoid calling sfContext::getInstance(). Many of symfony’s classes in the controller layer already store a reference to the context, so you can use that one instead. If no reference is available, inject the reference to the context or to whichever class you need.

References

[1] E. Gamma, R. Helm, R. Johnson, J. Vlissides: Design Patterns. Elements of Reusable Object-Oriented Software. Addison-Wesley, 1995

Related posts:

1. No Piece of Cake Welcome to all of you on webmozarts.com! Whether you are...

Today I will briefly speak about the advantages of both frameworks, and how they can be combined to result in a slicker, powerful testing framework. I will show you how easy testing really can be! And you will be able to try it out, because all the required code has already been released in sfLimeExtraPlugin.

Introduction

In the following sections, I will refer to a set of example classes that I will briefly describe here for your better understanding:

class User
{
  protected $storage;

  public function User(SessionStorageInterface $storage)
  {
    $this->storage = $storage;
  }

  public function setAttribute($name, $value)
  {
    $this->storage->write($name, $value);
  }

  public function getAttribute($name)
  {
    return $this->storage->read($name);
  }
}

The user class offers methods to store data of a user in a session storage that you need to pass to its constructor.

interface SessionStorageInterface
{
  public function write($key, $value);
  public function read($key);
}

Let’s assume that SessionStorageInterface specifies how session storages have to look like. They need methods to write values into the underlying layer, be it the file system or database, and methods to read values.

We will be writing unit tests for the User class. We don’t want to use a real session storage class though, because we don’t want the test to rely on the file system or a database. Thus we will create a fake implementation of SessionStorageInterface:

class StubSessionStorage implements SessionStorageInterface
{
  private $name;
  private $value;

  public function write($name, $value)
  {
    $this->name = $name;
    $this->value = $value;
  }

  public function read($name)
  {
    return $name == $this->name ? $this->value : null;
  }
}

Fake implementations like this are called “Stubs”. Obviously, they would never make sense in a production environment. Their sole purpose is to help us testing, as in our case, the User class.

PHPUnit and the xUnit Family

Back in 1999, Kent Beck wrote “the mother of all unit testing frameworks”; it was called “SUnit” and supported unit testing for Smalltalk[1]. SUnit lead to a further testing framework, that Beck wrote in cooperation with Erich Gamma: jUnit, for Java. Today, jUnit is the most popular and widely-used unit testing framework for Java and hence it was ported to many other languages: CppUnit for C++, NUnit for C# or PHPUnit for PHP. All those frameworks together are often referred to as the xUnit family[2].

PHPUnit is a high-quality port of jUnit to PHP written by Sebastian Bergmann, currently available in stable version 3.3. A typical test case with PHPUnit looks like this:

class UserTest extends PHPUnit_Framework_TestCase
{
  private $sessionStorage;
  private $user;

  public function setUp()
  {
    $this->sessionStorage = new StubSessionStorage();
    $this->user = new User($this->sessionStorage);
  }

  public function testAttributesAreReadFromTheSession()
  {
    // fixture setup
    $this->sessionStorage->write('Foo', 'Bar');
    // execute test
    $value = $this->user->getAttribute('Foo');
    // verify results
    $this->assertEquals($value, 'Bar', 'The value was read from the session');
  }

  public function testAttributesAreWrittenToTheSession()
  {
  // ...
  }
}

What does this code do? First of all, we see that the test code is organized within a test class. This means that you can use all the power of object-orientation for testing, but it also implies that a certain amount of code overhead is required for defining the class’s structure.

All methods prefixed with “test” are test methods. These methods test that a certain requirement is successfully fulfilled by the tested class. Because most of the test methods need a common set of objects (the “fixture”), these objects are created in the method setUp(), which is executed once before every test method. As a result, each test method works with fresh objects; influences of the previously executed test methods are largely prevented.

We also notice that test methods have descriptive names (which, to be honest, tend to look very weird). The purpose is to allow the reader to quickly scan the method names of a test class to receive an impression of the tested class’s abilities.

In our single, exemplary test method, we first set up the fixture; we tell the fake session storage, which has been instantiated in setUp(), to return the value “Bar” when the method read("Foo") is called. Then we call getAttribute("Foo") on the user, which we expect to read from the session. In the last line of code, we assert that the returned value has indeed been read from the session.

Lime

Lime is a testing framework created by Fabien Potencier for testing the source code of the web framework symfony. It is based on the Test::More Perl library and aims for a very concise and readable test code. The above test in lime looks like this:

$t = new lime_test(1);

$t->comment('Attributes are read from the session');

  // fixture
  $s = new StubSessionStorage();
  $u = new User($s);
  $s->write('Foo', 'Bar');
  // test
  $value = $u->getAttribute('Foo');
  // assertions
  $t->is($value, 'Bar', 'The value was read from the session');

$t->comment('Attributes are written to the session');

  // ...

Contrary to PHPUnit, lime tests are written in a procedural way. Thus the code is more concise, because you don’t need to write down structural information of the code.

Initially a lime_test object is created, which tracks the number of expected, successful and failing tests and offers several methods to make testing easier. Each test case is, by convention, introduced by a comment that explains the tests purpose. Therefore the method comment() is called, which does also print the comment on the console when executing the test.

The test fixture has to be created manually for each test case. This is very prone to errors, because you can easily forget to reassign a variable once in a while. Then you’ll suddenly deal with an object left over from a previous test, which may lead to strange and unexpected test results.

Pro and Contra

Let us roughly sum up the advantages and disadvantages of both frameworks:

PHPUnit…

• … is verbose
• … offers magic methods like setUp(), which initiates your test fixture before every test
• … offers other convenient tools not covered in this blog post, like mocking support

lime…

• … is concise and readable
• … requires code repetition
• … requires you to initiate your fixture manually

sfLimeExtraPlugin extends lime and tries to introduce concepts of the xUnit family without making tests more verbose. Quite the opposite, because sfLimeExtraPlugin supports annotations, the written tests are even more concise than without this plugin.

Annotation-Driven Tests

The above test case, written with support of sfLimeExtraPlugin, looks like this:

$t = new lime_test_simple(1);

// @Before
$s = new StubSessionStorage();
$u = new User($s);

// @Test: Attributes are read from the session
// fixture
$s->write('Foo', 'Bar');
// test
$value = $u->getAttribute('Foo');
// assertions
$t->is($value, 'Bar', 'The value was read from the session');

// @Test: Attributes are written to the session
// ...

This test leads to exactly the same test results and console output as the test written with plain lime earlier in this post.

sfLimeExtraPlugin introduces the new class lime_test_simple. When you use that test class, you can mark sections of your code with so-called annotations. The test class knows, for example, that code annotated with @Before must be executed before every test case.

Single test cases are annotated with @Test. You can also add a comment about the purpose of the test. Note that the comment now really is a PHP comment, which is usually highlighted in a different color by code editors and thus disturbs the eye much less than the call to the method comment().

Several other annotations are available. I’ll shortly list all of them:

@Test

A test case

@Before

Executed before each test case

@After

Executed after each test case

@BeforeAll

Executed once before all test cases

@AfterAll

Executed once after all test cases

With these annotations, you can easily structure your test code and avoid code duplication while making your tests easier to read.

Testing for Exceptions

Contrary to plain lime_test, lime_test_simple allows you to automatically test whether exceptions are thrown. With plain lime_test, such a test would look like this:

$t->comment('setAttribute() throws an exception if the data contains <script> tags');

  // fixture
  $u = new User(new StubSessionStorage());
  // test
  try
  {
    $u->setAttribute('<script>alert("Evil!")</script>');
    $t->fail('setAttribute() throws an "InvalidArgumentException"');
  }
  catch (InvalidArgumentException $e)
  {
    $t->pass('setAttribute() throws an "InvalidArgumentException"');
  }

In this test, we try to catch the expected exception. If the exception is caught, we mark the test as passed, otherwise as failed.

With lime_test_simple, this is much easier:

// @Before
$u = new User(new StubSessionStorage());

// @Test: setAttribute() throws an exception if the data contains <script> tags
// fixture
$t->expect('InvalidArgumentException');
// test
$u->setAttribute('<script>alert("Evil!")</script>');

Mock and Stub Objects

Like PHPUnit, sfLimeExtraPlugin allows you to automatically generate fake objects, which are referred to as “Mocks” and “Stubs”. So far, we had to write our fake StubSessionStorage class by hand. With sfLimeExtraPlugin this is not needed anymore. The component lime_mock will generate such a class automatically:

// @Before
$s = lime_mock::create('SessionStorageInterface');
$u = new User($s);

// @Test: Attributes are read from the session
// fixture
$s->read('Foo')->returns('Bar');
$s->replay();
// test
$value = $u->getAttribute('Foo');
// assertions
$t->is($value, 'Bar', 'The value was read from the session');

Before the execution of each test case, we tell lime_mock to generate a new fake instance of SessionStorageInterface. In the test itself, we teach the fake object which methods can be called with what parameters and which value should be returned. We can also specify other constraints, such as how often a method may be called or which exception it should throw.

Then we switch the fake object into “replay” mode. In this mode, the fake object will behave just the way that we configured it before.

You can create stubs for interfaces, classes or abstract classes. You can even create stubs for non-existing classes, which is very convenient if you develop test-driven.

Because this topic deserves a whole blog post of its own, I won’t go into more detail here. For more information about Mocks and Stubs in general and their usage in sfLimeExtraPlugin in specific can be found on the readme page of sfLimeExtraPlugin.

Final Words

I personally think that tests can be written in a much more concise and readable way with sfLimeExtraPlugin. Because it also introduces other powerful features of the xUnit-family, the plugin aims to be an essential tool of every symfony developer who wants to seriously unit test his or her application.

Currently the plugin is available in version 0.2.0alpha. That means that the API may change before the final release (though this is unlikely) and that the code is not being considered 100% stable. I recommend you to try it out nevertheless and give me feedback about its usefulness or shortcomings, report bugs etc.

What do you think about sfLimeExtraPlugin? Do you think you may ever use it?

References

[1] Kent Beck, Donald G. Firesmith: Kent Beck’s Guide to Better Smalltalk. Cambridge University Press, 1998. Page 408

[2] Gerard Meszaros: xUnit Test Patterns. Refactoring Test Code. Addison-Wesley, 2007. Page 75

Related posts:

1. Symfony Day Cologne 2009 Today, I will take the plane to Cologne to attend...

Your app is slow? If the symfony web debug toolbar doesn’t give you the details you want, you can take a real deep look into your application using the profiling options of Xdebug.

In this tutorial we will set up Xdebug to profile your application and then we’ll analyse the output with KCachegrind.

By the way: Xdebug has a lot of other useful features. One that comes automatically is the nicely formated php debugging output in case of errors including the full call stack. KCachegrind on the other hand has very interesting graphical output features like the call graph. In the case of symfony the call graph can be like an interesting expedition into the functionality of the framework.

Installation

We’ll do the installation using Ubuntu Linux, but it works similar for other unixes or even Windows with a WAMP stack. Ah yes – we assume you have the correct environment for symfony installed (Apache, PHP5, …).

KCachegrind is not available for Windows. You can use WinCacheGrind instead although it doesn’t provide the graphical goodies.

Download and install:

sudo aptitude install php5-xdebug kcachegrind

Ubuntu automatically inserts the Xdebug module in the php ini files:

# /etc/php5/conf.d/xdebug.ini
zend_extension=/usr/lib/php5/20060613+lfs/xdebug.so

Now let’s restart apache to load the new configuration:

sudo apache2ctl restart

Let’s provoke an error and let us see if Xdebug works. I put an invalid function call into a php script:

// apps/frontend/modules/myModule/actions.class.php
class myModuleActions extends sfActions
{
  public function executeIndex()
  {
    invalid_function();
  }
}

Now we get the typical Xdebug output including the call stack in the browser, so we know it works:

Enable profiling

The profiling capability of Xdebug has to be explictly enabled because it produces A LOT of output and slows down the application serverely.

If you use .htaccess for your symfony project this is the easiest way to enable the profiling:

# web/.htaccess

# append at the end of the file:
php_value xdebug.profiler_enable 1
php_value xdebug.profiler_output_dir /tmp

If you don’t use .htaccess, or if you want to profile a cli php script, you have to enable the profiling in your php.ini (cli stands for command line interface). Example for the cli:

# /etc/php5/cli/conf.d/xdebug.ini

# append at the end of the file:
xdebug.profiler_output_dir = "/tmp"
xdebug.profiler_enable = 1

Don’t forget to restart apache if you changed the php.ini config!

Data galore…

Ok, let’s profile something! Just fire up your webbrowser and load any page of your local symfony project.
Xdebug now creates a “cachegrind” file like “cachegrind.out.22076 in your /tmp/ directory.

Here’s how a cachgrind file looks like:

version: 0.9.6
cmd: /var/www/ullright/web/index.php
part: 1

events: Time

fl=php:internal
fn=php::realpath
38 98

fl=/var/www/ullright/plugins/ullCorePlugin/lib/vendor/symfony/lib/autoload/sfCoreAutoload.class.php
fn=sfCoreAutoload->__construct
50 93
cfn=php::dirname
calls=1 0 0
38 2
cfn=php::realpath
calls=1 0 0
38 98

It basically records which function was called from which script file, how many times it was called and how long the execution took.

Now that isn’t really human readable, is it?

So let’s open the cachegrind file with KCachegrind. It looks something like this:

So what have we got here? On the left side you see the “Flat Profile”. A list of all function and method calls. From left to right:

• Incl. – The cost of the function including all child functions
• Self – The cost of the function itself
• Called – How many times a function was called
• Function – Which function
• Location – Script file

A good starting point is to click on “Called” to see which functions are called the most often. It’s also interesting to order by “Self” to see which method itself took the most time.

On the right side I selected the tab “Call Graph” which shows the sequence of the function calls starting with “{main}”. For symfony it’s usually “web/index.php”.

The number of nodes in the call graph is limited by the relative percentage of the execution time. Per default only functions that take more than 5% of the execution time are displayed. Get a more detailed graph by right clicking into the call graph and selecting “Graph -> Min. node cost -> 1%”. You can also doube click on any node to see a more detailed child-graph.

Here is a nice detailed graph showing the internals of a doctrine query.  I’d like to invite you to explore your symfony app using the call graph – it surely is an interesting journey and you can learn a lot about the architecture of symfony.

Coming to an end I’d like to hear about your experiences and findings about performance profiling:

• What tools do you use?
• What are your best practices?

Looking forward to interesting discussions – have a nice day!

Related posts:

1. Symfony Day Cologne 2009 Today, I will take the plane to Cologne to attend...

I will show you today how symfony could help you keeping all of your forms consistent with very little work left for you to do.

A Quick Look Back

In my last post I introduced you to the concept of field groups. Field groups are similar to embedded forms in that they group a set of form fields together and enable combined data binding and validation. They differ from embedded forms in that they can combine multiple fields to enter one single value. I showed you the example of a password field with two fields, that is used to enter one single value: The password.

Here is the code for the user profile form that we have developed in the course of this article series:

// lib/form/doctrine/ProfileForm.class.php
class ProfileForm extends sfFormDoctrine
{
  protected $user = null;

  public function __construct(sfUser $user)
  {
    $this->user = $user;
  }

  public function configure()
  {
    $this->addField('name', new sfTextField(15))
         ->setHelp('Your full name, f.i. "John Travolta"');
    $this->addField('email', new sfEmailField())
         ->setHelp('A valid email address, f.i. "john.travolta@gmail.com"');
    $this->addField('password', new VerifiedPasswordField())
         ->setHelp('Must not be "pulpfiction"');

    $this->setFinalValidator(
      new sfValidatorCallback($this, 'comparePasswordAndName')
    );

    if (!$this->user->hasCredential('admin'))
    {
      $this->getField('name')->setEditable(false);
    }
  }

  public function comparePasswordAndName(sfValidator $validator, array $values)
  {
    if ($values['name'] == $values['password'])
    {
      throw new sfValidatorError('The password must not be the same as the name',
          'password');
    }
  }
}

I invite you to compare this form with the original symfony implementation of the same functionality shown in my first post.

Form Layouts

Today I want to present you another advantage of the field groups. You can use “layouts” on them to automate the generation of HTML code in a very flexible way.

Right now, symfony offers two alternatives to create the HTML code of your forms.

1. Use one of the built-in form formatters “list” and “table”. These formatters are very unflexible because the whole form will be rendered in the same way. You cannot modify the formatters to render some parts as fieldsets, others as multi-column fields etc.
2. Code the HTML by hand in your templates. This way gives the most power to web designers. Unfortunately it also leads to a lot of code duplication in your templates that cannot be easily resolved by using partials. Maintaining this duplicate code is quite repetitive, tedious, and error prone™

Layouts help you to solve this problem. But what exactly are layouts?

In general, a layout is a set of different classes (the “formatters”) that specify how different parts of a form should be rendered. Look at the following sketch to get an idea of what layouts can do for you:

Usually, layouts render the individual fields in rows with the label to the left and the field to the right. You can change individual fields or field groups to be rendered in a different way: As fieldset (useful for field groups), with the label to the right (useful for checkboxes), with no label at all or with your very own custom formatter.

But layouts can do much more than formatting the individual rows: They also know how the formatted fields should be visually organized. You can, for example, display all fields in a horizontal row or organize them in a grid with multiple columns.

Each field group (the form is also a field group) has exactly one layout assigned that is used to organize the fields in this group. Because field groups can be nested within each other, you can also nest different layouts. Let’s look at a basic example that can be achieved very easily:

The password field and the permissions field group are configured to be formatted as fieldset. The permissions field group itself has a multi-column layout applied. Later in this post I will show you how little PHP code is necessary to achieve this result.

Apart from the visual aspect, layouts specify which HTML code will be used to render the form. sfListLayout renders the form in an ul tag, sfTableLayout renders the form in a … guess what .. right, in a table tag. Of course you can also implement your own layout that renders the whole form in a combination of address and blockquote tags, if that makes sense to you (tag misuse at its best!).

Multi-Column Layouts

Layouts with multiple columns are especially interesting. They help you to display a lot of information in little, well-organized space.

If you use ul-tags to render your form, a multi-column layout can be achieved very easily. You just need to change the CSS of the li-tags to make them floating. By giving them a fixed width, you can control how many form fields are displayed in a row.

There is a big problem with this solution though: Fields are first rendered from left to right, then from top to bottom.

This can be a problem if your fields are sorted in a specific order. A good example are large lists of checkboxes. If the labels of these fields are sorted alphabetically, users expect them to be sorted from top to bottom, then from left to right.

Layouts are able to deal with this problem easily. You can configure the number of columns and the order of the fields (”horizontal” or “vertical”) simply by passing these options to the layout’s constructor.

Show Me the Code

Configuring layouts in your form is easy. Every class inheriting from sfFormFieldGroup (thus also sfForm) offers the method setLayout(). To this method you can pass an instance of the layout you want to use.

  public function configure()
  {
    $this->setLayout(new sfListLayout());
  }

The different layout classes allow different options that you can pass to their constructor. Two such options are the number of columns and the order in which the fields are put into these columns.

  public function configure()
  {
    $this->setLayout(new sfListLayout(array(
      'columns' => 3,
      'order'   => sfLayout::VERTICAL,
    )));
  }

With as little code as this you have configured your form to organize all fields in 3 columns in a vertical order using ul and li-tags. You can achieve the same result using an HTML table by passing an instance of sfTableLayout instead of sfListLayout.

The format of the individual form fields can be modified by calling the method setFormat() on the field. To this method you pass the name of the format you want to use. The names of the different formats are declared in the layout class, as you will see later.

  public function configure()
  {
    $this->addField('password', new VerifiedPasswordField())
         ->setFormat('fieldset');
  }

After this simple definition, the password fields are rendered as in the picture above. Depending on the layout, there can be many more formats like “leftlabel” (the default), “nolabel” or “rightlabel”. Look at the first sketch in this post to see what these look like.

A More Complex Example

Now that we have learned about the basics, we can look at how to configure our user profile form to be displayed like in the above picture.

First, we tell our form to be rendered as HTML list.

  public function configure()
  {
    $this->setLayout(new sfListLayout());

Now we add the fields as we did before. Note the format that we have set on the password field to render it as a fieldset.

    $this->addField('name', new sfTextField(15))
         ->setHelp('Your full name, f.i. "John Travolta"');
    $this->addField('email', new sfEmailField())
         ->setHelp('A valid email address, f.i. "john.travolta@gmail.com"');
    $this->addField('password', new VerifiedPasswordField())
         ->setHelp('Must not be "pulpfiction"')
         ->setFormat('fieldset');

Just for fun, we’ll add a few checkboxes to our form to demonstrate how a multigrid layout is integrated.

    $permissions = array(
      'admin', 'blog-editor', 'content-editor',
      'publisher', 'file-editor', 'comment-editor',
    );
    $this->addField('permissions', new sfCheckboxList($permissions))
         ->setHelp('Choose one or more permissions for this user')
         ->setFormat('fieldset')
         ->setLayout(new sfListLayout(array('columns' => 3));

The last thing left is to declare the final validator and the user credential check again, but this code has not changed.

Let’s sum up what we have learned:

1. A format is the definition of how a single field is rendered
2. A layout is the definition of how a group of fields is organized

But What About the Web Designers?

I can hear voices screaming that I am violating the MVC separation with this proposal. But honestly, I am not. We still have one specific component that is responsible for generating the output of our form: The sfLayout instance. You can simply modify the way your form is rendered by exchanging its layout, which is what MVC is all about.

Many people misunderstand the MVC concept as it is applied in symfony. Although the view layer consists mostly of templates, it is not restricted to that. MVC simply requires you to program separate decoupled layers that can be easily exchanged. Whether you put the code of these layers in templates, classes or coke cans does not matter.

The good news is that you can do all the configuration from within your templates, if you don’t like to do it in your configure() method. All of the above methods are accessible using sfForm’s array access syntax. Together with a set of easy convenience methods, even web designers could configure the form’s format.

<?php $form->setLayout('list') ?>
<?php $form['password']->setFormat('fieldset') ?>
<?php $form['permissions']->setFormat('fieldset') ?>
<?php $form['permissions']->setLayout('list', array('columns' => 2)) ?>

<?php echo $form ?>

For small projects with one or only very few forms, I recommend you to not use layouts and formatters, if that eases the life of your web designers. You can still output the form the oldfashioned way and write all the HTML by hand.

sfLayout Internals

In the last part of our travel to the magic layout wonderland, I want to explain some of the internals of sfLayout to you.

The information in this section is only relevant when you create your own layout. You hardly ever need this information to simply configure your form.

All layouts must implement sfLayoutInterface.

interface sfLayoutInterface
{
  public function createFieldFormatter($format = null);
  public function createFieldGroupFormatter();
}

Layouts follow the Abstract Factory Pattern. That means that any class implementing sfLayoutInterface simply creates instances of other classes that are connected in some way.

Let’s visualize this very technical definition with a simple example: sfListLayout is able to create new sfFieldFormatter instances as well as sfFieldGroupFormatter instances. Because both instances must know that the form is rendered as ul-list, they structurally belong together. If you use a different layout, you get a different set of formatters that again know about each other. That’s what this pattern is about.

It is the responsibility of sfFieldFormatter and sfFieldGroupFormatter instances to turn the fields/field groups into HTML code.

sfLayoutInterface::createFieldFormatter() has one single parameter “format”. This format is exactly the format string that you have set on the form fields earlier using setFormat(). For each given format, the layout knows which object to return.

$layout = new sfListLayout();
$formatter = $layout->createFieldFormatter('rightlabel');
echo get_class($formatter);

// returns "sfRightLabelListFieldFormatter"

The great thing is that you never need to know about these long class names, because the layout you use hides them from you. All returned objects share the same interface: sfFieldFormatterInterface. You only ever need to know about this interface and never about the concrete class you receive.

interface sfFieldFormatterInterface
{
  public function render($id, $label, $value, $help, array $attributes = array());
}

Conclusion

Enough theory for today. I hope I was able to give you an idea of what power layouts can give to you. As you have seen, they can reduce code duplication in large applications with many forms and simplify the presentation of forms. There is much more to tell about layouts, but this post has grown long enough.

How do you like the layouts? Is this idea worth the time following?

Related posts:

1. Improving the Forms: Field Groups Today I want to follow up on my last post...
2. Improving the Forms After my last post about simplifying symfony and especially the...
3. No Piece of Cake Welcome to all of you on webmozarts.com! Whether you are...

This post will be different though. While I only made assumptions in my last post without any code verifying that my ideas are implementable, I do have a prototype implementation now.

Where Did We Stop?

In my last post, we left with the following form:

The idea was to have a user profile form where we can enter the name of the user, his email address and his password and are able to validate a few special conditions. I added a few help texts to enhance the look and usability of the form. Here is the code for the form:

// lib/form/doctrine/ProfileForm.class.php
class ProfileForm extends sfFormDoctrine
{
  protected $user = null;

  public function __construct(sfUser $user)
  {
    $this->user = $user;
  }

  public function configure()
  {
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15))
         ->setHelp('Your full name, f.i. "John Travolta"');

    $this->addField('email')
         ->setValidator(new sfValidatorEmail())
         ->setHelp('A valid email address, f.i. "john.travolta@gmail.com"');

    $this->addField('password', new PasswordField())
         ->setHelp('Must not be "pulpfiction"');

    $this->addField('password_again')
         ->setWidget(new sfWidgetPassword())
         ->setValidator(new sfValidatorPass())
         ->setLabel('Password (again)');

    $this->setFinalValidator(new sfValidatorAnd(
      new sfValidatorCompare('password_again', '==', 'password',
          'The passwords must be equal'),
      new sfValidatorCallback($this, 'comparePasswordAndName')
    ));

    if (!$this->user->hasCredential('admin'))
    {
      $this->getField('name')->setEditable(false);
    }
  }

  public function comparePasswordAndName(sfValidator $validator, array $values)
  {
    if ($values['name'] == $values['password'])
    {
      throw new sfValidatorError('The password must not be the same as the name',
          'password');
    }
  }
}

I introduced you to the concept of form fields that bundle a widget and a validator. If you have not read the post explaining this concept, I recommend you to read it now, because I will build up on it today.

Convention Over Configuration

Many forms in symfony applications share the same type of fields. An email address, for example, is in 95% of the cases a normal input widget with an email validator. Redefining this definition in different forms leads to code duplication, so we should extract it into a separate field type. If we do this for the most common field types, we come up with a nice little collection of fields that should be bundled with symfony by default:

• sfTextField (sfWidgetInput, sfValidatorString)
• sfTextareaField (sfWidgetTextarea, sfValidatorString)
• sfPasswordField (sfWidgetInputPassword, sfValidatorString)
• sfEmailField (sfWidgetInput, sfValidatorEmail)
• sfCheckboxField (sfWidgetCheckbox, sfValidatorBoolean)
• sfCountryField (sfWidgetI18nSelectCountry, sfValidatorI18nSelectCountry)
• sfLanguageField (sfWidgetI18nSelectLanguage, sfValidatorI18nSelectLanguage)
• sfSelectField (sfWidgetSelect, sfValidatorChoice)

I might have forgotten quite a few now, but you see where I am heading. With a decent collection of predefined fields you will only need to manually define widgets and validators in edge cases. This is especially great for beginners who do not have to learn about widgets and validators to create simple forms!

Let’s look at how we can reduce the above form definition even more by using these predefined fields:

  public function configure()
  {
    $this->addField('name', new sfTextField(15))
         ->setHelp('Your full name, f.i. "John Travolta"');
    $this->addField('email', new sfEmailField())
         ->setHelp('A valid email address, f.i. "john.travolta@gmail.com"');
    $this->addField('password', new sfPasswordField())
         ->setHelp('Must not be "pulpfiction"');
    $this->addField('password_again', new sfPasswordField())
         ->setValidator(new sfValidatorPass())
         ->setLabel('Password (again)');

    $this->setFinalValidator(new sfValidatorAnd(
      new sfValidatorCompare('password_again', '==', 'password',
          'The passwords must be equal'),
      new sfValidatorCallback($this, 'comparePasswordAndName')
    ));

Field Groups

So far, I have left the question open about how we can bundle the two password fields together, so you can just drop them into any form. The idea to solve this problem is to create field groups as proposed by David.

A field group is simply a collection of fields that logically belong together. These fields may share a common initial and final validator, a common label, a common help text and a few other things. You will see that field groups are very similar to embedded form as they exist right now.

In fact, a form is a field group with a few extra abilities such as CSRF protection, form tag generation etc.

Normal fields and field groups share a common interface. In practice, this means that you can simply add groups by calling addField() and nest groups inside each other. It does also mean that the developer doesn’t necessarily need to know whether a field is a “normal” field or a field group, which is exactly what we will do with the password field.

To understand the implementation, we will look at the common interface sfFormFieldInterface first:

interface sfFormFieldInterface
{
  public function bind($taintedValue, $taintedFile);
  public function getData();
  public function getId();
  public function getLabel();
  public function getHelp();
  public function render();
  ...
}

You may wonder what the methods bind() and getData() do in a form field. To use the real power of object orientation, the bound values are delegated from the form to all nested fields and field groups, where they are validated. The form can collect the cleaned values again by calling getData() on all fields and field groups. Because embedded forms are nothing more than field groups, this implementation also solves the common problem that bind() is not called on embedded forms.

Now we can finally implement our combined password field. The combined field extends sfFormFieldGroup which already implements sfFormFieldInterface, so we only need to configure the field:

class VerifiedPasswordField extends sfFormFieldGroup
{
  public function configure()
  {
    $this->addField('first', new sfPasswordField());
    $this->addField('second', new sfPasswordField())
         ->setValidator(new sfValidatorPass())
         ->setLabel('Password (again)');

    $this->setFinalValidator(
      new sfValidatorCompare('second', '==', 'first',
          'The passwords must be equal')
    );
  }
}

Now we can simply drop our password field into the form:

  public function configure()
  {
    $this->addField('password', new VerifiedPasswordField())
         ->setHelp('Must not be "pulpfiction"');
  }

Alert readers might have noticed that the password fields are now named “first” and “second”. Do you wonder how that will be translated into form field names? It works just the same way as it does now for embedded forms: The name of the internal field is appended to the name of the external field in squared brackets (f.i. “password[first]“).

Now you probably think that this implementation makes things harder than they were! When processing the values after a successful validation, we need to know that the password is stored in “password[first]” instead of simply “password”!

Calm down old boy, help is on the way. To find our solution, let’s look at the output of the method VerifiedPasswordField::getData(), which returns the cleaned values of the field group:

// VerifiedPasswordField::getData()
array(
  'first' => 'The password',
  'second' => 'The password',
)

Hm, any idea? Let’s also look at the output of ProfileForm::getData().

// ProfileForm::getData()
array(
  'name' => 'The name',
  'email' => 'thename@gmail.com',
  'password' => array(
    'first' => 'The password',
    'second' => 'The password',
  ),
)

Did you already find the solution? I’ll tell you: It’s fairly easy. We just need to modify getData() in VerifiedPasswordField to just return a single password instead of an array.

  public function getData()
  {
    $data = parent::getData();

    return $data['first'];
  }

Now you probably understand why getData() isn’t named getValues(), like it is in the forms framework right now. The problem is that getData() can return single values (in simple fields) or arrays (in field groups). Naming the method getValues() would implicate that it always returns an array.

Time To Relax

If you made it until here, the hardest part of this post is over. Field groups allow us to easily implement and reuse a set of fields. As you have seen, we can even use field groups as if they were a single field. Especially in large applications, this architecture can hugely simplify your form definitions and reduce duplicate code.

You can, of course, create field groups on the fly, if you want to logically group fields together:

  public function configure()
  {
    $group = $this->addGroup('personal')
          ->setLabel('Personal Information')
          ->setHelp('Please enter your personal information here so we can sell it');
    $group->addField('first_name')
          ->setLabel('First name');
    $group->addField('surname');
  }

$form->addGroup('groupname')

$form->addGroup('groupname', new sfFormFieldGroup())

$form->addField('groupname', new sfFormFieldGroup())

In my next post, I will speak about how formatters and group layouts can help you to reduce duplicate code in your form templates and help you to sustain a uniform look in applications with many forms. You will learn that the structural information stored in field groups can easily be used to generate a visually appealing presentation.

How do you like the field groups? Are there any use cases that cannot be implemented with this architecture?

Related posts:

1. Improving the Forms: Layouts and Formatters Keeping all parts of a website consistent is one of...
2. Improving the Forms After my last post about simplifying symfony and especially the...
3. No Piece of Cake Welcome to all of you on webmozarts.com! Whether you are...

The Situation

In my last post I introduced you to the following situation: A form should allow to edit a user’s name, email address and password. The name should only be editable by administrators, while the password should be entered twice to make sure it was entered correctly. The maximum length of the name is 15 characters and the password should not be the same as the name.

We came up with the following class:

// lib/form/doctrine/ProfileForm.class.php
class ProfileForm extends sfFormDoctrine
{
  protected $user = null;

  public function __construct(sfUser $user)
  {
    $this->user = $user;
  }

  public function configure()
  {
    $this->setWidgets(array(
      'name'           => new sfWidgetFormInput(array(), array(
        'max_length' => 15
      ),
      'email'          => new sfWidgetFormInput(),
      'password'       => new sfWidgetFormInputPassword(),
      'password_again' => new sfWidgetFormInputPassword(),
    ));
    $this->widgetSchema->setLabel('password_again', 'Password (again)');

    $this->setValidators(array(
      'name'           => new sfValidatorString(array(
        'max_length' => 15
      ), array(
        'max_length' => 'The name must be 15 characters or longer'
      ),
      'email'          => new sfValidatorEmail(array(), array(
        'required' => 'Please enter your email address',
      )),
      'password'       => new sfValidatorString(array(), array(
        'required' => 'Please enter a password',
      )),
      'password_again' => new sfValidatorPass(),
    ));

    // implement custom validation logic
    $this->validatorSchema->setPostValidator(new sfValidatorAnd(array(
      new sfValidatorSchemaCompare('password_again', '==', 'password', array(
        'invalid' => 'The passwords must be equal'
      )),
      new sfValidatorCallback(array(
        'callback' => array($this, 'comparePasswordAndName')
      )),
    )));

    // only administrators may enter the user name
    if (!$this->user->hasCredential('admin'))
    {
      unset($this['name']);
    }
  }

  public function comparePasswordAndName(sfValidator $validator, array $values)
  {
    // if the field "name" is not editable, it does not exist in $values
    if (array_key_exists('name', $values) && $values['name'] == $values['password'])
    {
      $error = new sfValidatorError($validator,
          'The password must not be the same as the name');

      // throw an error schema so the error appears at the field "password"
      throw new sfValidatorErrorSchema($validator, array('password', $error));
    }
  }
}

The Issues

The above form definition bears several issues:

• It is not possible to abstract form fields that combine a widget, a validator and possible other settings. You might want to use a password field in several forms so it should be possible to extract that definition into a separate class.
• To configure the form, you need to know about the widget schema and the validator schema. You also need to know where to call which method. For instance, you need to call setWidgets() on the form, setLabels() on the widget schema and setPostValidator() on the validator schema.
• Nearly none of the default validator error messages like “Invalid.” or “Required.” are useful in production, thus we always have to configure them. Validators should provide sensible defaults for these errors to reduce the amount of configuration.
• Some of the used classes have complex constructor signatures that are hard to remember. sfValidatorCallback, for instance is always called with a callback. It should be possible to pass the callback directly to its constructor without having to create addtional arrays.
• If the user is not administrator, the field “name” is not available. Because of that we must implement additional checks everytime we access the form values to find out whether the name has been set. But, in fact, the name value should always be there. It just is not always editable.
• Throwing a custom validation error and binding it to a specific field is tedious.

I was searching for ways to improve these issues and will explain them in more detail below.

Form Field Abstraction

It was very useful if you could abstract form fields in symfony that combine a validator, a widget and possible other settings. Let’s just imagine for this post that sfField is a class that allows bundling a widget and a validator.

I don’t think that including the “form” in the name is necessary (f.i. sfFormField). The “sf” prefix is reserved to symfony core classes and I can’t think of any other context in the core where an sfField class could serve useful. KISS.

To create our custom password field, we would just extend sfField and combine the logic inside.

// lib/form/fields/PasswordField.class.php
class PasswordField extends sfField
{
  public function configure()
  {
    $this->setWidget(new sfWidgetInputPassword());
    $this->setValidator(new sfValidatorString(array(), array(
      'required' => 'Please enter a password',
    ));
  }
}

Great! A neatly decoupled definition of a password field. But how should we add this field to a form? Probably with the most obvious method name there is for this task: addField().

// lib/form/doctrine/ProfileForm.class.php
class ProfileForm
{
  public function configure()
  {
    $this->addField('password', new PasswordField());
    ...
  }
}

Can it be easier?

You may ask yourself whether we can’t just bundle the second field for repeating our password as well. We certainly could, but I’ll leave the answer for this question to another post.

Widgets and Validators

As said before, we currently need to know a lot about the form’s internals to configure it successfully. We need to know about sfWidgetFormSchema, sfValidatorSchema and sfForm and their respective methods. Couldn’t we simplify that somewhat?

Let’s wait for a moment. In the previous section we introduced a new class sfField that bundles a widget, a validator and possible other settings. We also introduced a method addField() that adds a form field to the form.

Now we could return the added field from addField() and allow a modification of its widget, validator, label and other properties in a fluent coding style!

Let’s look at how the form’s configure() method looks like with these modifications:

  public function configure()
  {
    $this->addField('name', new sfField())
         ->setWidget(new sfWidgetInput(array(), array('max_length' => 15)))
         ->setValidator(new sfValidatorString(array('max_length' => 15)));

    $this->addField('email', new sfField())
         ->setWidget(new sfWidgetInput())
         ->setValidator(new sfValidatorEmail());

    $this->addField('password', new PasswordField());

    $this->addField('password_again', new sfField())
         ->setWidget(new sfWidgetInputPassword())
         ->setValidator(new sfValidatorPass())
         ->setLabel('Password (again)');
    ...
  }

Doesn’t look too bad. To reduce the amount of code, addField() could always add an instance of sfField, if no field is given, and preconfigure it with sfWidgetInput and sfValidatorString. Then we could introduce new methods sfField::setWidgetOptions(), sfField::setWidgetAttributes() and sfField::setValidatorOptions() that allow a fluent modification of these properties.

  public function configure()
  {
    $this->addField('name') // implicitly sfWidgetInput and sfValidatorString
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15));

    $this->addField('email') // implicitly sfWidgetInput
         ->setValidator(new sfValidatorEmail(array(), array(
           'required' => 'Please enter your email address',
         )));

    $this->addField('password', new PasswordField());

    $this->addField('password_again')
         ->setWidget(new sfWidgetInputPassword())
         ->setValidator(new sfValidatorPass())
         ->setLabel('Password (again)');
    ...
  }

Again our code became a bit easier to read and write. For reference, here is how the configuration of these settings was like before:

  // before
  public function configure()
  {
    $this->setWidgets(array(
      'name'           => new sfWidgetFormInput(array(), array(
        'max_length' => 15
      ),
      'email'          => new sfWidgetFormInput(),
      'password'       => new sfWidgetFormInputPassword(),
      'password_again' => new sfWidgetFormInputPassword(),
    ));
    $this->widgetSchema->setLabel('password_again', 'Password (again)');

    $this->setValidators(array(
      'name'           => new sfValidatorString(array(
        'max_length' => 15
      ), array(
        'max_length' => 'The name must be 15 characters or longer'
      ),
      'email'          => new sfValidatorEmail(array(), array(
        'required' => 'Please enter your email address',
      )),
      'password'       => new sfValidatorString(array(), array(
        'required' => 'Please enter a password',
      )),
      'password_again' => new sfValidatorPass(),
    ));
    ...
  }

Sensible Default Error Messages

Nearly all default error messages of the validators are absolutely unusable in a production environment. If you listen to the big usability gurus like Jakob Nielsen (see his Error Messages Guidelines), error messages should give “Constructive advice on how to fix the problem”. “Required.” and “Invalid.”, unfortunately, do not.

I think that all validators should be preconfigured with sensible error messages. Examples for the “required” and “invalid” errors of sfValidatorEmail are “Please enter an email address” and “The given email address is not valid”.

With sensible default messages, we can yet again reduce the complexity of our code:

  public function configure()
  {
    ...
    $this->addField('email')
         ->setValidator(new sfValidatorEmail());
    ...
  }

Compared to before:

  // before
  public function configure()
  {
    ...
    $this->addField('email')
         ->setValidator(new sfValidatorEmail(array(), array(
           'required' => 'Please enter your email address',
         )));
    ...
  }

The Post Validator

Now I’ll look at how to improve the post validator of our profile form. Basically I think the name is a bit weird. I am familiar with the latin expression “post”, but wouldn’t the english expression “final” fit in better?

Let’s imagine we live in an ideal world where setPostValidator() can be moved to sfForm and renamed to setFinalValidator().

$this->setFinalValidator(...);

Okay. Next step: sfValidatorAnd and its contained validators. First of all, I think we could extend sfValidatorAnd to accept an infinite number of arguments or an array containing these arguments. In Java we would achieve this by overloading the method. In PHP we cannot overload methods, but due to the weak typing we can still simulate this behaviour with one method.

There’s another candidate for simplification: sfValidatorCallback. Let’s just recall the current usage of this class:

new sfValidatorCallback(array('callback' => array($this, 'comparePasswordAndName')));

Why is this so complicated? It’s obvious that we want to pass a callback to this class. A callback can be either a single string or an array with two entries. We can again “overload” the constructor to accept either a single argument (a function name) or two arguments (a class or object method).

new sfValidatorCallback($this, 'comparePasswordAndName');

Much better. Last step: sfValidatorSchemaCompare. I think the usage of its constructor is pretty straight-forward. Because I can never remember its name, this validator should be renamed to sfValidatorCompare (KISS). Furthermore it is always necessary to pass an error message to this class, so why not make it the fourth argument?

new sfValidatorCompare('password_repeat', '==', 'password',
    'The passwords must match');

Now we can draw the whole picture of our final validator:

    $this->setFinalValidator(new sfValidatorAnd(
      new sfValidatorCompare('password_repeat', '==', 'password',
          'The passwords must match'),
      new sfValidatorCallback($this, 'comparePasswordAndName')
    ));

Isn’t this much nicer to read? Here’s the old definition again:

    // before
    $this->validatorSchema->setPostValidator(new sfValidatorAnd(array(
      new sfValidatorSchemaCompare('password_again', '==', 'password', array(
        'invalid' => 'The passwords must be equal'
      )),
      new sfValidatorCallback(array(
        'callback' => array($this, 'comparePasswordAndName')
      )),
    )));

Editable vs. Non-Editable

In forms it is very common to display some fields as editable and some fields as non-editable depending on the user’s rights. Just think of a common article form. The administrator may be able to change the author of an article, while the editor may only be allowed to see the author.

In the past, I have read several times that people would like to set fields to read-only in the admin generator. One such situation was the discussion about the admin generator for symfony 1.2. Since the admin generator is now based on the forms framework, this would be essentially the same feature.

The idea is to extend the current sfWidgetForm class to have two different states: “editable” and “non-editable”. Dependent on the state, each widget renders different HTML. Let’s look at sfWidgetFormInputDate for example. If this widget is editable, it displays the three select fields that we all know. But if the widget is not editable, it renders the date as plain text in the configured culture.

Do you notice something? If such a widget is implemented, it is essentially not a form widget anymore, but just “a widget”. In this case we could remove the “Form” from its name and reuse the widget in other components, such as sfGrid .

Let’s look at the configuration of our “name” field with this new widget concept. Instead of removing the field when the user is not an administrator, we just disable it.

    if (!$this->user->hasCredential('admin'))
    {
      $this->getField('name')->setEditable(false);
    }

That’s all! Compared to before:

    // before
    if (!$this->user->hasCredential('admin'))
    {
      unset($this['name']);
    }

The form should still populate the “name” value after submitting so that we do not have to care about whether the field was editable or not. The submitted value should just be ignored then.

Throwing Custom Validation Errors

Let’s be honest. Throwing custom validation errors is a pain in the ass. You must remember to pass the validator itself to the error, and then you need to construct an sfValidatorErrorSchema just to associate the error with a field.

In my opinion this should be much easier. The only reason why sfValidatorError requires a passed validator is to populate the error message internally. Why don’t we just pass the error message?

Second, sfValidatorError’s constructor could simply accept an optional parameter that specifies the field the validator belongs to.

How does that all look like? Let’s look at our refactored method comparePasswordAndName():

  public function comparePasswordAndName(sfValidator $validator, array $values)
  {
    if ($values['name'] == $values['password'])
    {
      throw new sfValidatorError('The password must not be the same as the name',
          'password');
    }
  }

Now that was easy! Here’s the old definition:

  // before
  public function comparePasswordAndName(sfValidator $validator, array $values)
  {
    // if the field "name" is not editable, it does not exist in $values
    if (array_key_exists('name', $values) && $values['name'] == $values['password'])
    {
      $error = new sfValidatorError($validator,
          'The password must not be the same as the name');

      // throw an error schema so the error appears at the field "password"
      throw new sfValidatorErrorSchema($validator, array('password', $error));
    }
  }

Conclusion

I think we don’t need to drop object oriented concepts to facilitate the use of the forms. The interface of this framework can be easy while remaining completely well-designed and flexible.

Here you can see the complete new form definition. Especially note the shorter widget names.

// lib/form/doctrine/ProfileForm.class.php
class ProfileForm extends sfFormDoctrine
{
  protected $user = null;

  public function __construct(sfUser $user)
  {
    $this->user = $user;
  }

  public function configure()
  {
    $this->addField('name')
         ->setWidgetAttributes(array('max_length' => 15))
         ->setValidatorOptions(array('max_length' => 15));

    $this->addField('email')
         ->setValidator(new sfValidatorEmail());

    $this->addField('password', new PasswordField());

    $this->addField('password_again')
         ->setWidget(new sfWidgetPassword())
         ->setValidator(new sfValidatorPass())
         ->setLabel('Password (again)');

    $this->setFinalValidator(new sfValidatorAnd(
      new sfValidatorCompare('password_again', '==', 'password',
          'The passwords must be equal'),
      new sfValidatorCallback($this, 'comparePasswordAndName')
    ));

    if (!$this->user->hasCredential('admin'))
    {
      $this->getField('name')->setEditable(false);
    }
  }

  public function comparePasswordAndName(sfValidator $validator, array $values)
  {
    if ($values['name'] == $values['password'])
    {
      throw new sfValidatorError('The password must not be the same as the name',
          'password');
    }
  }
}

The above ideas are only very rough and conceptual. I was thinking about how the interface would be ideal from the user’s point of view without verifying whether it is implementable and, if yes, how. But that’s a whole different story anyway. Usually, usability should drive implementation, not the other way round.

I did focus this post on this specific ProfileForm. There are several issues with the form framework that remain to be discussed. One example is how to bundle the two password fields and their post validator to be able to just drop them into any form. Another example is the internal processing of embedded forms. But these topics belong entirely to a new post.

How do you like this interface? Has it flaws and how can it be improved?

Related posts:

1. Improving the Forms: Field Groups Today I want to follow up on my last post...
2. Improving the Forms: Layouts and Formatters Keeping all parts of a website consistent is one of...
3. No Piece of Cake Welcome to all of you on webmozarts.com! Whether you are...

With our first post, I want to talk about symfony and where this blog is heading. And I don’t mean “symphony” as in music – no! Scrap that “ph”. It’s “symfony”, one of the greatest web frameworks that has been developed in PHP5 so far. (If you ever dare to write symfony with “ph”, tiny kittens will suffer!)

Symfony is by a large part a product of Fabien Potencier’s ingenuity and dedication. I want to deeply express my respect for his work at this point. The framework is a very well-thought piece of work and can immensely boost your productivity.

The amount of features and the complexity come with a drawback though: It takes a lot of time to learn how to develop efficiently with symfony. Many PHP developers are overwhelmed by the object-oriented concepts applied in the framework. Many call for a simplified version and I must agree that symfony suffers some usability problems lately. But why is that and how can we improve the current situation?

The Average Developer

Let’s face it. The average PHP developer knows nothing about “Design Patterns”, “Unit Tests” or “Refactoring”. In the course of my job I had to interview a lot of potential employees. Not only once I faced total ignorance when I talked about these or similar topics. Even basic understanding of PHP could not be taken for granted! What struck me most was that many of these people programmed PHP applications for a living, some of them for more than a decade.

What happens when you confront these developers with symfony? It’s like when my grandma got a computer. It took so much time to teach her using the mouse that telling her about how to write a letter would just have made no sense.

In my opinion, every PHP developer who is familiar enough with the language itself should be able to learn symfony.  If we want to raise the general quality and standards of PHP applications, we must reach these developers. Lowering the burdens for them to learn the framework is crucial for its future community.

Back To Basics

The excellent documentation of symfony obviously is a great help. I remember when I read the symfony documentation for the first time. Its great writing, the presented simplicity of powerful features really struck me. Every couple of pages I was astonished  by the fact that programming in PHP could be so easy! I was torn apart, because I had to read on while I just felt the urgent desire to start programming. Anything.

Unfortunately, this feeling of simplicity quickly fades away when you get started. Questions over questions arise. Where do I put that code? What method again should I use? Is it better to write it this or that way?

Now this is the case for every major programming library. You can’t expect to read a little of the documentation and be an expert (in this case it probably wouldn’t even be worth to use the library). What you can do is look at the code of others, extract the common ideas and find out for yourself how to best organize your code.

What you are searching for is generally referred to as “Best Practices”. The Jobeet tutorial did a great job at presenting such best practices. But further than just being documented, the described concepts must be simple enough for you to remember them next time you need them. And this, partly, is symfony’s weak point.

Forms By Example

To demonstrate my argument, let’s look at how to create a basic profile form in symfony. This form should allow to edit a user’s name, email address and password. The name should only be editable by administrators, while the password should be entered twice to make sure it was entered correctly. The maximum length of the name is 15 characters and the password should not be the same as the name.

Let’s start with the constructor. We need to alter the form depending on the authentication of the current user session, thus we pass the user object to the form.

// lib/form/doctrine/ProfileForm.class.php
class ProfileForm extends sfFormDoctrine
{
  protected $user = null;

  public function __construct(sfUser $user)
  {
    $this->user = $user;
  }

So far so good. Now let’s configure the form’s appearance and validation logic.

  public function configure()
  {
    $this->setWidgets(array(
      'email'          => new sfWidgetFormInput(),
      'password'       => new sfWidgetFormInputPassword(),
      'password_again' => new sfWidgetFormInputPassword(),
    ));
    $this->widgetSchema->setLabel('password_again', 'Password (again)');

    $this->setValidators(array(
      'email'          => new sfValidatorEmail(array(), array(
        'required' => 'Please enter your email address',
      )),
      'password'       => new sfValidatorString(array(), array(
        'required' => 'Please enter a password',
      )),
      'password_again' => new sfValidatorPass(),
    ));

    // implement custom validation logic
    $this->validatorSchema->setPostValidator(new sfValidatorAnd(array(
      new sfValidatorSchemaCompare('password_again', '==', 'password', array(
        'invalid' => 'The passwords must be equal'
      )),
      new sfValidatorCallback(array(
        'callback' => array($this, 'comparePasswordAndName')
      )),
    )));

    // administrators may enter the user name
    if ($this->user->hasCredential('admin'))
    {
      $this->setWidget('name', new sfWidgetFormInput(array(), array(
        'max_length' => 15
      ));
      $this->setValidator('name', new sfValidatorString(array(
        'max_length' => 15
      ), array(
        'max_length' => 'The name must be 15 characters or longer'
      );
    }
  }

Phew, there’s already a lot going on. We need to know about the widget schema and the validator schema. These are tricky, because for example setWidgets() is called on the form directly, while setLabel() is called on the widget schema. Don’t get that wrong.

Then you need to pass the error messages that are displayed when the fields are not filled out, because the default “Required.” is not really usable for a customer.

The post validator is especially tricky. Once you understood the concept, you need to remember to set it on the validator schema, use sfValidatorAnd with a couple of braces thrown in and mix it with sfValidatorSchemaCompare and sfValidatorCallback. Not easy.

The last thing is to add the “name” field and validator only when the user is administrator. This especially causes complications, because then the field “name” is not always present in the form values, which requires extra checks and template customizations from you. We need to configure the “max_length” constraint twice, once on the input field and once on the validator.  Again we override the error message, because the default is not usable.

What is missing now is the method that checks that the password and name differ:

  public function comparePasswordAndName(sfValidator $validator, array $values)
  {
    // if the field "name" is not editable, it does not exist in $values
    if (array_key_exists('name', $values) && $values['name'] == $values['password'])
    {
      $error = new sfValidatorError($validator,
          'The password must not be the same as the name');

      // throw an error schema so the error appears at the field "password"
      throw new sfValidatorErrorSchema($validator, array('password', $error));
    }
  }
}

If you want to set an error for the form, you basically need to throw an sfValidatorError, which behaves like an exception. Because the error should be displayed at the password field, we need to wrap it with an sfValidatorErrorSchema instance and associate it with the fieldname “password”.

This form is not yet complete. The logic to save the profile is still missing, but the above implementation pretty well demonstrates what I want to show.

Tying It All Together

If you go back and re-read the form requirements, you will see that these requirements are not uncommon even for very basic websites. Still the implementation requires you to know many different concepts. Altering the form based on the authentication status, modifying field labels, limiting field lengths, implementing custom validation logic, all of this is so common that it should be far easier. The default error messages should only need to be overridden in edge cases. Don’t expect that the average developers that I spoke about will get that right.

In my opinion, symfony must strive for absolute simplicity. The easier it is to explain its use, the quicker new developers will grasp the real power that lies under the hood of this framework. Together with a well-defined set of recommendations and best practices we will be able to teach new developers and expand the community. And we will be able to help those “average PHP developers” to step into the world of powerful object-oriented concepts.

This is the goal of this blog. We want to analyze our work and present best practices to improve your development. We want to speak about symfony’s strengths and learn about symfony’s flaws to point out possible solutions. We want to teach object oriented concepts in PHP5. We want to investigate what the community needs and try to find answers. Of course, we also want to present our own work. And last but not least, we do want to hear your feedback.

In the coming weeks I will think about possible solutions to the above problems with the Forms framework and post them on this blog. I would also appreciate to hear your ideas.

What is your experience with this new component? Is symfony simple enough for you?

Related posts:

1. Improving the Forms: Layouts and Formatters Keeping all parts of a website consistent is one of...
2. Improving the Forms: Field Groups Today I want to follow up on my last post...
3. Improving the Forms After my last post about simplifying symfony and especially the...