The Enhanced Script Notifications in OpenCart 2.2.x.x

Today, we’re going to discuss one of the coolest features of OpenCart—script notifications. Although they've been available since the release of OpenCart 2.x version, they've been enhanced in the recent release of OpenCart 2.2.x.x. Throughout the course of this tutorial, we’ll discuss the concept and demonstrate it by creating a working module.

Introduction

As a developer, you'll often need to alter the flow of the core framework behaviour, whether it’s to add a new feature to the framework or to enhance the existing workflow. In either case, you need to have control over the workflow so that you can hook into the functionality and achieve the desired behavior.

Let’s try to understand it by a simple example. If you’re running a popular online store, chances are that the most popular products of your store will be sold out soon. In this case, it would be nice to get a notification about it and take the proper action accordingly.

So what you could do in the aforementioned example is to look for the method that's called when the order is placed. Next, you can hook into the order creation flow so that you can control when the order is placed. That allows you to execute a random piece of code in the context of the called event. That's where event notifications come into the picture, allowing us run arbitrary code and modify the resulting outcome.

What Are Script Notifications?

As per the official OpenCart documentation:

In 2.2+ we have added a new events system, these are hooks that can be called before and after events such as a controller method call, model method call or templates being loaded. They give the ability to manipulate the input method parameters and returned output.

That's really powerful, as you could literally hook into any method call and change the output returned by that method. However, you should be careful during the implementation of hooks, if you're taking the responsibility of modifying the resulting output of the call. That's because if your implementation returns any value, it will stop any other event actions that are set to be called.

What does it take to implement script notifications? Here are the necessary steps:

Register Your Event

When you're registering your event with OpenCart, you're telling OpenCart that you want to monitor xyz action, and if that happens please execute the foo action in the bar controller file. While doing so, you have two options to choose from—before and after.

If you choose the before option, OpenCart will run the foo action before the action that's being monitored, and in the case of the after option it'll execute foo after the action. In the case of the before option, it's important to note that if the foo method returns anything, OpenCart won't execute the original method code that's being monitored at all.

Later in this article, we'll see how to register an event during custom module implementation.

Implement the Target Action

Next, you'll need to implement the controller and the corresponding action method that's been associated with an event in the first step. That's the place where your custom code should go in. OpenCart sends context-specific arguments to your foo method, so that you could use it if needed.

So that’s just a glimpse of what script notifications are capable of.

Do We Still Need OCMOD?

If you're familiar with either vQmod or OCMOD, chances are that you're going to roll up your sleeves against the event notifications feature. After all, you could achieve everything by the aforementioned goodies that you would have anyway accomplished with event notifications.

For those who are not familiar with either vQmod or OCMOD, listed below are nice introductory articles that explain it.

• The New Modification System in OpenCart 2


• Altering the Core of OpenCart Using vQmod

So, the question is, if you could use either vQmod or OCMOD to alter the core files, why would you use script notifications? It’s because of the fact that there may be multiple OCMOD plugins trying to alter the same code, and that could result in conflict. In the case of events, there’s no chance of conflict as each event is executed in a specific order.

So the conclusion is that if it’s possible to use events, go for that. On the other hand, if you feel that there’s no event available for your use-case, it’s completely fine to go with OCMOD.

Create a Back-End Module

In this section, we're going to build a module that demonstrates how to use event notifications in OpenCart. I assume that you're aware of the basic module development process in OpenCart, as we'll skid through the basics. If you're not aware of it, here's a nice article that you can go through quickly.

Let's understand the use-case before we go ahead and implement it. Assume that you have a store that fetches the catalog information from the third-party API back-end. You've set up a cron that regularly fetches the information and inserts it in the OpenCart database, so that it can be displayed in the front-end. Although you've set up a cron that updates the information at regular intervals, you want to make sure that the information displayed in the front-end must be in real time.

In the front-end, OpenCart calls the getProduct function when it displays the product detail page. So, that's the ideal candidate for you to hook into and update the database if the API information has changed.

So let's start creating the back-end files first.

Go ahead and create the admin/controller/module/demoevent.php file with the following contents.

<?php
// admin/controller/module/demoevent.php
class ControllerModuleDemoevent extends Controller {
  private $error = array();

  public function install() {
    $this->load->model('extension/event');
    $this->model_extension_event->addEvent('event_product_info', 'catalog/model/catalog/product/getProduct/before', 'custom/product/info');
  }
    
  public function uninstall() {
    $this->load->model('extension/event');
    $this->model_extension_event->deleteEvent('event_product_info');
  }
}

As we discussed earlier, the first thing you would like to do is the registration of the event. It's the install hook that we'll use to do it, as it'll be executed when the module is installed.

We've used the addEvent method of the event model under the extension directory, and that method has three arguments.

The first argument, event_product_info, is the name of the event. You could name it anything, but make sure that it's unique.

The second argument is very important, and it points out to the method that you would like to hook into. In our case, we have to choose the getProduct method of the Product Model under the Catalog directory. So the hierarchy is model/catalog/product/getProduct. In addition to that, it should be prefixed by either catalog or admin, which stands for the application. In our case, it's catalog as we're hooking into the front-end method. Finally, it'll be post-fixed by either before or after, which tells OpenCart to run our code accordingly.

The third argument points to the action of your controller that will be triggered when the event is fired. It's set to custom/product/info, so you'll have to create a Product controller with the info method under the custom directory, as we'll do in a moment.

Finally, the uninstall method is used to remove the event during the uninstallation of the module.

Next, let's create a language file for our custom module at admin/language/en-gb/module/demoevent.php with the following contents.

