Test Balance

The more tests you have for your application, the more difficult it becomes to introduce changes. Everytime you change an existing feature, you have to change at least one test. Everytime you make a refactoring of your project’s architecture (which you should do frequently), you most likely need to adapt multiple tests. As a rule of thumb you can say that the more tests you have, the more difficult it becomes to make changes in your code.

We know that not to write tests is not a solution. Lots of tests, on the other hand, are bad for maintainability. Instead, try to keep a certain test balance by testing only what is important. The following section shows you one possible approach for identifying important tests called risk-based testing.

Risk-Based Testing

The purpose of testing is to avoid regressions in your software resulting of its complexity. These potential regressions can be expressed as risks ranked by their probability and severity. The probability expresses how likely the regression is to occur. The severity expresses how severely the regression would affect the functionality of your application. Both can be expressed in numbers, for instance in a range of 1 to 10 with 10 being the highest severity/probability. Look at the following table for example:

The table contains risks for two fictitious methods getGroup() and calculatePrice(). Imagine that the first of these methods only returns an internal property $group. The probability of someone breaking this code by accident is near to non-existent. Assume further that the group is only used for display purposes, so the severity of a broken code is not very high either.

The second method, calculatePrice(), uses an internal algorithm to calculate the price of a product. Because it depends on an external object $product, and because the algorithm is non-trivial, the probability of breaking the code is rather high. Even higher though is the severity of a broken functionality – what could be worse than wrongly calculated prices.

Is it worth to unit-test getGroup()? Probably not. We calculated an overall total of 3, which (in our scale from 1 to 100) is really not that impressive. Is it, on the other hand, worth to test calculatePrice()? Judge for yourself.

Obviously I selected two extreme examples here. Also you will almost never calculate probabilities and severities for testing single methods like I did it here. But you should try to develop a feeling for what is worth to be tested and what is not.

Test Complexity

Now that you have identified which risks you should cover in your test suite, the question is to what extent you should do so. Look at the following to approaches for testing calculatePrice():

Approach 1: The fair-enough approach

$t = new LimeTest();

// @Test: calculatePrice() multiplies the price with the amount

  $product = new Product();
  $product->price = 100;
  $product->amount = 2;
  $t->is($calculator->calculatePrice($product), 200);

Approach 2: The safe approach

$t = new LimeTest();

// @Before

  $product = new Product();
  $product->price = 100;

// @Test: calculatePrice() multiplies the price with the amount (amount == 1)

  $product->amount = 1;
  $t->is($calculator->calculatePrice($product), 100);

// @Test: calculatePrice() multiplies the price with the amount (amount == 2)

  $product->amount = 2;
  $t->is($calculator->calculatePrice($product), 200);

The first approach assumes that testing whether the result equals price multiplied by amount is enough. The test can obviously not check whether the developer has hard-coded a fixed return value of 200 or uses a fixed amount of 2. It expects the developer to be reasonable.

The second approach takes care of these eventualities by writing another test to make sure that changed amounts result in changed outputs. But even now, the developer could write a simple switch statement in calculatePrice() and return either 100 or 200, based on the amount. The test will not notice.

The conclusion is that you can never test your code for all eventualities. However complicated your test may be, there will always be a way to fake the implementation. But is it likely that developers will fake it? Probably not. This being said, the best approach in my opinion is approach 1 because it keeps effort required to adapt or change the test to a minimum.

Conclusion

Don’t try to achieve 100% test coverage. Identify the most important risks, and test for those. Don’t test for all eventualities either. Always keep in mind that the developers working on your code are somewhat reasonable people. If they aren’t, you are probably better off without them anyway.

Related posts:

1. Writing Efficient Tests Unit testing can be a blessing and curse at the...

What happened?

Unit vs. System Tests

To begin with, you need to understand the difference between unit and system tests and the impact both have on testing performance.

Unit tests are atomic. They test classes and components in isolation from any other service they depend on. Such services can be external services, like mailing systems, databases or webservices, and internal services, like a calculator, a data store or similar service classes. Running these tests in isolation gives you several advantages:

• Speed of execution
• Speed of development
• Test confidence

