Create a Custom Shipping Method in OpenCart: Part Two

In this series, we're discussing the implementation of a custom shipping method module in OpenCart. In the first part, we enabled and configured our custom shipping method using the configuration form in the back-end. Today, we'll implement the files which are required by OpenCart so that it can detect the custom shipping method and list it along with the other enabled shipping methods during checkout.

I hope that you've created all the files from the first part of this series. If you haven't gone through the first part yet, I would encourage you to go through that before proceeding further. Also, I assume that you're using the latest version of OpenCart.

A Glance at the File Setup in the Front-End

Let's start with a list of the files required in the front-end.

catalog/language/english/shipping/custom.php: It's a language file in which we'll define the labels.
catalog/model/shipping/custom.php: It's a model file, which is important as most of the shipping calculation logic goes here.

So that's it as far as the front-end setup is concerned.

File Setup

Let's start with the language file setup.

Create a Language File

Create a file catalog/language/english/shipping/custom.php and paste the following contents in that file.

<?php
// Text
$_['text_title']       = 'Custom Rate';
$_['text_description'] = 'Custom Shipping Rate';

I don't think it requires any explanation, so let's move on!

Create a Model File

Create a file catalog/model/shipping/custom.php and paste the following contents in that file.

<?php
class ModelShippingCustom extends Model {
  function getQuote($address) {
    $this->load->language('shipping/custom');

    $query = $this->db->query("SELECT * FROM " . DB_PREFIX . "zone_to_geo_zone WHERE geo_zone_id = '" . (int)$this->config->get('custom_geo_zone_id') . "' AND country_id = '" . (int)$address['country_id'] . "' AND (zone_id = '" . (int)$address['zone_id'] . "' OR zone_id = '0')");

    if (!$this->config->get('custom_geo_zone_id')) {
      $status = true;
    } elseif ($query->num_rows) {
      $status = true;
    } else {
      $status = false;
    }

    $method_data = array();

    if ($status) {
      $quote_data = array();

      $quote_data['custom'] = array(
        'code'     => 'custom.custom',
        'title'    => $this->language->get('text_description'),
        'cost'     => $this->config->get('custom_cost'),
        'tax_class_id' => $this->config->get('custom_tax_class_id'),
        'text'     => $this->currency->format($this->tax->calculate($this->config->get('custom_cost'), $this->config->get('custom_tax_class_id'), $this->config->get('config_tax')))
      );

      $method_data = array(
        'code'     => 'custom',
        'title'    => $this->language->get('text_title'),
        'quote'    => $quote_data,
        'sort_order' => $this->config->get('custom_sort_order'),
        'error'    => false
      );
    }

    return $method_data;
  }
}

As per the OpenCart conventions, the class name should be ModelShippingCustom and there's a getQuote method which is a must for our shipping method to be picked up by OpenCart.

You should notice that the $address argument is passed in the getQuote method, which is the shipping address of the customer during checkout, and it allows us to decide if the current shipping method is applicable for the geo zone belonging to that address. It's decided by the following code.

$query = $this->db->query("SELECT * FROM " . DB_PREFIX . "zone_to_geo_zone WHERE geo_zone_id = '" . (int)$this->config->get('custom_geo_zone_id') . "' AND country_id = '" . (int)$address['country_id'] . "' AND (zone_id = '" . (int)$address['zone_id'] . "' OR zone_id = '0')");

if (!$this->config->get('custom_geo_zone_id')) {
  $status = true;
} elseif ($query->num_rows) {
  $status = true;
} else {
  $status = false;
}

Next, if the shipping method is applicable, we prepare the required array variables as per the conventions.

if ($status) {
  $quote_data = array();

  $quote_data['custom'] = array(
      'code'         => 'custom.custom',
      'title'        => $this->language->get('text_description'),
      'cost'         => $this->config->get('custom_cost'),
      'tax_class_id' => $this->config->get('custom_tax_class_id'),
      'text'         => $this->currency->format($this->tax->calculate($this->config->get('custom_cost'), $this->config->get('custom_tax_class_id'), $this->config->get('config_tax')))
  );

  $method_data = array(
      'code'       => 'custom',
      'title'      => $this->language->get('text_title'),
      'quote'      => $quote_data,
      'sort_order' => $this->config->get('custom_sort_order'),
      'error'      => false
  );
}

As you can see, we're using the $this->config->get method to load the values for the configuration variables like "custom_cost", "custom_tax_class_id" and "custom_sort_order". Recall the first part, in which we configured these values using the custom configuration form!

Also, an important snippet to notice is the value of the text key in the $quote_data array. It calculates and formats the total amount which will be charged for our custom shipping method. Specifically, it checks if any additional tax should be added to the "cost" of the shipping method. Recall the Tax Class setting we provided in our configuration form, in which we selected Taxable Goods. Thus, it'll add an extra tax to the total amount of the shipping method!

We've tried to keep our model part simple, but you could do all the calculations in this file as per your shipping method APIs if any. So that's it as far as the model part is concerned.

Demo in the Front-End

In the front-end, add a few products in the cart and start the checkout process. In Step 4: Delivery Method, you should be able to see our custom shipping method listed as shown in the following screenshot.

It's listed with the title "Custom Shipping Rate - $14.00". You may be surprised that although we configured the Cost parameter to 10, it's showing 14 in the list. As I mentioned earlier, we configured Taxable Goods in the Tax Class field in the configuration form in the back-end.

Navigate to Localization > Taxes > Tax Classes, and edit Taxable Goods. You'll see that 20% VAT and a flat 2$ Eco Tax are configured for this tax class. Thus, it adds a further $4 to the cost of the shipping method! Of course, if you set Tax Class to None, tax won't be applied at all!

So, that's it for today. We've now successfully created a fully fledged custom shipping method module in OpenCart!

Conclusion

I hope that you've enjoyed this two-part series and you've learned something useful. If you're looking for more OpenCart applications, don't forget to check out what we have available for sale on the market. Don't forget to share your reviews and queries using the feed!

HIGHLIGHTS OF THE DAY