Tom Butler's programming blog

Using a Dependency Injection Container to simplify Routing in an MVC framework

Updated 19/11/2018: Examples now use Dice 4.0

Introduction

Today, I'm going to show how combining several different OOP techniques and design patterns can create a very powerful yet simple application entry point for an MVC framework. From the ground up, I'll walk you through building a Convention-Over-Configuration router for a MVC framework. By the end you'll have something smaller, far more robust and powerful than is available in any of the popular frameworks!

I'll be using my own Dependency Injection Container: Dice (available here) to create a smart router/dispatcher for a simple MVC Framework. Any Dependency Injection Container can be used for this job, but Dice takes away 99% of the configuration so makes everything far simpler.

Why use a Dependency Injection Container for this task?

In MVC In PHP part 2: MVC On the web. I discussed the problem of routing that the web architecture presents. I chose not to get too technical in that article as I wanted everything to be self-contained. However, this is a more advanced version of that and while it addresses the same concepts and the same issues, this is far more complex and designed to be used in the real-world. It's not just for demonstration.

As such, and sticking with the theme of Separation of Concerns that MVC strives for, Using a different tool for the creation of objects within the system creates a far more robust and flexible application. I won't go into the merits of dependency injection here as there are lot of articles around which discuss that. However, I hope the code examples here will speak for themselves even if you're not familiar with Dependency Injection.

Routing in MVC web frameworks

To recap, the biggest issue faced when deploying MVC on the web is:

How does the centralised entry point (front controller) know which Model, View and Controller to initiate?

By delegating that job to a Dependency Injection Container it's easy to avoid the trivial binding logic of "This controller needs this model, this view needs this model".

Firstly, how the router will interact with the rest of the system must be defined. Basic functionality dictates that it will take a route such as '/users/list' and return the names (or instances) of the model, view and controller that it's going to use.

Here is a skeleton router API with the basic logic:

class Router {
    public function 
find($route) {
        
//Convert $route into a Route object as defined below
        
return new Route('...''...''...');
    }
}

class 
Route {
    private 
$view;
    private 
$controller;
    private 
$model;

    public function 
__construct(View $view$model null$controller null) {
        
$this->view $view;
        
$this->controller $controller;
    }

    public function 
getView() {
        return 
$this->view;
    }

    public function 
getController() {
        return 
$this->controller;
    }

    public function 
getModel() {
        return 
$this->model;
    }
}

To follow the basic rules of encapsulation, the three properties are private. This essentially makes them read-only and once a route has been created it is immutable. This is good because it stops unknown external code changing the route during the application's execution.

However, this can be simplified slightly. If there is a Model in use, the View and/or Controller will ask for it in its constructor:

class MyView implements View {
    public function 
__construct(MyModel $model) {

    }
}

class 
MyController {
    public function 
__construct(MyModel $model) {

    }
}

In MVC the View and Controller encapsulate the model. The top level of the application that knows about the route doesn't need to know of the Model's existence, and as such it should be removed from the Route object entirely:

class Router {
    public function 
find($route) {
        
//Convert $route into a Route object as defined below
        
return new Route('...''...');
    }
}

class 
Route {
    private 
$view;
    private 
$controller;

    public function 
__construct(View $view$controller null) {
        
$this->view $view;
        
$this->controller $controller;
    }

    public function 
getView() {
        return 
$this->view;
    }

    public function 
getController() {
        return 
$this->controller;
    }
}

Later on a dispatcher will be required to call the correct controller action and this will need to know which controller it's dealing with. And the top level of the application needs to know which view to render. Nothing apart from the View and Controller need the model so we can minimise the data needed in the Route object.

A convention based router

Back to the router itself, let's say the first two parts of the URL to generate the route. For example /user/edit/12 becomes "\User\Edit\Controller" and "\User\Edit\View" by default. The default action is then called by the dispatcher with a parameter of "12". A Convention-over-configuration approach can be used so that this can be overridden where needed.

This could be defined manually in the router:

class Router {
    
/*
    * @param string
    * @description: Convert $route into a Route object as defined below
    * @return \Route
    */
    
public function find($route) {
        
//Split the route on / so the first two parts can be extracted
        
$routeParts explode('/'$route);


        
//A name based on the first two parts such as "\User\Edit" or "\User\List"
        
$name '\\' array_shift($route) . '\\' array_shift($route);

        
$viewName $name '\\View';
        
//Does the class e.g. "\User\List\View" exist?
        
if (class_exists($viewName))  {
            
$view = new $viewName;
        }
        else {
            
//Exit, this should display an error or throw an exepction but for simpliticy in this case, routes that
            //do not have a view will be disabled
            
return false;
        }


        
//E.g. "\User\Edit\Controller"
        
$controllerName $name '\\Controller';
        if (
class_exists($controllerName)) {
            
$controller = new $controllerName;
        }
        else {
            
$controller null;
        }

        
//Finally, return the matched route
        
return new Route($view$controller);
    }
}

The obvious problem here is that it won't work. The logic is sound but the controller and view can't be initialised in this way because they'll never get passed the model. This is where Dice, the Dependency Injection Container, comes in. It can automatically resolve dependencies:

Rather than having Dice construct the Model, View and Controller, Dice will instead, dynamically construct the Route object with the correct parameters.

This means that the Router is never aware of any dependencies that controllers, models or views may have and resolving those dependencies is all down to Dice. This ensures a proper separation of concerns that abide by the single responsibility principle. The router is concerned with routing and the Dependency Injection Container is concerned only with managing dependencies.

class Router {
    private 
$dice;

    public function 
__construct(\Dice\Dice $dice) {
        
//Dice, the dependency injection container
        
$this->dice $dice;
    }

    public function 
find($route) {
        
//Convert $route into a Route object as defined below


        //A name based on the first two parts such as "\User\Edit" or "\User\List"
        
$name '\\' array_shift($route) . '\\' array_shift($route);


        
$viewName $name '\\View';

        if (!
class_exists($viewName)) return false;

        
$controllerName $name '\\Controller';

        
//Auto-generate a rule for a route if it's not already been generated
        
if ($this->dice->getRule('$autoRoute_' $className) == $this->dice->getRule('*')) {
            
$rule = [];

            
//Dice will be creating a Route object and pass it a specific view and controller
            
$rule['instanceOf'] = 'Route';

            
//The first parameter will be a view
            
$rule['constructParams'] = [
                [\
Dice\Dice::INSTANCE => $view]
            ];

            
//Only pass the controller to the route object if the controller exists
            
$rule['constructParams'][] = (class_exists($controllerName)) ? [\Dice\Dice::INSTANCE => $controllerName] : null;


            
//The model (or ViewModel) will need to be shared between the controller and view
            
$modelName $className '\\ViewModel';

            
//The model doesn't need to exist, in its purest form, an MVC triad could just be a view
            //This tells Dice that the same instance of the model should be passed to both the view and the controller, if it exists
            
if (class_exists($modelName))  $rule['shareInstances'] = [$modelName];


            
//Add the rule to the DIC
            
$this->dice $this->dice->addRule('$autoRoute_' $className$rule);
        }


        
//Have Dice construct the Route object with the correct controller and view set.
        //Dice will automatically pass the model into the View nad Controller if they ask for it in their constructors
        
return $this->dice->create('$autoRoute_' $className);
    }

}

This works by having Dice create the Route object with a specific View and Controller that are using a convention based name

Dice will create an instance of the Route object passing it the required View and Controller. If the controller or view ask for the model in their constructor, they will be automatically passed that too.

The best part about this is that thanks to Dice, the controller (e.g. \User\Edit\Controller) can ask for additional dependencies and they will be automatically resolved by Dice. Amending the controller to ask for a session object and a request object will just work without any further configuration! And not need to alter or reconfigure the router in any way.

namespace User\Edit;
class 
Controller {
    public function 
__construct(UserModel $userSession $sessionRequest $request) {

    }
}

Nice! This is now a very simple Convention-based router. That is, it will always use the naming convention to work out the route. However, it's not very flexible. It ties you to a very specific naming convention for your classes. It must initiate $route1$route2View and $route1$route2 controller. This is far from ideal as it's impossible to reuse a class. For instance You may wish to use a generic "\List\View" rather than a specific "\User\List\View"

A configuration based router

Sometimes you want to be able to manually define which controller and view to initialise. This is important for reusability, if you have to use the convention approach you must needlessly use inheritance if you want to reuse a controller or view on two different routes

By defining the routes using Dice's Named Instances feature, it's possible to have complete control over an instance:

$rule = [
    
//It will be an instance of the Route object
    
'instanceOf' => 'Route',

    
//Define the View and Controller which will be used.
    //These don't rely on a naming convention
    
'constructParams' => [
        
//Here a generic ListView is used with a user-specific UserListController
        
[\Dice\Dice::INSTANCE => 'ListView'],
        [\
Dice\Dice::INSTANCE => 'UserListController']
    ]
];


//And add a rule containing the route
$dice $dice->addRule('$route_user/edit'$rule);

This means that when Dice is told to create a component called "$route_user/edit" it creates the an instance of the Route class by passing it an instance of ListView and an instance of UserListController in its constructor.

And now change the router to allow Dice to piece together all the relevant components:

class Router {
    private 
$dice;

    public function 
__construct(\Dice\Dice $dice) {
        
$this->dice $dice;
    }

    public function 
find($route) {
        
//Convert $route into a Route object as defined below
        
$routeParts explode('/'$route);

        
$name $routeParts[0] . '/' $routeparts[1];

        return 
$this->dice->create('$route_' $name);
    }
}

And Dice has done all the work! Of course, the fallback to the default view has been lost. That should be added back in:

$rule = [
    
'instanceOf' => 'Route',
    
'constructParams' => [
        [\
Dice\Dice::INSTANCE => 'DefaultView'];
    ];
];

//Add a named instance for the fallback view:
$dice $dice->addRule('$route_default'$rule);

And then in the router:

class Router {
    private 
$dice;

    public function 
__construct(\Dice\Dice $dice) {
        
$this->dice $dice;
    }

    public function 
find($route) {
        
//Convert $route into a Route object as defined below
        
$routeParts explode('/'$route);

        
$name '$route_' $routeParts[0] . '/' $routeparts[1];

        
//If there is no special rule set up for this $name, revert to the default
        
if ($this->dice->getRule($name) === $this->dice->getRule('*')) {
            return 
$this->dice->create('$route_default');
        }
        else return 
$this->dice->create($name);
    }
}

This will now fall back to whatever has been defined as the default route. The problem with this approach is that every single route still needs to be defined manually. This is a Configuration based (or static) router where each route is manually defined. The downside is that every single possible route in the system must be defined as a rule. This can very quickly grow to a very long list in large application and become a pain in larger applications. Doing something as simple as adding a page means reconfiguring the router.

Combining the two to create a Convention-Over-Configuration router

By combining the two, it's easy to create a Convention-over-configuration router that has all the flexibility of the Configuration-based and along with the convenience of the Convention-based router! And what's more, by using Dice you don't need to worry about locating any dependencies the View or Controller may have.

class Router {
    private 
$dice;

    public function 
__construct(\Dice\Dice $dice) {
        
$this->dice $dice;
    }

    public function 
find($route) {
        
//Convert $route into a Route object as defined below
        
$routeParts explode('/'$route);

        
$configName '$route_' $routeParts[0] . '/' $routeparts[1];

        
//Check if there is a manual configuration for this route
        
if ($this->dice->getRule($configName) === $this->dice->getRule('*')) {

            
$className '\\' array_shift($route) . '\\' array_shift($route);

            
$viewName $className '\\View';

            
//If the view doesn't exist, the convention rule can't continue
            
if (!class_exists($viewName)) return false;

            
$controllerName $className '\\Controller';

            
//Auto-generate a rule for a route if it's not already been generated
            
if ($this->dice->getRule('$autoRoute_' $className) == $this->dice->getRule('*')) {
                
$rule = new \Dice\Rule;

                
//Dice will be creating a Route object and pass it a specific view and controller
                
$rule->instanceOf 'Route';

                
//The first parameter will be a view
                
$rule->['constructParams'] = [
                    [\
Dice\Dice::INSTANCE => $viewName]
                ];

                
//Only pass the controller to the route object if the controller exists
                
$rule['constructParams'][] = (class_exists($controllerName)) ?
                [\
Dice\Dice::INSTANCE => $controllerName] : null;

                
//The model (or ViewModel) will need to be shared between the controller and view
                
$modelName $className '\\ViewModel';

                
//The model doesn't need to exist, in its purest form, an MVC triad could just be a view
                
if (class_exists($modelName))  $rule['shareInstances'] = [$modelName];

                
//Add the rule to the DIC
                
$this->dice $this->dice->addRule('$autoRoute_' $className$rule);
            }

            
//Create the route object
            
return $this->dice->create('$autoRoute_' $className);

        }
        
//There is a manual route defined, use that
        
else return $this->dice->create($configName);

    }
}

This is excellent! Here is a very simple yet very powerful Convention-Over-Configuration router. It's simple and follows the Single Responsibility Principle as well as keeping the idea of separation of concerns by not being concerned with the creation of the objects and delegating it to Dice.

Room for improvement

Of course, there's always room for improvement. How about making the router entirely extensible? Should the router itself really be concerned with looking at class names or the implementation of Dice? It can be simplified and made extensible:

namespace Router;

interface 
Rule {
    public function 
find(array $route);
}

class 
Router {
    private 
$rules = array();

    public function 
addRule(Rule $rule) {
        
$this->rules[] = $rule;
    }

    public function 
getRoute(array $route) {
        foreach (
$this->rules as $rule) {
            if (
$found $rule->find($route)) return $found;
        }

        throw new 
Exception('No matching route found');
    }
}

Here is a very basic router that requires some third party rules are provided for it to work. The first thing you'll notice is that getRoute() now takes an array. This is because assuming that all routes are strings broken up by a '/' is a bad thing and will limit the scope of the router. Instead, the part of the code that actually accepts the route as a string can format it into an array for the router. The router doesn't care where the route comes from or whether the URL was broken on a '/' or a '\' or even a ':' or "@". In fact it may not have been a URL at all.

This router works on rules. You pass it rules and it processes them in order. At the moment the router will never match a single route. To add back the functionality that existed previously it needs to be moved to rules. Firstly the Configuration-based rule:

namespace Router\Rule;
class 
Configuration implements \Router\Rule {
    private 
$dice;

    public function 
__construct(\Dice\Dice $dice) {
        
$this->dice $dice;
    }

    public function 
find(array $route) {
        
$name '$route_' $route[0] . '/' $route[1];

        
//If there is no special rule set up for this $name, revert to the default
        
if ($this->dice->getRule($name) == $this->dice->getRule('*')) {
            return 
false;
        }
        else return 
$this->dice->create($name);
    }
}

and one for the Convention based approach:

namespace Router\Rule;

class 
Convention implements \Router\Rule {
    private 
$dice;

    public function 
__construct(\Dice\Dice $dice) {
        
$this->dice $dice;
    }

    public function 
find(array $route) {
        
//The name of the class
        
$className '\\' array_shift($route) . '\\' array_shift($route);

        
$viewName $className '\\View';

        
//If the view doesn't exist, the convention rule can't continue
        
if (!class_exists($viewName)) return false;

        
$controllerName $className '\\Controller';

        
//Auto-generate a rule for a route if it's not already been generated
        
if ($this->dice->getRule('$autoRoute_' $className) == $this->dice->getRule('*')) {
            
$rule = [];

            
//Dice will be creating a Route object and pass it a specific view and controller
            
$rule['instanceOf'] = 'Route';

            
//The first parameter will be a view
            
$rule->['constructParams'] = [
                 [\
Dice\Dice::INSTANCE => $viewName];
            ];

            
//Only pass the controller to the route object if the controller exists
            
$rule->['constructParams'][] = (class_exists($controllerName)) ? [\Dice\Dice::INSTANCE => $controllerName] : null;

            
//The model (or ViewModel) will need to be shared between the controller and view
            
$modelName $className '\\ViewModel';

            
//The model doesn't need to exist, in its purest form, an MVC triad could just be a view
            
if (class_exists($modelName))  $rule['shareInstances'] = [$modelName];


            
//Add the rule to the DIC
            
$this->dice $this->dice->addRule('$autoRoute_' $className$rule);
        }

        
//Create the route object
        
return $this->dice->create('$autoRoute_' $className);
    }
}

Finally, in case neither of those rules match a route, return the default rule:

namespace Router\Rule;
class Default implements \
Router\Rule {
    private 
$dice;

    public function 
__construct(\Dice\Dice $dice) {
        
$this->dice $dice;
    }

    public function 
find(array $route) {
        return 
$this->dice->create('$route_default');
    }
}

Why break them up? It allows flexibility in the application. The router can be a Convention based router or a Configuration based router or a Convention-over-configuration based router simply by adding the relevant rules to it. And the rules don't have to use Dice. Other rules could be used such as filename based routing. This frees up the router from any true dependencies making it more portable and easier to reuse. The initialisation code would look like this:

$dice = new \Dice\Dice;


$router = new \Router\Router;
$router->addRule(new \Router\Rule\Configuration($dice));
$router->addRule(new \Router\Rule\Convention($dice));
$router->addRule(new \Router\Rule\Default($dice));

$route $router->getRoute(explode('/'$url));

As you can see, without much effort at all, a very powerful extensible router has been created with very little code.

Conclusion

You now have a very powerful router which is fully extensible and creates all your models, views and controllers! By using Dice you take a lot of the boilerplate code out of the framework entry point and simplify everything.

In the next article, I'll show you how to use the generated route with a dispatcher and you'll have a fully functional entry point for your own MVC framework!