Speed of execution, because the test doesn’t need to wait for the related service to process its internal logic. Speed of development, because you (hopefully) don’t have to adapt the test when you refactor the internals of the related service class or add new features to it. And test confidence, because the test will only fail when the tested class is erroneous, not if any of the related services provide wrong data.

System tests (acceptance or functional tests are a kind of system tests) test whether all the classes in your application collaborate correctly. Because you unit tested these classes in isolation, you had to assume how collaborating services should behave. If this assumption is wrong, no unit test will tell you. And that’s the space that system tests fill. The big, big disadavantage of system tests is that they are slow. They have to initialize the application, read its configuration files, initialize its database with fresh data (it doesn’t make a lot of sense to disconnect system tests from the real database) and more. All this takes time.

The conclusion from the last paragraphs is that features of your application should always be tested in unit tests. These tests are fast and guide you to the error if things go wrong. There is nothing more harmful to test performance than testing whether a form works correctly by means of a system test. If the form is a class, write a unit test. If the form is no class, make it one.

Decouple Your Code

If you reach the point that you have lots of unit tests and few system tests, you made the first step towards becoming a test speed king. The second step is to decouple your classes.

Highly coupled code negatively affects your development in several ways. Because your code depends on other classes, these other classes (the dependent-on components or DOCs) all have to be instantiated during testing. Depending on their nature, this process may take time and slow your test down. Introducing new features becomes difficult because it results in lot of test code that needs to be adapted. If one of your classes breaks, not only the test of the class fails, but also several other tests of dependent classes. Shortly spoken: Extending and maintaining the application becomes a nightmare.

To decouple your code, get a clear picture of the responsibilities inside of your application. If a class does too much, tear it apart like a wild monkey smelling a banana in a big pile of waste paper.

The following code samples are based on the PHP5 frameworks symfony, Doctrine and Lime 2. The same concepts can be applied to other frameworks and languages just as well.

Let’s look at a (slightly modified) example I recently saw in a code review:

class sfValidatorUsername
{
  public function clean($value)
  {
    $user = Doctrine_Query::create()
      ->from('User u')
      ->where('u.name = ? AND u.active = 1', $value)
      ->fetchOne();

    if (is_null($user))
    {
      throw new sfValidatorError('invalid', $this);
    }

    return $value;
  }
}

It should be pretty obvious what this code is doing. What is the problem? The validator depends on the database. This is not a problem per se, but querying the database for User objects is beyond the validator’s responsibilities. This task should rather be done by your data acccess objects (DAOs), entity stores, tables or whatever you call them. And these objects can easily be injected into the validator using Dependency Injection.

Happy that we have identified this code smell, we can already start removing it:

class sfValidatorUsername
{
  protected $table;

  public function __construct(UserTable $table)
  {
    $this->table = $table;
  }

  public function clean($value)
  {
    if (is_null($this->table->findActive($value))
    {
      throw new sfValidatorError('invalid', $this);
    }

    return $value;
  }
}

We removed the database code and instead inject the table object into the constructor. The responsibility for fetching an active user by its name was outsourced to the table.

An even faster solution is to only count the matching user objects in the database instead of querying and hydrating them. But that’s not in the scope of this article.

So, mummy, is our test faster already? Is it?

Replace Dependencies During Testing

No, kid. We are still using the UserTable when testing the validator – of course, because we need it. So what can we do?

Now that the validator only depends on the UserTable, and not on some mystical database query magic, we can replace the UserTable – which is tested somewhere else and assumed to be working – with a fake implementation. This is usually called stubbing (because you are replacing it with a non-functional stub). With Lime 2, you can do it like this:

$t = new LimeTest();

// @Test: clean() returns the cleaned value if the user is found

  $table = $t->stub('UserTable');
  $table->findActive('bob')->returns(new User());
  $table->replay();
  $validator = new sfValidatorUsername($table);

