Shipping Method for WooCommerce Development Tutorial

Recently, I was learning about WooCommerce development, The problem which I found during that period is the lack of tutorials. What I really don’t appreciate about WooCommerce is its documentation. It’s not that bad, but sometimes it’s a little vague and you can’t manage to completely understand what is going on.

When I started developing Australia Post Shipping Method, I found out that I have to read the code of other shipping methods in order to get all the things right.

Today, I will explain how to develop a simple shipping method for WooCommerce step by step and I will make the plugin files available for download.

What is WooCommerce Extension?

WooCommerce extension is simply an ordinary WordPress plugin, The only difference is WooCommerce extension is built to extend the functionality of WooCommerce. For example, it could be a payment gateway or a shipping method. Also, it could add new features to WooCommerce such as invoicing, checkout page customizations, login with facebook …etc

What are we trying to achieve?

Let’s assume that there is a company called “Fast Delivery Inc.”, Fast Delivery depends on the weight and the dimensions of the package to calculate the shipping rates. The following table is explaining exactly how the rates are calculated.

 

In real life, the calculations are much more complex, and many factors get involved with it, especially the destination. But for the sake of simplicity, we will stick with that table.

As you see in the table, Fast Delivery does not support packages that weigh more than 10kg, so our shipping method won’t be available for products that weigh more than 10kg.

 

Create the main file of the shipping method

Ok, let’s start the real deal and write some code. The first thing we have to do is to create a new folder in the “plugin” folder, let’s name it “woocommerce-fast-delivery-shipping-method”. Inside this folder create a new PHP file and name it “fast-delivery-shipping-method.php”.  This file will be the main file of the plugin, that’s where we have to put the WordPress plugin header.

<?php

/*

Plugin Name: WooCommerce Fast Delivery Shipping Method

Plugin URI: http://www.waseem-senjer.com

Description: WooCommerce calculator for Fast Delivery Inc.

Version: 1.0.0

Author: Waseem Senjer

Author URI: http://www.waseem-senjer.com

*/

I’m assuming that you have an experience in WordPress plugin development, so this header should be familiar to you.

[alert_box style=”info” close=”no” ]It’s always preferable to start the name of WooCommerce extensions with “woocommerce” prefix, that will give a straight idea to the user or other developers that this plugin is a WooCommerce extension.[/alert_box]

Ask if WooCommerce is installed and activated

Now, we must ask if WooCommerce is installed and activated on the website because if it’s not, then our plugin is useless. Furthermore, it will generate a lot of errors if WooCommerce is not activated. This is how we do that.

/**

 * Check if WooCommerce is active

 */

$active_plugins = apply_filters( ‘active_plugins’, get_option( ‘active_plugins’ ) );

if ( in_array( ‘woocommerce/woocommerce.php’,  $active_plugins) ) {

  // The rest of our plugin’s code goes here.

}

First, we need to get a list of the currently activated plugins, WordPress saves a list of the activated plugins in the database via the Options API, They use the key “active_plugins”, so we simply get this list by

get_option( ‘active_plugins’ );

This line will return an array of strings with this format “{plugin_folder_name}/{main_plugin_file}.php” , then if we want to check if WooCommerce whether installed or not, we need to search the array for “woocommerce/woocommerce.php”, “woocommerce” is the folder of WooCommerce in the plugins folder, and “woocommerce.php” is the main WooCommerce plugin file. We searched the array using a PHP function “in_array”. If this function returned true, then we will write our plugin code into the “if” block.

Add your shipping method to the default methods of WooCommerce

After we made sure that WooCommerce is activated, we will start writing the core code of our plugin, We will add our shipping method to the default WooCommerce shipping methods by using the filter “woocommerce_shipping_methods” which is provided by WooCommerce.

add_filter( ‘woocommerce_shipping_methods’, ‘add_fast_delivery_shipping_method’ );

  function add_fast_delivery_shipping_method( $methods ) {

    $methods[] = ‘WC_Fast_Delivery_Shipping_Method’;

    return $methods;

  }

This filter takes the default shipping methods array as a parameter, we will add our own shipping method by adding a new element to that array which is the class name of our shipping method (We will write this class next). Finally, do not forget to return the modified array.

 