<?php
// admin/language/en-gb/module/demoevent.php
// Heading
$_['heading_title']          = 'Custom Event (Script Notification) Demo Module';

We've finished with the back-end file setup. Now, you should be able to see our module listed under Extensions > Modules in the back-end of OpenCart. Go ahead and install it. Now, we'll go ahead and create the files in the front-end.

Create a model file catalog/model/custom/product.php with the following contents. It's a typical model file as per the OpenCart structure.

<?php
// catalog/model/custom/product.php
class ModelCustomProduct extends Model {
  function getProductLastModifiedInfo($product_id) {
    $query = $this->db->query("SELECT date_modified FROM " . DB_PREFIX . "product WHERE product_id = '" . (int)$product_id . "'");

    return $query->row;
  }
 
  function updateProductInfo($product_id, $data) {
    include_once __DIR__.'../../../admin/model/catalog/product.php';
      
    $modelCatalogProduct = new ModelCatalogProduct();
    $modelCatalogProduct->editProduct($product_id, $data);
  }
}

It implements two important methods. The getProductLastModifiedInfo method is used to fetch the last modified date of the product, and the updateProductInfo method is used to update the product information in the database. In a moment, we'll see how these methods will be used.

Finally, let's create one of the most important files of this article, catalog/controller/custom/product.php, with the following contents. It's a controller file that implements the info action method that is set to be called when the getProduct method of the Product Model is called.

<?php
// catalog/controller/custom/product.php
class ControllerCustomProduct extends Controller {
    public function info($route, $product_id) {
        // fetch product info from API (psudo code)
        $product_api_info = api_call_to_fetch_product_info($product_id);
        
        // fetch product info from database
        $this->load->model('custom/product');
        $product_modified_date = $this->model_custom_product->getProductLastModifiedInfo($product_id);
        
        if ($product_modified_date['date_modified'] != $product_api_info['date_modified']) {
            // api info has changed so first let's update db
            // Note: you probably want to format $product_api_info as per the format required by editProduct method
            $this->model_custom_product->updateProductInfo($product_id, $product_api_info);
            
            // return latest/real-time product information
            return array(
                'product_id'       => $product_api_info['product_id'],
                'name'             => $product_api_info['name'],
                'description'      => $product_api_info['description'],
                'meta_title'       => $product_api_info['meta_title'],
                'meta_description' => $product_api_info['meta_description'],
                'meta_keyword'     => $product_api_info['meta_keyword'],
                'tag'              => $product_api_info['tag'],
                'model'            => $product_api_info['model'],
                'sku'              => $product_api_info['sku'],
                'upc'              => $product_api_info['upc'],
                'ean'              => $product_api_info['ean'],
                'jan'              => $product_api_info['jan'],
                'isbn'             => $product_api_info['isbn'],
                'mpn'              => $product_api_info['mpn'],
                'location'         => $product_api_info['location'],
                'quantity'         => $product_api_info['quantity'],
                'stock_status'     => $product_api_info['stock_status'],
                'image'            => $product_api_info['image'],
                'manufacturer_id'  => $product_api_info['manufacturer_id'],
                'manufacturer'     => $product_api_info['manufacturer'],
                'price'            => ($product_api_info['discount'] ? $product_api_info['discount'] : $product_api_info['price']),
                'special'          => $product_api_info['special'],
                'reward'           => $product_api_info['reward'],
                'points'           => $product_api_info['points'],
                'tax_class_id'     => $product_api_info['tax_class_id'],
                'date_available'   => $product_api_info['date_available'],
                'weight'           => $product_api_info['weight'],
                'weight_class_id'  => $product_api_info['weight_class_id'],
                'length'           => $product_api_info['length'],
                'width'            => $product_api_info['width'],
                'height'           => $product_api_info['height'],
                'length_class_id'  => $product_api_info['length_class_id'],
                'subtract'         => $product_api_info['subtract'],
                'rating'           => round($product_api_info['rating']),
                'reviews'          => $product_api_info['reviews'] ? $product_api_info['reviews'] : 0,
                'minimum'          => $product_api_info['minimum'],
                'sort_order'       => $product_api_info['sort_order'],
                'status'           => $product_api_info['status'],
                'date_added'       => $product_api_info['date_added'],
                'date_modified'    => $product_api_info['date_modified'],
                'viewed'           => $product_api_info['viewed']
          );
        }
    }
}

The important thing to note here is that OpenCart provides context-specific arguments to your method. The first $route argument tells you the route associated with the event that has been triggered. In our case, it should be catalog/product/getProduct. The second argument is the product id as it's a required argument by the actual getProduct method.

The logic is something like this: we'll compare the modified date of the product in the OpenCart database with the information that's returned by the API callback.

So the first step is to load the real-time product information from the API. Please note that the api_call_to_fetch_product_info method is just a dummy method that you would like to replace with your actual API call.

Next, we use the getProductLastModifiedInfo method, which was created in the earlier section, to fetch the modified date of the product from the OpenCart database.

Finally, we do the comparison, and if the date differs, it'll update the OpenCart database with the latest product information using the updateProductInfo method in our Model class.

We've also returned the product information in array format in the same way the actual getProduct would have returned. It's important to note that as we've provided the return value in our hook, it won't call any further event calls including the call to the original getProduct method as well.

So, in this way you could influence the execution flow in OpenCart. It's a really powerful way to alter the core functionality. However, you should be careful while approaching this solution as it gives you total control to change the resulting output of any method.

Conclusion

Today, we've discussed one of the exciting features in OpenCart called script notifications. We started with an introduction to the subject, and it was the latter half of the article that demonstrated how to use them by building a custom event module.

As always, 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.

Queries and comments are always welcome!