  $t->is($validator->clean('bob'), 'bob');

The stub acts as if it was the real UserTable object, but in reality it has no internal logic at all. So compared to the real table, the stub is very fast.

More documentation about Lime 2 and its stubbing/mocking capabilities can currently be found on the Lime 2 GitHub repository.

A word of caution shall be spoken. You should only replace services (classes that process some data and return a result) with stubs, not entities (classes that simply contain data). Otherwise changing your domain model (the entities) will soon become a nightmare.

Testing With Databases

Hurray! The validator test is so fast, I can execute it 10 times in a row and it’s still fun. One more time! Nice.

But wait – we can’t decouple everything from the database, can we? Of course, we can’t. Code that is responsible for collaborating with the database, like the above UserTable, needs to access the database. In order for that test to work, the database has to be bootstrapped and filled with data. Because tests should run in isolation from each other, the database further needs to be reset before every single test.

Now a common mistake that severely affects testing performance can often be seen in symfony projects. Many developers use a test database on their development DBMS, like a MySQL server. This database is filled with the content of fixtures.yml, which usually contains all fixture data commonly used to test the application in the browser. And for good reasons this is very slow:

• Most DBMS store data on the file system. Hard disk access is an expensive operation.
• Filling the database with all the test data takes a lot of time
• Parsing YAML files is slow

So ideally we don’t use the database and don’t use any test data. Obviously, that’s not possible.

In-Memory Databases

What is possible is to use an in-memory database. While CPU access on the hard disk usually takes around 4 170 000 ns (nano seconds) for 7200 RPM drives, memory access only takes around 14 ns! Thus, using an in-memory database is a very cheap way to increase your testing performance immensely. Unfortunately not all database vendors offer in-memory alternatives for their file-based DBMS (such as MySQL). In such cases I use SQLite in-memory databases, because SQLite supports most of the SQL92 standard, which is generally sufficient for testing purposes.

If you use symfony with Doctrine, you can place the following code snippet into your bootstrap/unit.php file which initializes the SQLite in-memory database:

// initialize Doctrine
$cacheFile = sprintf('sf_autoload_unit_doctrine_%s.data', md5(__FILE__));
$autoload = sfSimpleAutoload::getInstance(sys_get_temp_dir().'/'.$cacheFile);
$autoload->addDirectory(ROOT_DIR.'/lib/model');
$autoload->addDirectory(ROOT_DIR.'/lib/form');
$autoload->addDirectory(ROOT_DIR.'/lib/filter');
$autoload->register();

$database = new sfDoctrineDatabase(array(
  'name' => 'doctrine',
  'dsn' => 'sqlite::memory:'
));

// load all missing model files
Doctrine::loadModels(ROOT_DIR.'/lib/model');

/**
 * Reloads the database.
 */
function reload()
{
  // close the connection to the in-memory database to recreate the database
  Doctrine_Manager::getInstance()->getCurrentConnection()->close();

  // create the database tables from the loaded models
  Doctrine::createTablesFromModels();

  // clear the Doctrine cache
  foreach (Doctrine::getLoadedModels() as $model)
  {
    Doctrine::getTable($model)->clear();
  }
}

Make sure the constant ROOT_DIR is defined and points to the root of the tested project (your real project or the fixture project).

You might wonder why the $cacheFile is required. This parameter allows us to run multiple tests in parallel while still leveraging autoloading performance by using a cache.

The real interesting piece of code is the reload() function. It allows you to recreate the database on demand. Whenever you write a test that requires a fresh database, call reload() and you are good to go.

Fixture Management

As described above, it is important to keep an eye on the test data that is loaded into your database. The more data you load, the more time it takes. Loading the whole fixtures.yml is a recipe for slow (not only because it contains a lot of data, but also because the YAML file must be parsed).

A much more efficient solution is to programmatively create and load test data on-the-fly. Only create what you need, and nothing more. Below you can find a sample test for our above method UserTable::findActive():

$t = new LimeTest();

// @Test: findActive() returns an active user by username