Include the shipping method class

The last remaining thing to do in the main file of the plugin is to include the class file of the shipping method. We will use a WooCommerce action hook called “woocommerce_shipping_init”, This action will be executed when WooCommerce actually needs to call the shipping methods.

add_action( ‘woocommerce_shipping_init’, ‘fast_delivery_shipping_method_init’ );

function fast_delivery_shipping_method_init(){

   require_once ‘class-fast-delivery-shipping-method.php’;

}

Now the main file of our plugin looks like this:

/*

Plugin Name: WooCommerce Fast Delivery Shipping Method

Plugin URI: http://www.waseem-senjer.com

Description: WooCommerce calculator for Fast Delivery Inc.

Version: 1.0.0

Author: Waseem Senjer

Author URI: http://www.waseem-senjer.com

*/

/**

 * Check if WooCommerce is active

 */

$active_plugins = apply_filters( ‘active_plugins’, get_option( ‘active_plugins’ ) );

if ( in_array( ‘woocommerce/woocommerce.php’, $active_plugins) ) {
 add_filter( ‘woocommerce_shipping_methods’, ‘add_fast_delivery_shipping_method’ );

 function add_fast_delivery_shipping_method( $methods ) {

   $methods[] = ‘WC_Fast_Delivery_Shipping_Method’;

   return $methods;

 }
 add_action( ‘woocommerce_shipping_init’, ‘fast_delivery_shipping_method_init’ );

 function fast_delivery_shipping_method_init(){

   require_once ‘class-fast-delivery-shipping-method.php’;

 }
}

The Shipping Method Class

The main code in any shipping method is its class, let’s create a file and name it “class-fast-delivery-shipping-method.php”. Open this file and write the following:

<?php

class WC_Fast_Delivery_Shipping_Method extends WC_Shipping_Method{

}

You should give attention to two things. First, The class name must match the name that we gave it to the “woocommerce_shipping_methods” filter in the main file of the plugin. Second, The class file name should also match the file name that we required in the “woocommerce_shipping_init” action.

The class must extend the “WC_Shipping_Method” class which is an abstract class provided by WooCommerce to implement the shipping method functionalities.

These are the minimum methods that you have to implement in order to the shipping method to work properly.

class WC_Fast_Delivery_Shipping_Method extends WC_Shipping_Method{

  public function __construct(){}

  public function init_form_fields(){}

  public function is_available( $package ){}

  public function calculate_shipping($package){}
}

The constructor

The first thing to start with is the constructor. In the constructor, we will write some lines of codes to initialize the shipping method.

public function __construct(){

  $this->id = ‘fast_delivery_shipping_method’;

  $this->method_title = __( ‘Fast Delivery Shipping Method’, ‘woocommerce’ );
  // Load the settings.

  $this->init_form_fields();

  $this->init_settings();
  // Define user set variables

  $this->enabled	= $this->get_option( ‘enabled’ );

  $this->title 		= $this->get_option( ‘title’ );
  add_action( ‘woocommerce_update_options_shipping_’ . $this->id, array( $this, ‘process_admin_options’ ) );
}

Let’s divide the code and walk through it.

$this->id = 'fast_delivery_shipping_method';

This is a unique id that we give to our shipping method, it will work as a reference to the shipping method.

$this->method_title = __( ‘Fast Delivery Shipping Method’, ‘woocommerce’ );

This is the method title which will appear to the admin in the Dashboard.

$this->init_form_fields();

Here, we call “init_form_fields()” which we will implement it later, This method is responsible for creating the settings fields for the admin. I will explain it later.

$this->init_settings();

This method is inherited from the Settings API class of WooCommerce which it gets inherited by WC_Shipping_Method class. It’s mainly responsible for retrieving the settings values from the database and load them into the settings field in the settings page of the shipping method settings page.

$this->enabled = $this->get_option( ‘enabled’ );

I’m getting the value of “enabled”, this attribute is inherited from the abstract class, and it stores whether the shipping method is enabled or disabled by the admin.

$this->title = $this->get_option( ‘title’ );

