As a programmer, it’s important that you understand the flow of the system you’re working with—not just for the sake of being able to alter something when needed, but also because it’ll give you a confidence boost while doing so.

Today, we’ll pick OpenCart and dissect it to understand the basics of the dispatching process. We’ll start with what the dispatching process is all about, and as we move on we’ll explore code slices from the different sections of the framework.

I’ll pick up the latest version of OpenCart for this article, but more or less the flow is similar in the earlier versions.

Dispatching in a Nutshell

In any web-based application, the dispatching process is used to find the mapping between the incoming request URL and the corresponding module in the framework. Of course, the implementation varies from framework to framework, but the underlying concept remains the same. So here are some of the responsibilities of the dispatcher:

• Grab the appropriate parameters from the Request Object.
• Find the corresponding module and action to be called.
• If the corresponding module and action are found, the dispatching process ends.
• If no module is found for the given Request, the default action is set and the dispatching process ends.

Let’s try to understand this using a simple example in OpenCart. To create a new user from the front-end, one needs to register with the site using http://www.youropencartstore.com/index.php?route=account/register. Let’s summarize the steps taken by OpenCart to render the requested page.

• First, it checks the presence of the “route” query string variable, otherwise it’ll set the “common/home” as a default “route” of the page.
• In our case, it’s present, so it’ll set up the required variables and trigger the dispatch process.
• At the beginning of the dispatch process, it’ll run some of the “preAction” actions which are used to perform common tasks. We’ll discuss the “preAction” stuff in the later part of this article.
• Finally, it’ll check whether there’s a controller file available for the current “route” variable, and if there’s one it’ll be called to fetch the response.
• If there’s no controller file available for the requested “route” variable, it’ll execute the “error/not_found” action, which shows the “page not found” message to the user.

So that’s a top-level view of how OpenCart goes through the requested URL and returns the response. In the next section, we’ll go deeper and see how exactly it does so.

Go Through the Flow

Go ahead and open the index.php file in the document root of OpenCart. There is a lot happening in that file, but don’t get overwhelmed, as most of it is just the setup of objects used throughout the framework.

Let’s straight away pull in the snippet of our interest from that file.

// Front Controller
$controller = new Front($registry);

// Maintenance Mode
$controller->addPreAction(new Action('common/maintenance'));

// SEO URL's
$controller->addPreAction(new Action('common/seo_url'));

As with most other frameworks, OpenCart also relies on the front-controller pattern so that there’s a common entry point for all the requests in the application.

First, we’re creating an instance of the front controller and assigning it to the $controller variable. Immediately next to that, we’re calling the addPreAction method to add a couple of actions.

Now, that brings another topic on the table: what is a “preAction”? In simple terms, a preAction is an action which will be executed before the requested action on any page. For example, when the user clicks on any page, you want to check whether the site is in maintenance mode or not before the actual response is returned. In that case, you could use a preAction so that user will be redirected to the maintenance page if it’s on.

Also, we’re adding common/seo_url as a preAction as well, since in the case of an SEO-enabled site we want to fetch the corresponding route variables before actual dispatching starts.

Let’s move on to the next important snippet.

// Router
if (isset($request->get['route'])) {
    $action = new Action($request->get['route']);
} else {
    $action = new Action('common/home');
}

It checks the presence of the “route” query string variable, and if it’s there we’ll create an instance of the Action class by passing the current “route” value as a constructor argument. If it’s not present, we’ll do the same with the home page route URI—common/home.

With our $action variable set with the proper value, let’s move on to the next snippet.

// Dispatch
$controller->dispatch($action, new Action('error/not_found'));

Finally, we’re calling the dispatch method of the front controller class. Go ahead and open system/engine/front.php and find the following snippet.

public function dispatch($action, $error) {
    $this->error = $error;

    foreach ($this->pre_action as $pre_action) {
        $result = $this->execute($pre_action);

        if ($result) {
            $action = $result;

            break;
        }
    }

    while ($action) {
        $action = $this->execute($action);
    }
}

This is the method where all the magic happens! First, it executes all the “preActions” as discussed earlier. Further, in the while loop it’ll try to execute our current $action, passed as an argument of the execute method.

Let’s follow the definition of the execute method in the same file.

private function execute($action) {
	$result = $action->execute($this->registry);

	if (is_object($result)) {
		$action = $result;
	} elseif ($result === false) {
		$action = $this->error;

    	$this->error = '';
	} else {
		$action = false;
	}

	return $action;
}

On the very first line, the execute method of the Action class is called. Don’t confuse it with the execute method of the Front controller class. Open the file system/engine/action.php and here it is.

public function execute($registry) {
	// Stop any magical methods being called
	if (substr($this->method, 0, 2) == '__') {
		return false;
	}

	if (is_file($this->file)) {
		include_once($this->file);

		$class = $this->class;

		$controller = new $class($registry);

		if (is_callable(array($controller, $this->method))) {
			return call_user_func(array($controller, $this->method), $this->args);
		} else {
			return false;
		}
	} else {
		return false;
	}
}

The important thing to note here is that the Action class already sets up the required variables in the constructor itself when the action object is instantiated in index.php. It sets up the file, class and method properties, which will be used in the execute method. To keep things less complicated, we’ll only discuss the execute method, although I would recommend that you go through the constructor of the Action class.

Back to our execute method of the Action class, it checks the presence of the file ($this->file) associated with the current route. If everything is fine, it includes that file and calls the corresponding method ($this->method) of that controller class using the call_user_func function and returns the response.

If the associated file is not available, it’ll return false. Now, let’s get back to the snippet from the execute method of the Front controller class. Be patient, we’re almost there!

...
$result = $action->execute($this->registry);

if (is_object($result)) {
	$action = $result;
} elseif ($result === false) {
	$action = $this->error;

	$this->error = '';
} else {
	$action = false;
}

return $action;
...

Once the execute method of the Action class completes the process, it returns the result and it’s assigned to the $result variable. Now, there are three different possibilities with the value stored in $result. Let’s examine each one.

If everything went fine, we’ll have HTML output in the $result variable, so the $action variable is set to false and the process ends. It’s the last else case.

Recall that we returned false if the corresponding controller file was not found in the execute method of the Action class. In that case, the $action variable will be set to $this->error (error/not_found Action), and “page not found” will be shown to the user.

And finally, if we find that the $result is an object itself, we’ll set it to the $action variable. Yes, that’s weird: why on earth would the controller method return another Action object, when it’s supposed to return the HTML output for requested page? But that’s just one of the ways the controller redirects users to some other URL.

Let’s quickly open the catalog/controller/common/maintenance.php file and see it in action. In the index method, it returns the Action object if certain conditions are true.

…
if (($route != 'payment' && $route != 'api') && !$this->user->isLogged()) {
    return new Action('common/maintenance/info');
}
…

So, as you can see, it returns the Action object to redirect the user to the common/maintenance/info URL. Of course, there’s a code in the dispatch method of the front controller class to handle this behavior. Recall the snippet from that method—I promise it’s the last snippet of this tutorial.

...
while ($action) {
	$action = $this->execute($action);
}
...

So it’s a while loop, and it runs until it finds the $action variable set to false! More specifically, it’ll end the loop when we have useful output for our user.

So that’s the end of the journey. I hope that it was not as complicated as it seemed to be at first glance.

Conclusion

Today, we’ve gone through an important aspect of the OpenCart framework—the dispatching process. We understood the basics of dispatching and went through the complete flow to understand how it works.

If you're looking for additional OpenCart tools, utilities, extensions, and so on that you can leverage in your own projects or for your own education, don't forget to see what we have available in the marketplace.

For any queries, don’t hesitate to leave your comments. Also, Twitter is another option for contacting me, and I respond quickly.