Create your own framework... on top of the Symfony2 Components (part 9)

Fabien Potencier

January 19, 2012

This article is part of a series of articles that explains how to create a framework with the Symfony2 Components: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12.

Our framework is still missing a major characteristic of any good framework: extensibility. Being extensible means that the developer should be able to easily hook into the framework life cycle to modify the way the request is handled.

What kind of hooks are we talking about? Authentication or caching for instance. To be flexible, hooks must be plug-and-play; the ones you "register" for an application are different from the next one depending on your specific needs. Many software have a similar concept like Drupal or Wordpress. In some languages, there is even a standard like WSGI in Python or Rack in Ruby.

As there is no standard for PHP, we are going to use a well-known design pattern, the Observer, to allow any kind of behaviors to be attached to our framework; the Symfony2 EventDispatcher Component implements a lightweight version of this pattern:

{
    "require": {
        "symfony/class-loader": "2.1.*",
        "symfony/http-foundation": "2.1.*",
        "symfony/routing": "2.1.*",
        "symfony/http-kernel": "2.1.*",
        "symfony/event-dispatcher": "2.1.*"
    },
    "autoload": {
        "psr-0": { "Simplex": "src/", "Calendar": "src/" }
    }
}
 

How does it work? The dispatcher, the central object of the event dispatcher system, notifies listeners of an event dispatched to it. Put another way: your code dispatches an event to the dispatcher, the dispatcher notifies all registered listeners for the event, and each listener do whatever it wants with the event.

As an example, let's create a listener that transparently adds the Google Analytics code to all responses.

To make it work, the framework must dispatch an event just before returning the Response instance:

<?php
 
// example.com/src/Simplex/Framework.php
 
namespace Simplex;
 
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Matcher\UrlMatcherInterface;
use Symfony\Component\Routing\Exception\ResourceNotFoundException;
use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface;
use Symfony\Component\EventDispatcher\EventDispatcher;
 
class Framework
{
    protected $matcher;
    protected $resolver;
    protected $dispatcher;
 
    public function __construct(EventDispatcher $dispatcher, UrlMatcherInterface $matcher, ControllerResolverInterface $resolver)
    {
        $this->matcher = $matcher;
        $this->resolver = $resolver;
        $this->dispatcher = $dispatcher;
    }
 
    public function handle(Request $request)
    {
        try {
            $request->attributes->add($this->matcher->match($request->getPathInfo()));
 
            $controller = $this->resolver->getController($request);
            $arguments = $this->resolver->getArguments($request, $controller);
 
            $response = call_user_func_array($controller, $arguments);
        } catch (ResourceNotFoundException $e) {
            $response = new Response('Not Found', 404);
        } catch (\Exception $e) {
            $response = new Response('An error occurred', 500);
        }
 
        // dispatch a response event
        $this->dispatcher->dispatch('response', new ResponseEvent($response, $request));
 
        return $response;
    }
}
 

Each time the framework handles a Request, a ResponseEvent event is now dispatched:

<?php
 
// example.com/src/Simplex/ResponseEvent.php
 
namespace Simplex;
 
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\EventDispatcher\Event;
 
class ResponseEvent extends Event
{
    private $request;
    private $response;
 
    public function __construct(Response $response, Request $request)
    {
        $this->response = $response;
        $this->request = $request;
    }
 
    public function getResponse()
    {
        return $this->response;
    }
 
    public function getRequest()
    {
        return $this->request;
    }
}
 

The last step is the creation of the dispatcher in the front controller and the registration of a listener for the response event:

<?php
 
// example.com/web/front.php
 
require_once __DIR__.'/../vendor/.composer/autoload.php';
 
// ...
 
use Symfony\Component\EventDispatcher\EventDispatcher;
 
$dispatcher = new EventDispatcher();
$dispatcher->addListener('response', function (Simplex\ResponseEvent $event) {
    $response = $event->getResponse();
 
    if ($response->isRedirection()
        || ($response->headers->has('Content-Type') && false === strpos($response->headers->get('Content-Type'), 'html'))
        || 'html' !== $event->getRequest()->getRequestFormat()
    ) {
        return;
    }
 
    $response->setContent($response->getContent().'GA CODE');
});
 
$framework = new Simplex\Framework($dispatcher, $matcher, $resolver);
$response = $framework->handle($request);
 
$response->send();
 

The listener is just a proof of concept and you should add the Google Analytics code just before the body tag.

As you can see, addListener() associates a valid PHP callback to a named event (response); the event name must be the same as the one used in the dispatch() call.

In the listener, we add the Google Analytics code only if the response is not a redirection, if the requested format is HTML, and if the response content type is HTML (these conditions demonstrate the ease of manipulating the Request and Response data from your code).

So far so good, but let's add another listener on the same event. Let's say that I want to set the Content-Length of the Response if it is not already set:

$dispatcher->addListener('response', function (Simplex\ResponseEvent $event) {
    $response = $event->getResponse();
    $headers = $response->headers;
 
    if (!$headers->has('Content-Length') && !$headers->has('Transfer-Encoding')) {
        $headers->set('Content-Length', strlen($response->getContent()));
    }
});
 

Depending on whether you have added this piece of code before the previous listener registration or after it, you will have the wrong or the right value for the Content-Length header. Sometimes, the order of the listeners matter but by default, all listeners are registered with the same priority, 0. To tell the dispatcher to run a listener early, change the priority to a positive number; negative numbers can be used for low priority listeners. Here, we want the Content-Length listener to be executed last, so change the priority to -255:

$dispatcher->addListener('response', function (Simplex\ResponseEvent $event) {
    $response = $event->getResponse();
    $headers = $response->headers;
 
    if (!$headers->has('Content-Length') && !$headers->has('Transfer-Encoding')) {
        $headers->set('Content-Length', strlen($response->getContent()));
    }
}, -255);
 

When creating your framework, think about priorities (reserve some numbers for internal listeners for instance) and document them thoroughly.

Let's refactor the code a bit by moving the Google listener to its own class:

<?php
 
// example.com/src/Simplex/GoogleListener.php
 
namespace Simplex;
 
class GoogleListener
{
    public function onResponse(ResponseEvent $event)
    {
        $response = $event->getResponse();
 
        if ($response->isRedirection()
            || ($response->headers->has('Content-Type') && false === strpos($response->headers->get('Content-Type'), 'html'))
            || 'html' !== $event->getRequest()->getRequestFormat()
        ) {
            return;
        }
 
        $response->setContent($response->getContent().'GA CODE');
    }
}
 

And do the same with the other listener:

<?php
 
// example.com/src/Simplex/ContentLengthListener.php
 
namespace Simplex;
 
class ContentLengthListener
{
    public function onResponse(ResponseEvent $event)
    {
        $response = $event->getResponse();
        $headers = $response->headers;
 
        if (!$headers->has('Content-Length') && !$headers->has('Transfer-Encoding')) {
            $headers->set('Content-Length', strlen($response->getContent()));
        }
    }
}
 

Our front controller should now look like the following:

$dispatcher = new EventDispatcher();
$dispatcher->addListener('response', array(new Simplex\ContentLengthListener(), 'onResponse'), -255);
$dispatcher->addListener('response', array(new Simplex\GoogleListener(), 'onResponse'));
 

Even if the code is now nicely wrapped in classes, there is still a slight issue: the knowledge of the priorities is "hardcoded" in the front controller, instead of being in the listeners themselves. For each application, you have to remember to set the appropriate priorities. Moreover, the listener method names are also exposed here, which means that refactoring our listeners would mean changing all the applications that rely on those listeners. Of course, there is a solution: use subscribers instead of listeners:

$dispatcher = new EventDispatcher();
$dispatcher->addSubscriber(new Simplex\ContentLengthListener());
$dispatcher->addSubscriber(new Simplex\GoogleListener());
 

A subscriber knowns about all the events it is interested in and pass this information to the dispatcher via the getSubscribedEvents() method. Have a look at the new version of the GoogleListener:

<?php
 
// example.com/src/Simplex/GoogleListener.php
 
namespace Simplex;
 
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
class GoogleListener implements EventSubscriberInterface
{
    // ...
 
    public static function getSubscribedEvents()
    {
        return array('response' => 'onResponse');
    }
}
 

And here is the new version of ContentLengthListener:

<?php
 
// example.com/src/Simplex/ContentLengthListener.php
 
namespace Simplex;
 
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
class ContentLengthListener implements EventSubscriberInterface
{
    // ...
 
    public static function getSubscribedEvents()
    {
        return array('response' => array('onResponse', -255));
    }
}
 

A single subscriber can host as many listeners as you want on as many events as needed.

To make your framework truly flexible, don't hesitate to add more events; and to make it more awesome out of the box, add more listeners. Again, this series is not about creating a generic framework, but one that is tailored to your needs. Stop whenever you see fit, and further evolve the code from there.

Discussion

gravatar Kevin Bond  — January 19, 2012 14:46   #1
Awesome chapter, really solidified my understanding of the event dispatcher component as well as the observer pattern. I have read the "Internals" chapter a few times but something in this really made it click for me. Nice job!
gravatar Alessandro Desantis  — January 19, 2012 16:55   #2
Nice. There's only one problem: the declaration of Simplex\Framework::handle() is not compatible with that of Symfony\Component\HttpKernel\HttpKernelInterface::handle(), so running PHPUnit generates an error.

You should either add the missing parameters to the handle() method or don't implement HttpKernelInterface yet.
gravatar Fabien Potencier  — January 19, 2012 17:26   #3
@Alessandro: oops, I've removed the interface... indeed, we will add it in a later part.
gravatar Maik L├╝deke  — January 20, 2012 08:02   #4
@Fabien: It would be great, if you could link the past parts of your great tutorial in the footer. For someone, who pops in later on this site, it would be easier to follow your track.
gravatar Jean-Louis GUINALDO  — January 20, 2012 15:02   #5
@Fabien : Sorry if I missed something about namespaces but I am in front the following issue:

I put my listener files in this folder path
/src/Simplex/Listeners/

I updated the namespace of the listener's class : namespace Simplex\Listeners;

I updated the dispatcher's lines in front.php
$dispatcher->addSubscriber(new Simplex\Listeners\ContentLengthListener());
$dispatcher->addSubscriber(new Simplex\Listeners\GoogleListener());

The namespaces do not seem to be resolved by the dispatcher. (Something goes wrong when EventDispatcher's doDispatch() is called)

Thanx.
gravatar Fabien Potencier  — January 21, 2012 08:59   #6
@Maik: I will do something similar soon.
gravatar Jean-Louis GUINALDO  — January 22, 2012 23:57   #7
Ok,sorry. Just had to fix a NS scope issue.