This is also an inherited attribute from the abstract class, The “title” stores the title of the shipping method which will appear to the visitor on the checkout page.

 add_action( ‘woocommerce_update_options_shipping_’ . $this->id, array( $this, ‘process_admin_options’ ) );

The last line is very important, it’s responsible for processing the admin options of the shipping method and saving them in the database. We add an action hook “woocommerce_update_options_shipping_” and appending the shipping method id. Then, “process_admin_options” will be called when the admin clicks on “Save Changes” button, this method is also inherited from the Settings API class of WooCommerce.

Settings Fields

As I said in the constructor part, we have to implement the “init_form_fields” method. This method uses the Settings API of WooCommerce.  Here we set the fields that we want to provide to the admin so he can control the shipping method. As you see in the implementation below, I assigned an associative array to the attribute “form_fields”, This attribute is coming from the Settings API class, The array represents the form fields of the admin page of the shipping method. Please, read about the possible options for this array in Settings API of WooCommerce documentation, it’s short and useful.

public function init_form_fields() {

  $this->form_fields = array(

    ‘enabled’ => array(

      ‘title’ 		=> __( ‘Enable/Disable’, ‘woocommerce’ ),

      ‘type’ 			=> ‘checkbox’,

      ‘label’ 		=> __( ‘Enable Fast Delivery Shipping’, ‘woocommerce’ ),

      ‘default’ 		=> ‘yes’

    ),

    ‘title’ => array(

      ‘title’ 		=> __( ‘Method Title’, ‘woocommerce’ ),

      ‘type’ 			=> ‘text’,

      ‘description’ 	=> __( ‘This controls the title which the user sees during checkout.’, ‘woocommerce’ ),

      ‘default’		=> __( ‘Fast Delivery Shipping’, ‘woocommerce’ ),
    )

  );

}

Availability

If we want to make the shipping method not available for specific conditions, and as our example of Fast Delivery which they do not ship packages that weigh more than 10kg. That means when the visitor purchases a product that weighs more than 10kg, our shipping method won’t appear to him. We will implement that by implementing the “is_available” method.

public function is_available( $package ){

  foreach ( $package[‘contents’] as $item_id => $values ) {

      $_product = $values[‘data’];

      $weight =	$_product->get_weight();

      if($weight > 10){

      	return false;

      }

  }
  return true;
}

As you see, “is_available” method takes one parameter $packacge, This is an array that contains information about the products of the order. We can access the order items by using $package[‘contents’]. If you want to access the address of the package, you can use $package[‘destination’]. I advise printing the $package parameter to know what exactly it looks like. It will give you a complete image of the possibilities of this parameter.
Now to return to our table of rates, the shipping method must be not available if one of the products is weighing more than 10kg. When we are looping the package contents, you can get the current product object by 

$_product = $values[‘data’];

And to get the weight of the product, I used the method get_weight(). After that, I asked if the weight is more than 10kg If so, I  made the method to return false. That’s it, you do your conditions and simply return true or false, this will reflect the shipping method availability. If you returned false, the shipping method will not appear on the checkout page.

Calculate Shipping Rate

Finally, we will implement the most important part of any shipping method, the rate calculations. To calculate the rates, you have to implement the abstract method “calculate_shipping”, and similar to “is_available” it also takes the $package parameter.  This is how the implementation looks like.

public function calculate_shipping($package){

    //get the total weight and dimensions

    $weight = 0;

    $dimensions = 0;

    foreach ( $package[‘contents’] as $item_id => $values ) {

      $_product  = $values[‘data’];

      $weight =	$weight + $_product->get_weight() * $values[‘quantity’];

      $dimensions = $dimensions + (($_product->length * $values[‘quantity’]) * $_product->width * $_product->height);
    }
    //calculate the cost according to the table

    switch ($weight) {

        case ($weight < 1):

          switch ($dimensions) {

            case ($dimensions <= 1000):

            $cost = 3;

            break;

            case ($dimensions > 1000):

            $cost = 4;

            break;

          }

         break;

        case ($weight >= 1 && $weight < 3 ):

          switch ($dimensions) {

            case ($dimensions <= 3000):

            $cost = 10;

            break;

          }

        break;

        case ($weight >= 3 && $weight < 10):

          switch ($dimensions) {

            case ($dimensions <= 5000):

            $cost = 25;

            break;

            case ($dimensions > 5000):

            $cost = 50;

            break;

          }

         break;
      }
    // send the final rate to the user.

    $this->add_rate( array(

      ‘id’ 	=> $this->id,

      ‘label’ => $this->title,

      ‘cost’ 	=> $cost

    ));

}

Let’s walk through that code.

//get the total weight and dimensions

    $weight = 0;

    $dimensions = 0;

    foreach ( $package[‘contents’] as $item_id => $values ) {

      $_product  = $values[‘data’];

      $weight =	$weight + $_product->get_weight() * $values[‘quantity’];

      $dimensions = $dimensions + (($_product->length * $values[‘quantity’]) * $_product->width * $_product->height);

    }

Here, I calculated the total weights and dimensions of all the products of the order, but you should notice that we must pay attention if the user ordered more than one quantity from the product. We have to multiply the weight and the length by the quantity. Width and height do not change corresponding to the quantity.

After the weight and dimensions calculations, I wrote a switch statement that represents the Fast Delivery Inc rates table and calculated the final cost according to it.

// send the final rate to the user.

    $this->add_rate( array(

      ‘id’ 	=> $this->id,

      ‘label’ => $this->title,

      ‘cost’ 	=> $cost

    ));

After calculating the cost, we have to add it by using “add_rate” method. It will take an array as a parameter. This array contains the ID of the shipping method, the title of the shipping method and the final cost of the shipping. Then, WooCommerce will take care of the rate and shows it to the visitor.

Conclusion

I explained the most simple form of a shipping method. Usually, the shipping method will be more complicated. For example, you won’t find a shipping method with simple rules like this, and to resolve this problem, shipping companies provide an API to their services. Developers can interact with these APIs and calculate the shipping rate directly from the shipping company.

Every company has different rules and to develop a shipping method for them you must read their documentation of their API. In WordPress, you can interact with different APIs by using the ‘wp_remote_get‘ function.

In my opinion, the best way to learn how to implement a shipping method or a payment gateway is to read other developers’ code. You’ll examine how they solve common problems with these extensions and to know a lot of information that the WooCommerce official docs don’t provide.

Please do not hesitate to ask me any questions, I will try my best to answer you. Also, If you liked this tutorial, you can subscribe to my newsletter to get the next posts immediately into your email.

Download the Extension Files

 

Update: Supporting Shipping Zones in WooCommerce 2.6+

WooThemes introduced Shipping Zones in WooCommerce 2.6. In the new shipping structure, you can create multiple shipping zones and assign different shipping zones to them. Each shipping method which is assigned to a zone will have different settings. This will help customers to customize each zone differently. Our concern as developers is that your shipping method will be used as an instance whenever it’s assigned to a zone.

To support shipping zones in your shipping method, you need to do some minor changes to the previous code. Let’s go through these changes and explain them.

The constructor.

1. We will add $instace_id to the constructor. The constructor declaration should be 

   public function __construct( $instance_id = 0 ){
   

2. Inside the constructor, we need to assign the passed $instance_id. Adding this line will do it. 

   $this->instance_id = absint( $instance_id );
   

3. Then, we declare the support of shipping zones.
   

   $this->supports  = array(
   
    			‘shipping-zones’,
   
     			‘instance-settings’,
   
     			‘instance-settings-modal’,
   
    		);
   

This is all that we need to change in the constructor of our method.

The settings form fields.

In the method “init_form_fields”, one simple line need to be changed, instead of $this->form_fields, we need to use $this->instance_form_fields

The calculate_shipping method.

Also, a minor change here, we should assign the $package parameter to a default value, so the calculate_shipping method declaration should be 

public function calculate_shipping( $package = array() ){

The main plugin’s file.

When you use the “woocommerce_shipping_methods” filter, replace this line

$methods[] = ‘WC_Fast_Delivery_Shipping_Method’;

by

 $methods[‘fast_delivery_shipping_method’] = ‘WC_Fast_Delivery_Shipping_Method’;

‘fast_delivery_shipping_method‘ is the $id attribute value in the shipping method class we assigned in the constructor method.

Please, let me know if you have any questions regarding shipping zones support.