This post was partially triggered by the release of the new Zend Framework 2 Form RFC because I think that a lot of duplicated effort is going on there. I completely understand that Zend Framework 2 needs a form layer that is tailored to the components delivered by the framework. The purpose of this post is to demonstrate that the Symfony2 Form component is perfectly suited for this requirement. Symfony2-specific functionality can be unplugged, leaving only the raw core dealing with form processing and abstraction. As a replacement, functionality can be developed for supporting Zend’s or any other framework’s components.

Creating a generic form library that elegantly solves all the various use-cases that can be found in web form construction and processing has been a challenging, long-lasting and complex task that is not over yet. Cooperating and continuing development from this common base on seems like a big chance to make form handling in PHP more powerful – and easier – than it has ever been before.

The post starts with crediting all the other great frameworks and form libraries that influenced this work. Then I would like to introduce you to the key aspects of the Form component before continuing to describe its high and low-level architecture.

Influences

The Form component has been influenced by many other frameworks written in different languages, including symfony 1, Zend Framework 1, Django, Ruby on Rails,  Struts and JSF. Apart from that, it shows many similarities with Formlets, WUI and iData, form libraries written for the functional languages Links, Curry and Clean.

Key Aspects

The key aspects of the Form component are:

• Abstraction
• Extensibility
• Compositionality
• Separation of Concerns
• Model Binding
• Dynamic Behavior

Abstraction

Abstraction describes the ability to take any part of a form – or even the whole form – and put it into a reusable data structure. Consider a form with three drop down boxes to select the day, month and year  for a date. First, you need code that generates the HTML with all of its option tags. Second, you need code that converts from the application’s data type (for example, PHP’s DateTime) to the view’s representation (which option is selected?) and back. If you add another date selector to a form in your application, you need to duplicate and adapt all of that code.

Abstraction solves this problem by providing suitable data structures for describing and reusing your code.

Extensibility

Extensibility refers to two main concepts related to abstraction:

1. Specialization is a logical consequence of abstraction. When it is possible to abstract functionality into generic data structures, it should also be possible to extend these data structures into custom, specialized ones. A simple example is to extend the above date selector to also show selectors for the time. Without the ability to specialize the existing date selector, a large part of its functionality needs to be rewritten.
2. Mixins are an orthogonal concept to specialization. Assume that you want to change all existing fields to include an asterisk (“*”) in their label if they require user input. Doing so by using specialization is a tedious task, because it requires you to extend every existing field with a custom one, implementing the same new functionality. Mixins, on the other hand, allow to attach functionality to existing objects without the need to specialize them. As a bonus, the added functionality is inherited by all descendants in the inheritance tree.

Extensibility also refers to more indepth extensiblity by means of events, which will be discussed later.

Compositionality

If we examine the last examples a bit more, we discover that there is no relevant difference between fields (complex ones, such as in the example before, and primitive ones, such as a text input tag) and forms. Both fields and forms

1. accept default values from the model (an array, a date, a string…)
2. convert the value to a representation suitable for use in the view
3. render HTML
4. accept values submitted by the user
5. convert these values back to the model’s format
6. optionally perform validation

We can implement fields and forms using the same fundamental data structure. By adding compositionality – the ability to nest this data structure into itself (see the Composite pattern) – we can create forms of arbitrary complexity. Instead of forms and fields, we will talk about forms and their children from now on. Once that a form has children, it also needs to

7. forward (map) its default value (an array or an object) to its children
8. extract (also map) the submitted value of each child back into the original array/object

Separation of Concerns

We can group the tasks in the above list to several, distinct responsibilities:

• Data Transformation
• HTML Generation (the View)
• Validation
• Data Mapping

These responsibilities should be implemented by decoupled components with clearly defined interfaces. As a result, any of these components can be replaced by a custom implementation, such as a custom view or validator layer.

Model Binding

In many cases, forms directly relate to structures that have already been described otherwise in the domain model. Consider a form to submit the profile information of a user. Consider further that these profiles are stored in a table in your database. The table has information about the properties stored in the profile, about the types of these properties, their default values and their constraints. Ideally, your application also features a class Profile that is mapped to this database table with an ORM such as Doctrine 2. This class may exhibit more information about the profile, for example, that a profile can be related to any number of subjects that the user is intersted in. These subjects must be selected from a list that is stored in a configuration file.

Usually, the information listed here (we will call it metadata) must be replicated in the form layer. The user must know what properties he can edit, the form must display appropriate HTML widgets that correspond to the types of the properties, the user must know which fields may not be left empty and so on. This is why creating forms usually sucks.

Model Binding tries to change this situation. It refers to two ideas:

1. reuse existing metadata during form construction in order to reduce duplication of code and configuration
2. read default values from a domain object (an instance of Profile) and write the submitted values back into the object

Dynamic Behavior

Last but not least, forms should support dynamic behavior. Gone are the times were you could statically code your forms on the server and avoid security issues by making sure that every submitted form corresponds to the predefined structure. Nowadays, client-side JavaScripts change the DOM of forms in order to enhance usability.

Just consider a tabular form. Each column contains fields of the same type, each row represents an object on the server. Little buttons allow to delete or to add new rows. Whenever the form is submitted, the server must adjust the form’s model to match the deleted and added rows in order to successfully process and validate it.

