This article shows an example of framework decoupling. You’ll find a more elaborate discussion in my latest book, Recipes for Decoupling.

Why would it be nice to decouple your user model from the framework’s security user or authentication model?

Reason 1: Hexagonal architecture

I like to use hexagonal architecture in my applications, which means among other things that the entities from my domain model stay behind a port. They are never exposed to, for instance, a controller, or a template. Whenever I want to show anything to the user, I create a dedicated view model for it.

This is just a quick post sharing something I was able to figure out after doing some research.

The situation: our application throws exceptions by means of “talking back to the user”. As developer we don’t want to be notified about all these exceptions. They aren’t as important as any other exception that should be considered “critical”. Still, we do want to find these exceptions in the logs, because they can sometimes provide valuable feedback about the usability of the system.

About 2 years ago I created a package that combines the power of two famous Symfony components: the Form component and the Console component. In short: this package allows you to interactively fill in a form by typing in the answers at the CLI. When I started working on it, this seemed like a pretty far-fetched idea. However, it made a lot of sense to me in terms of a ports & adapters architecture that I was looking for back then (and still always am, by the way). We could (and often should) write the code in our application layer in such a way that it doesn’t make a big difference whether we call applications services from a web controller or from a CLI “controller”.

Event sourcing with Broadway

At the Dutch PHP Conference I attended a workshop by Beau Simensen and Willem-Jan Zijderveld. They showed us some examples of how to work with Broadway, a framework for event sourcing, with full Symfony integration, created by the smart people at Qandidate.

During my two weeks of funemployment, before starting my new job at Ibuildings, I decided to recreate one of my previous projects using Broadway. As it turns out, it’s a great framework that’s quite easy to use and is very powerful at the same time. Even though it’s not a stable package (as in, it’s still in the 0.x version range), I think it’s safe to depend on it.

Bundles, not extensible

A (Symfony) bundle usually contains just some service definition files as well as some configuration options which allow the user of that bundle to configure its behavior (e.g. provide server credentials, etc.). Bundle maintainers usually end up combining lots of these options in one bundle, because they all belong to the same general concept. For example, the NelmioSecurityBundle contains several features which are all related to security, but are code-wise completely unrelated. This means that this one package could have easily been split into several packages. Please note that I’m not making fun of this bundle, nor criticizing it, I’m just taking it as a nice example here. Besides, I’ve created many bundles like this myself.

An ever recurring pattern in my life is this one:

1. I stumble upon some interesting piece of code, an intriguing book chapter, a fascinating concept, etc.
2. Slowly, over the next couple of weeks, my brain realises that, yes, this is some very interesting stuff.
3. Then I want to become all productive about it - writing things on my blog, speaking about it in public, maybe even writing a book about it.

This time it was domain-driven design (DDD), command-query responsibility segregation (CQRS) and in particular its architectural and technical aspects. While playing with existing libraries I soon recognized the huge benefits of applying hexagonal architecture and some of the tactical DDD patterns to a (Symfony) codebase.

Thanks! Let me explain myself

First of all: thanks everybody for reading the previous parts of this series. Many people posted some interesting comments. I realized quickly that I had to explain myself a bit: why am I writing all of this? Why would you ever want to decouple controllers from the (Symfony2) framework? You probably don’t need to bother anyway, because

The chances of you needing to move controllers to other frameworks is next to none. — Rafael Dohms

In the previous part of this series we decreased coupling of a Symfony controller to the Symfony2 framework by removing its dependency on the standard Controller class from the FrameworkBundle.

Now we take a look at annotations. They were initially introduced for rapid development (no need to create/modify some configuration file, just solve the issues inline!):

namespace Matthias\ClientBundle\Controller;

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Method;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;

/**
 * @Route("/client")
 */
class ClientController
{
    /**
     * @Route('/{id}')
     * @Method("GET")
     * @ParamConverter(name="client")
     * @Template
     */
    public function detailsAction(Client $client)
    {
        return array(
            'client' => $client
        );
    }
}

When you use these annotations, the details action will be executed when the URL matches /client/{id}. A param converter will be used to fetch a Client entity from the database based on the id parameter which is extracted from the URL by the router. The return value of the action is an array. These are used as template variables for rendering the Resources/views/Client/Details.html.twig template.

Part I: Don’t use the standard controller

The general belief is that controllers are the most tightly coupled classes in every application. Most of the time based on the request data, they fetch and/or store persistent data from/in some place, then turn the data into HTML, which serves as the response to the client who initially made the request.

So controllers are “all over the place”, they glue parts of the application together which normally lie very far from each other. This would make them highly coupled: they depend on many different things, like the Doctrine entity manager, the Twig templating engine, the base controller from the FrameworkBundle, etc.

It appears that I didn’t make myself clear while writing about entity managers and manager registries yesterday. People were quick to reply that instead you should inject entity repositories. However, I wasn’t talking about entity repositories here. I was talking about classes that get an EntityManager injected because they want to call persist() or flush(). The point of my previous post was that in those cases you should inject the manager registry, because you don’t know beforehand which entity manager manages the entities you are trying to persist. By injecting a manager registry you also make your code useful in contexts where another Doctrine persistence library is used.

Please also read my next article about injecting entity managers.

Or: how to make your persistence-related code more reusable

You probably know that you should trim your controllers as much as possible. This usually means extracting some classes from the semi-procedural code inside your controller class. You create services for the extracted classes and inject the necessary dependencies into them. You can no longer use the convenient $this->getDoctrine()->getManager(). Instead you inject the doctrine.orm.default_entity_manager service into every service that needs the EntityManager to persist data in your relational database: