As a module developer, more often than not you’ll need to create a custom schema in your day-to-day OpenCart custom module development. It’s already provisioned, as with the other frameworks, in the form of different hooks in the module architecture of OpenCart.
Before we go ahead and explore the aforementioned hooks, let’s explore the concept of extensions in OpenCart. Looking from the top, it’s an extension in OpenCart that allows you to enrich the core functionality of OpenCart. By installing it, you add features to the front-end store, be it a simple image gallery or some fancy-looking drag-and-drop functionality.
Further, the extensions, depending on the functionality they provide, are categorized into logical groups. As a quick example, the payment extension adds new payment methods in the front-end checkout, while it’s an anti-fraud extension that allows you to detect spam activities in your store. Head over to the back-end and have a look at the list under the Extensions menu that shows the different kinds of extensions supported in OpenCart.
You’ll be surprised to know that a module is also just an another kind of extension in OpenCart. Each extension is built around the common workflow of how things should work in the OpenCart ecosystem. And hooks allow you to perform certain actions based on specific events, whether it’s running an install hook during the module activation or cleaning up the garbage during uninstallation.
It’ll be those install and uninstall hooks that will be discussed throughout the course of this article. Although they’ll be discussed in the context of modules, I don’t see anything that stops you applying the same method to other kinds of extensions as well, so feel free to explore those files on your own.
It’s the latest version of OpenCart that provides the snippets spread over this tutorial. As of writing this, it’s the 2.1.0.2 stable version.
Walk Through the Install Hook
In this section, we’ll explore what exactly the install hook is used for. Go ahead and open admin/controller/extension/module.php in your favorite text editor, and find the install method. It should look something like this:
<?php
...
public function install() {
$this->load->language('extension/module');
$this->document->setTitle($this->language->get('heading_title'));
$this->load->model('extension/extension');
$this->load->model('extension/module');
if ($this->validate()) {
$this->model_extension_extension->install('module', $this->request->get['extension']);
$this->load->model('user/user_group');
$this->model_user_user_group->addPermission($this->user->getGroupId(), 'access', 'module/' . $this->request->get['extension']);
$this->model_user_user_group->addPermission($this->user->getGroupId(), 'modify', 'module/' . $this->request->get['extension']);
// Call install method if it exists
$this->load->controller('module/' . $this->request->get['extension'] . '/install');
$this->session->data['success'] = $this->language->get('text_success');
$this->response->redirect($this->url->link('extension/module', 'token=' . $this->session->data['token'], 'SSL'));
}
$this->getList();
}
...
?>
It’s the generic install hook for the module that will be called whenever you try to install any module from the back-end. Let’s go through the important parts of this method.
First, it loads the model files that are required for the subsequent activities. The $this->model_extension_extension->install method call makes sure that an entry is added to the database for this particular module.
Following that, there’s some ACL stuff, and it’s accomplished by calling the addPermission method. It makes sure that the current user, admin, should be able to access the module-specific settings and alter them.
Finally, it calls the install method of the module that’s being installed. Don’t get confused with the install method we’re already in—it’ll call the module specific install method if it exists.
For example, if you’re trying to install the Log In with PayPal module, it’ll call an install method defined in the file admin/controller/module/pp_login.php as shown below.
<?php
...
public function install() {
$this->load->model('extension/event');
$this->model_extension_event->addEvent('pp_login', 'post.customer.logout', 'module/pp_login/logout');
}
...
?>
Since the introduction of OpenCart 2.x, there are a few exciting features included, and event-observer is one of them. It allows you to add module-specific events, and other modules could set up observers for this event so that they could run some arbitrary code when that particular event is fired. And that’s exactly what's demonstrated in the above install method, which adds the post.customer.logout custom event!
In the case of the Log In with PayPal module, it was pretty simple stuff, but sometimes you’ll need more should you wish to inject a custom schema or something similar. Let’s pull in our install method from the PayPal Express Checkout payment extension. Go ahead and open admin/controller/payment/pp_express.php.
<?php
...
public function install() {
$this->load->model('payment/pp_express');
$this->model_payment_pp_express->install();
}
...
?>
First, it loads the corresponding model file, and using that it calls the install method of the model. As a rule of thumb, whenever you want to manipulate a schema, you should implement that code in the model's install method, rather than directly putting it in the controller's install method.
Now, let’s quickly pull in the install method defined in the model file admin/model/payment/pp_express.php.
<?php
...
public function install() {
$this->db->query("
CREATE TABLE IF NOT EXISTS `" . DB_PREFIX . "paypal_order` (
`paypal_order_id` int(11) NOT NULL AUTO_INCREMENT,
`order_id` int(11) NOT NULL,
`date_added` DATETIME NOT NULL,
`date_modified` DATETIME NOT NULL,
`capture_status` ENUM('Complete','NotComplete') DEFAULT NULL,
`currency_code` CHAR(3) NOT NULL,
`authorization_id` VARCHAR(30) NOT NULL,
`total` DECIMAL( 10, 2 ) NOT NULL,
PRIMARY KEY (`paypal_order_id`)
) ENGINE=MyISAM DEFAULT COLLATE=utf8_general_ci;");
$this->db->query("
CREATE TABLE IF NOT EXISTS `" . DB_PREFIX . "paypal_order_transaction` (
`paypal_order_transaction_id` int(11) NOT NULL AUTO_INCREMENT,
`paypal_order_id` int(11) NOT NULL,
`transaction_id` CHAR(20) NOT NULL,
`parent_transaction_id` CHAR(20) NOT NULL,
`date_added` DATETIME NOT NULL,
`note` VARCHAR(255) NOT NULL,
`msgsubid` CHAR(38) NOT NULL,
`receipt_id` CHAR(20) NOT NULL,
`payment_type` ENUM('none','echeck','instant', 'refund', 'void') DEFAULT NULL,
`payment_status` CHAR(20) NOT NULL,
`pending_reason` CHAR(50) NOT NULL,
`transaction_entity` CHAR(50) NOT NULL,
`amount` DECIMAL( 10, 2 ) NOT NULL,
`debug_data` TEXT NOT NULL,
`call_data` TEXT NOT NULL,
PRIMARY KEY (`paypal_order_transaction_id`)
) ENGINE=MyISAM DEFAULT COLLATE=utf8_general_ci;");
}
...
?>
Finally, there's something to cheer about! As you can see, a couple of custom MySQL tables are created using the database API of OpenCart. So, this is the way to apply database-related changes using the install method of the model.
So, that's it as far as the install hook is concerned. I hope it's not as complicated as it seems to be at first glance. Let's put it this way. The process is commenced by triggering an extension-specific install method that in turn calls the install method of the extension being installed if it exists. Finally, the install method of the model is called from the controller's install method in case any database manipulation is needed by that extension.
Walk Through the Uninstall Hook
This section, the counterpart of the previous section, highlights the happenings in the uninstall hook. We'll proceed in the same way as we did for the install method in the previous section, so let's straight away grab the code of the uninstall hook from the file admin/controller/extension/module.php.
<?php
...
public function uninstall() {
$this->load->language('extension/module');
$this->document->setTitle($this->language->get('heading_title'));
$this->load->model('extension/extension');
$this->load->model('extension/module');
if ($this->validate()) {
$this->model_extension_extension->uninstall('module', $this->request->get['extension']);
$this->model_extension_module->deleteModulesByCode($this->request->get['extension']);
$this->load->model('setting/setting');
$this->model_setting_setting->deleteSetting($this->request->get['extension']);
// Call uninstall method if it exists
$this->load->controller('module/' . $this->request->get['extension'] . '/uninstall');
$this->session->data['success'] = $this->language->get('text_success');
$this->response->redirect($this->url->link('extension/module', 'token=' . $this->session->data['token'], 'SSL'));
}
$this->getList();
}
...
?>
Again, it should look a bit familiar as most of it is the boilerplate code. The important snippet to start with is the call to the uninstall method that deletes the entry of the current extension being uninstalled from the extension MySQL table.
Next, it calls deleteModulesByCode, which deletes the modules associated with the extension. It's a special method that's only found in this module kind of extension—you won't find it in the other extensions like payment, shipping, fraud, etc.
The reason is that you could replicate every module to create multiple instances. For example, you could show different banner modules on different pages. On the other hand, it doesn't make any sense to replicate the other kind of extensions. Again as an example, there's only one instance required for the PayPal payment extension in the front-end.
Next, it deletes the configuration variables related to the module by calling the deleteSetting method. Finally, it calls the uninstall method of the module that’s being uninstalled.
Let's open admin/controller/module/pp_login.php to see how the uninstall method looks.
<?php
...
public function uninstall() {
$this->load->model('extension/event');
$this->model_extension_event->deleteEvent('pp_login');
}
...
?>
Pretty simple, huh? It's just undoing the stuff that was injected into the install method of the Log In with PayPal module. Recall that we created a new event post.customer.logout during the installation, so it's obvious that we need to delete it during uninstallation to make sure we don't leave any module-specific garbage.
Also, let's have a quick look at the uninstall method of the PayPal Express Checkout payment extension as we went through the install method of it in the earlier section. Grab the following snippet of admin/controller/payment/pp_express.php.
<?php
...
public function uninstall() {
$this->load->model('payment/pp_express');
$this->model_payment_pp_express->uninstall();
}
...
?>
Fairly expected stuff—it loads the model and calls the uninstall method. That also gives us a strong reason to open the model file admin/model/payment/pp_express.php and explore the uninstall method as well.
<?php
...
public function uninstall() {
$this->db->query("DROP TABLE IF EXISTS `" . DB_PREFIX . "paypal_order_transaction`;");
$this->db->query("DROP TABLE IF EXISTS `" . DB_PREFIX . "paypal_order`;");
}
...
?>
We're just dropping the MySQL tables that were created earlier, as we don't want someone to ask us, "How could you leave this garbage?"
So, that was the story, hopefully nice, of install and uninstall hooks in OpenCart. The next and last section quickly wraps up the concepts learned so far in a simple, yet working, custom module, as that's something nice to have in your kitty post theory session.
Create/Drop a Custom Schema Using Install/Uninstall Hooks
In this section, we'll create an admin module demo that won't do much except to create a new schema during installation and drop it during uninstallation.
First, let's create a language file so that the module is picked up in the back-end. Go ahead and create a file admin/language/english/module/demo.php with the following contents.
<?php // Heading $_['heading_title'] = 'Demo Module';
Next, we need to create a model file that holds the actual and interesting code of our custom module. The model file should be placed at admin/model/module/demo.php. It creates a demo MySQL table in the install method and drops it in the uninstall method.
<?php
class ModelModuleDemo extends Model {
public function install() {
$this->db->query("
CREATE TABLE IF NOT EXISTS `" . DB_PREFIX . "demo` (
`demo_id` int(11) NOT NULL AUTO_INCREMENT,
`name` VARCHAR(100) NOT NULL,
PRIMARY KEY (`demo_id`)
) ENGINE=MyISAM DEFAULT COLLATE=utf8_general_ci;");
}
public function uninstall() {
$this->db->query("DROP TABLE IF EXISTS `" . DB_PREFIX . "demo`;");
}
}
Finally, go ahead and create a controller file admin/controller/module/demo.php with the following contents.
<?php
class ControllerModuleDemo extends Controller {
public function install() {
$this->load->model('module/demo');
$this->model_module_demo->install();
}
public function uninstall() {
$this->load->model('module/demo');
$this->model_module_demo->uninstall();
}
}
It's straightforward, as it should be—it loads the model and calls the corresponding methods depending on the actions being performed.
Go ahead and give it a try. It should be listed as a Demo Module under Extensions > Modules. Install it and you should see the demo MySQL table created in the back-end, and of course don't forget to uninstall it to drop the table.
Conclusion
Today, we've discussed an important aspect of the OpenCart installation process, the install and uninstall hooks. We went through the details of those hooks, and in the later part of the article we built a simple module as a proof of concept.
Of course, queries and comments are always welcome!
No comments:
Post a Comment