Dynamic behavior shouldn’t be restricted to tabular forms though. Suitable mechanisms in the architecture should allow reactions to any kind of change on the client. Unfortunately, this problem isn’t addressed by many libraries.

High-Level Architecture

Let me outline the high-level architecture of forms in Symfony2. A their core lies the Form component. This component provides the basic architecture for defining and processing forms and uses Symfony2′s Event Dispatcher internally for processing events. On top of the component lie a series of pluggable extensions:

• The Core extension provides all field definitions (called form types) implemented by the framework.
• The Validation extension integrates the Symfony2 Validator to implement form validation.
• The DI extension adds support for Symfony2′s Dependency Injection component.
• The CSRF extension adds CSRF protection to forms.
• The Doctrine 2 extension (shipped with the Doctrine bridge) adds a Doctrine-specific drop down field and provides components that let forms know about Doctrine metadata.

The topmost layer contains the components responsible for rendering HTML. Symfony2 provides two such components: One for rendering forms in Twig (shipped with the Twig bridge) and another for rendering it with it’s PHP Templating component (contained in FrameworkBundle).

The most interesting fact for other frameworks here is that every component apart from Form is replaceable. A custom extension could be written to support Zend Validator, another could be written for Smarty and so on. You could even go so far to remove the Core extension and write an own set of basic fields. Even the underlying Event Dispatcher can be replaced by writing a custom one that implements Symfony2′s EventDispatcherInterface. You win a lot of flexibility compared to little loss.

Low-Level Architecture

This section continues to discuss the internal architecture of the Form component. As mentioned before, a form and all of its children can be represented by the same data structure that implements the Composite pattern. In the Form component, this data structure is described by the FormInterface. The main implementation of FormInterface is the class Form, which uses three components to do its work:

• A data mapper distributes the data of a form to its children and merges the data of the children back into the form’s data. The default data mapper allows forms to load their values both from arrays and objects or object graphs. After the form’s submission, the new values are written back into the original data structure.
• Two chains of data transformers convert values between different representations. Data transformers guarantee to output values of predefined types to your application, regardless of the format used to display and modify the values in the view.
• An event dispatcher allows you to execute custom code at predefined points during form processing. It enables you to adapt the form’s structure to match the submitted data, or to filter, modify or validate the submitted data and so on.

These components are passed to the constructor of Form and cannot be changed after construction in order to avoid corruption of the form’s state. Because the constructor signature is quite long and complicated, a form builder simplifies the construction of Form instances.

The form view is the view representation of a form. This means that you never deal with Form instances in the template, but with FormView instances. These store additional, view-specific inforrmation, such as HTML names, IDs and so on.

The following UML diagram illustrates the architecture.

As can be seen in the previous diagram, a form has three different representations throughout its lifecycle:

• During construction, it is represented by a hierarchy of FormBuilder objects.
• In the controller, it is represented by a hierarchy of Form objects.
• In the view, it is represented by a hierarchy of FormView objects.

Because the configuration of form builders and form views is repetitive, Symfony2 implements form types that group such configuration. Form types support dynamic inheritance, meaning that they can extend different base types, depending on the options passed at the the construction of a form. The following diagram illustrates all types that come bundled with the Symfony2 extensions (green types are provided by the Core extension, yellow types by additional ones):

Mixins, as described before, are supported in Symfony2 by so-called type extensions. These type extensions can be attached to existing form types and add additional behavior. Symfony2, for example, contains type extensions for adding CSRF protection to the “form” type (and consequently all of its subtypes).

A form factory retrieves the type hierarchy from the loaded extensions and uses them to configure new FormBuilder and FormView objects. It is important to know that this configuration itself can be controlled by user-provided options. For example, the “choice” type supports an option “choices” in which all selectable values need to be passed.

The last important concept in the Form component is that of type guessers. Type guessers try to derive the type and options of a field in the form based on the metadata available for the domain object backing the form (if any). For example, if a property of the object is configured to be a one-to-many-relation to a model Tag, type guessers automatically configure this property to be represented by a multiple-choice field with all Tag instances loaded by default. This concept is similar to ModelForms in Django. The main difference is that your application can use various type guessers to use metadata from different sources instead of just relying on the ORM definition. Symfony2, for example, ships with three guessers: One for reading Doctrine2 metadata, one for Propel metadata and a last one for reading metadata of the Symfony2 validator.

The concepts described in the last paragraphs are summarized again in the following UML diagram.

Summary

As I have tried to show in this post, the Symfony2 Form component features a carefully engineered architecture that takes many important aspects of modern form processing into account.

It solves the problem of abstraction, specialization and mixins by providing a dynamic inheritance tree of form types and form type extensions. It solves the compositionality problem by distributing the work and responsibility of processing a form among all of its elements. It offers a clear separation of concerns in order to easily replace different layers of the component. It achieves model binding by involving the existing domain model metadata into the construction of a form and by reading from and writing into domain objects directly. And it supports dynamic behavior by offering events at predefined points during its processing that can be handled by custom listeners, such as for validation or filtering.

Interested? Explore the code. Play with it. And help us to integrate it into your favourite framework.

No related posts.

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

No related posts.