  reload();
  $user = new User();
  $user->username = 'bob';
  $user->active = true;
  $user->save();
  $table = Doctrine::getTable('User');
  $t->is($table->findActive('bob'), $user);

This test is really fast now. The database is created in-memory, exactly one single User object is inserted and that’s it. The downside is that creating all the fixture data inline becomes a little messy, especially if you have to fill a lot of properties only because they are defined as NOT NULL in the database.

Creation Methods

To work around this issue, I prefer the Creation Method pattern by Gerard Meszaros[1]:

We should use a Creation Method whenever consructing a Fresh Fixture requires significant complexity and we value Tests as Documentation.

The pattern is very simple. Encapsulate the code required to create an object within a utility function that can be reused across your project. My rule of thumb is to write creation methods for all tested Doctrine records and initialize all NOT NULL fields and relations with default values so that the object can be saved without further modification. Because this leads to a lot of code duplication, I also use a base function createObject().

function createUser(array $properties = array())
{
  return createObject('User', $properties, array(
    // NOT NULL properties
    'username' => 'francis',
    ...
    // NOT NULL relations
    'Group' => createGroup(),
    ...
  );
}

function createObject($class, array $properties, array $defaultProperties)
{
  $properties = array_merge($defaultProperties, $properties);

  $object = new $class();
  foreach ($properties as $property => $value)
  {
    $object->set($property, $value);
  }

  return $object;
}

Now you can call createUser() everytime you need to create and save a new User object. Optionally, you can inject property values into the constructor.

$t = new LimeTest();

// @Test: findActive() returns an active user by username

  reload();
  $user = createUser(array(
    'username' => 'bob',
    'active' => true,
  ));
  $user->save();
  $table = Doctrine::getTable('User');
  $t->is($table->findActive('bob'), $user);

/**
 * Saves all objects passed as arguments.
 * @param Doctrine_Record $object1
 * @param Doctrine_Record ...
 */
function save()
{
  foreach (func_get_args() as $object)
  {
    $object->save();
  }
}

/**
 * Creates a collection containing the passed objects.
 * @param Doctrine_Record $object1
 * @param Doctrine_Record ...
 */
function collection()
{
  if (func_num_args() == 0)
  {
    throw new LogicException('You must pass at least one object');
  }

  $objects = func_get_args();
  $collection = new Doctrine_Collection(get_class($objects[0]));
  foreach ($objects as $object)
  {
    $collection->add($object);
  }

  return $collection;
}

$user1 = createUser();
$user2 = createUser();
$user3 = createUser();
save($user1, $user2, $user3);

$coll = collection($user1, $user3);
// etc.

Pulling All Levers

Now that we have optimized our test code to the highest degree, there is one last thing we can do: Increase the hardware power of the test computers and optimize the test suite to utilize its power.

Because most CPUs nowadays feature multiple cores, you should design your test suite for parallel processing. Make sure that no two tests are using the same resources (another benefit of the in-memory databases) and use a testing framework of your choice that supports multiprocessing.

Lime 2, for example, supports multiprocessing by adding the --processes option:

$ php lime --processes=16

While most of my CPU cores are pretty bored when running the test suite in one process, using multiple processes sparks a sudden increase in activity. Not only that, I could record speed increases of over 300% (15 minutes in one process, 4.5 minutes in 16 processes).

Conclusion

As I have tried to portray in this article, writing tests alone is not enough to improve your development. If tests are slow or prevent change, your developers won’t run and use them. Fortunately there are several ways to make changes easier and to increase test speed.

To summarize:

1. Test single features in unit tests. System tests should only be used to verify whether the classes collaborate correctly within different processes.
2. Decouple your classes. This allows introduction of changes without having to adapt multiple tests.
3. Only classes that really need to should deal with remote services. Replace these classes with stubs in all other tests.
4. Choose the fastest version of a remote service available. When you test database classes, use in-memory databases.
5. Only create databases during testing when you really need them
6. Only load data into the database that you really need. Do so programmatively without taking the overhead of parsing XML or YAML files.
7. Make use of multiprocessing, if supported by your testing framework.

How is your testing experience? Are you satisfied with the performance of your tests?

References

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

Related posts:

1. Why Not To Want 100% Code Coverage Although most modern literature agrees that testing is essential for...

© 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.

No related posts.

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. Why Not To Want 100% Code Coverage Although most modern literature agrees that testing is essential for...
3. Writing Efficient Tests Unit testing can be a blessing and curse at the...

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. Writing Efficient Tests Unit testing can be a blessing and curse at the...
2. Why Not To Want 100% Code Coverage Although most modern literature agrees that testing is essential for...

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. Writing Efficient Tests Unit testing can be a blessing and curse at the...
2. Why Not To Want 100% Code Coverage Although most modern literature agrees that testing is essential for...

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!

No related posts.

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?

No related posts.

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?

No related posts.

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?

No related posts.