sammela.com » opencart

The OpenCart Controller base class

Sam Mela — Sun, 15 Nov 2009 05:00:30 +0000

All controllers in OpenCart share a common ancestor, the Controller class, located in the DIR_APPLICATION/system/engine/controller.php file. Note that DIR_APPLICATION is the path to your application directory, and is defined in the OpenCart config.php file.

In object oriented terms, the Controller class is called a base class. It contains common methods and data definitions that all its descendant classes will find useful and can use.

Data definitions for the Controller class follow:

$id;	$id is used to identify the controller. Typically it is set by the controller. For example, the ControllerCommonColumnLeft controller sets its $id to “column_left”. Controller id’s are the means by which a parent controller relates child controller output to a template. The name used in the template must match the controller name.
$template	$template is the file that defines the output of the controller. It is basically a PHP/HTML file that is populated with variables from the controller $data array.
$children	$children is an array of the controllers that a top level controller is composed of. It is very important to understand that these are not children in the object oriented inheritance sense of the term. They are just pieces of the top level controller, the way tires and the engine are pieces of a car. For example, ControllerCommonHome contains the following childres: ControllerCommonHeader ControllerCommonFooter ControllerCommonLeft ControllerCommonRight
$data	All information that will be used to populate the $template is stored in the $data array. In the controller fetch method, the PHP extract function is used to create local variables from the $data array and make them available to populate the $template.
$output	The HTML output of the $template is ultimately stored in the $output variable, where it is available to be echoed to the client browser.

In addition to the above class data, the baseController class makes a few methods available.

__get	__get is a magic method that gets a class scope variable from the Registry class. See the online PHP documentation on magic methods for more detail. Also see The Open Cart “load” Class Variable and Magic Methods.
__set	__set is a magic method that puts a class scope variable into the Registry class. See the online PHP documentation on magic methods for more detail. Also see The Open Cart “load” Class Variable and Magic Methods.
forward	The forward method creates a new instance of the Router class.
redirect	The redirect method immediately redirects to a new location.
fetch	See How OpenCart Renders Pages.
render	See How OpenCart Renders Pages.

OpenCart Top Level Controller Architecture

Sam Mela — Sat, 14 Nov 2009 22:54:52 +0000

An OpenCart top level controller is responsible for orchestrating the complete construction of an OpenCart page.

As an example, the ControllerCheckoutCart controller class is responsible for coordinating the model data and the template view necessary to create a checkout cart page for the client.

Another example is the ControllerCommonHome controller class, which is responsible for the main store view that customers see when they first visit.

Common Base Class

All controllers in OpenCart share a common ancestor, the Controller class, located in the DIR_APPLICATION/system/engine/controller.php file. This class is described in The OpenCart Controller Base Class

The Index Method

How OpenCart Renders Pages

Sam Mela — Sat, 14 Nov 2009 06:01:07 +0000

The OpenCart Controller class contains a render method that is used to produce HTML pages output by all OpenCart classes that inherit from Controller class.

Here is how it works.

Each time a page is rendered, it is done with one top level controller. The top level controller may contain zero or more child controllers and it contains a template. Rendering proceed in the following order:

Each child controller is rendered
The top level controller is rendered, based on its own data and the output of the child controllers

That’s it. The rest is details which are described in the remainder of this article.

How the Template is Rendered

As stated previously, the top level controller render method produces output using a template. To accomplish this, it passes the template to the fetch method, which does the actual work.

The fetch Method

As stated previously, the top level controller render method produces output using a template. To accomplish this, it passes the template to the fetch method, which does the actual work.

The fetch method is not very long, but it does some clever things and it takes advantage of some very powerful features of PHP. Here is the operative code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// Create local variables from the controller data array
extract($this->data);

// Initialize PHP output buffering
ob_start();

// Load the template file, which is automatically
// populated with the local variables created above
require($file);

// Get the output of the template file
// Which has been echoed to the PHP output buffer
$content = ob_get_contents();

// Empty the PHP output buffer
ob_end_clean();

Basically, all information necessary to populate the template must be stored in the controller’s $data array. The native PHP extract function pulls the information out the the $data array and populates the local symbol table with it, so it is available to the template file.

Now here is the trick. The template file echoes its output; but since PHP buffering is turned on, the echoed HTML is not output to the client browser, but rather to the PHP output buffer. The fetch method stores the PHP output buffer contents in the $content variable and then returns it to the calling function. Cool beans.

But there’s more. Not only is this method used for the top level controller, but each of the controllers contained by the top level controller (the children) is evaluated the same way; and the children can contain their own children, theoretically without limit, although in practical terms it is unlikely they will go more than two or three levels deep.

The OpenCart Router Class

Sam Mela — Fri, 13 Nov 2009 22:04:26 +0000

The OpenCart Router class takes a route string and converts it to an internal representation of a class and a method, typically for invoking a controller.

The Router class is specialized to the directory structure of OpenCart and the naming conventions for OpenCart controller files and class; therefore, before discussing the Router class in detail, it is important to understand the directory structure and naming conventions that OpenCart uses for controllers, controller directories, and controller files.

Controller Directory Structure

In OpenCart, catalog controllers are all located under DIR_APPLICATION/catalog/controller, where DIR_APPLICATION is the path to your application directory, and is defined in the OpenCart config.php file.

More specifically, files containing definitions of controller classes are contained in the following directories:

DIR_APPLICATION/catalog/controller/account
DIR_APPLICATION/catalog/controller/checkout
DIR_APPLICATION/catalog/controller/common
DIR_APPLICATION/catalog/controller/error
DIR_APPLICATION/catalog/controller/feed
DIR_APPLICATION/catalog/controller/information
DIR_APPLICATION/catalog/controller/module
DIR_APPLICATION/catalog/controller/payment
DIR_APPLICATION/catalog/controller/product

As an example, the following files are contained in DIR_APPLICATION/catalog/controller/account:

DIR_APPLICATION/catalog/controller/checkout/address.php
DIR_APPLICATION/catalog/controller/checkout/cart.php
DIR_APPLICATION/catalog/controller/checkout/confirm.php
DIR_APPLICATION/catalog/controller/checkout/guest.php
DIR_APPLICATION/catalog/controller/checkout/payment.php
DIR_APPLICATION/catalog/controller/checkout/shipping.php
DIR_APPLICATION/catalog/controller/checkout/success.php

Controller Class Naming Conventions

We see from the previous section how the controllers directories are laid out, but how are the controller classes named?

It is very straightforward. Each controller class name is built from the last two directory names and the file name of its path name.

For example, the file DIR_APPLICATION/catalog/controller/checkout/address.php contains the class ControllerCheckoutAddress.

Similarly, the file DIR_APPLICATION/catalog/controller/account/address.php contains the class ControllerAccountAddress.

How the Router class works

Now that we understand the naming conventions for controller classes and files, let’s look at how the Router class works.

The Router constructor accepts a required string parameter, route, and an optional array parameter, args.

The constructor creates three class scope variables, $class, $method, $args; which are made available through the following class methods:

getClass
getMethod
getArgs

Here is what the Router does. If takes the route string

1	$router = new Router("account/address/somemethod");

The classvariable will be set to “account/address” and the method variable will be set to “somemethod”.

It may seem odd that the class maintains the slash (”/”), but that’s how it works, and later when the class name is actually used to instantiate an object, the slashes are removed first.

This may seem like much ado about nothing, but that’s how it works. Later, after the $route variable is created in the Registry, it can be fished out and used instantiate the correct controller; in this case, the ControllerAccountAddress class located in the DIR_APPLICATION/catalog/controller/account/address.php file.

The OpenCart Response Class

Sam Mela — Fri, 13 Nov 2009 06:19:23 +0000

The OpenCart Response class has a simple job. It outputs a page of HTML to a client browser.

But it does a few other things related to that function as well, including the following:

It compresses output data in accordance with how the OpenCart installation is configured and the client browser capabilitiles.
It maintains an array of header data and sends the header data, prior to outputting the page HTML

Here is a complete list of the public methods of the Response class:

addHeader($key, $value)

Adds a header to an internal keyed list of headers. When the output is constructed the headers are all transmitted first.

removeHeader($key)

Since the internal header list is keyed, a particular header can be removed using this method.

redirect($url)

Immediately redirects to $url. For debugging and maintenance purposes, it is much better to redirect using this method, rather than sprinkling redirects throughout code.

setOutput($output, $level = 0)

Sets the HTML to be output by the Response class. If the optional $level parameter is not false (i.e. non-zero and not set to FALSE), the Response class will attempt to compress the output sent to the browser.

output()

Send headers if not already sent. Compress the output if $level is true. Echo the output.

Try It

It is simple to test the Responseclass, as shown below:

1
2
3

$rsp = new response();
$rsp->setOutput("This is a test of the Response class with compression enabled",1);
$rsp->output();

Note On Compression

I had not done any PHP output compression before I looked at the OpenCart Response class. The compress method accomplishes this by first determining the ability of the browser to uncompress.

The value of $_SERVER['HTTP_ACCEPT_ENCODING'] will be set to ‘gzip’ if the browser is capable of accepting gzip encoding.

The value of $_SERVER['HTTP_ACCEPT_ENCODING'] will be set to ‘x-gzip’ if the browser is capable of accepting x-gzip encoding.

If the browser is not capable of accepting either type of compression, the compress method simply returns uncompressed data.

If the browser is capable of accepting either type of compression, the compress method then checks to see if the server has the proper library installed to do the compression and further it checks that no headers have already been set. If both these conditions are true, the compress method compresses the output data and returns it.

The Open Cart “load” Class Variable and Magic Methods

Sam Mela — Fri, 13 Nov 2009 04:54:52 +0000

All controllers in the OpenCart ecommerce package inherit from the Controller class.

The load variable in those controllers was a bit of a mystery to me, because I could not figure out where it was assigned. Then I realized it was being accessed through the Registry class using a PHP language construct called a “magic method”, which is documented in the online PHP Manual.

In particular the __get magic method is used. This method is quite interesting. It is called whenever a class method attempts to retrieve an undefined attribute.

In a nutshell, since the load variable is not defined in the Controller class or any of its child classes, the __get method will be called.

Let’s see exactly how this works. Below is the __get method as it is defined in the Controller class:

1
2
3

public function __get($key) {
return Registry::get($key);
}

Here is the code that attempts to access the load variable:

1	$this->load->model('catalog/category');

When PHP encounters the above code, to get the $this->load variable, it calls __get with the string “load”, and the implementation of __get looks it up in the Registry class, where it has been previously stored.

Here’s the final piece of the puzzle. You may be wondering how the value of the Registry variable “load” is set.

Simple — at initialization, in the index.php file, a loader object is created and stored in the registry, as follows:

1 2	$loader = new Loader(); Registry::set('load', $loader);