Improved shipping handling

eZ publish 3.8 makes it possible to define custom shipping options for your webshop (e.g. the cost of shipping may depend on the product properties). This could be done by implementing a shipping handler i.e. PHP class providing a mechanism that keeps shipping information for a product collection (basket or order) and calculates the cost of shipping for it. eZ publish does not include any built-in shipping handlers so you will need to extend the system by creating your own shipping handler in order to add shipping options for your webshop. Using two or more shipping handlers at the same time is not supported (within one siteaccess). The shipping handler to use must be specified in the "Handler" INI setting described in the "INI settings" subsection.

When a user is viewing a product page, no shipping cost will be displayed and included into product price. After adding some products to the basket the system will calculate their shipping cost that will be shown under the list of items and included into order total. A shipping handler returns not only shipping cost but also shipping options summary and a link to the shipping management interface where shipping options can be modified. This information will be displayed in the basket together with the shipping cost. The system will also show shipping cost and shipping options summary when asking a user to confirm his/her order and in the order view interface for site administrators.

INI settings

The "[ShippingSettings]" section of the "settings/shop.ini" configuration file defines the shipping handler that will be used for calculating the cost of shipping for your products. Under this section, the following settings can be specified:

• The "Handler" setting specifies the shipping handler that will be used.
• The "RepositoryDirectories[]" array specifies the directories where eZ publish will search for built-in shipping handlers.
• The "ExtensionDirectories[]" array specifies the extension directories where eZ publish will search for additional shipping handlers. By default eZ publish will search in the "shippinghandlers" subdirectory inside your extension.

Example 1

The following lines can be specified under the "[ShippingSettings]" section of the "shop.ini" configuration file:

[ShippingSettings]
Handler=ezcustom
RepositoryDirectories[]=kernel/classes/shippinghandlers

These settings will instruct eZ publish to use the shipping handler located at "kernel/classes/shippinghandlers/ezcustomshippinghandler.php".

Example 2

If you have an extension "myextension" that includes a shipping handler "mycost", you can put the following lines into an override for the "shop.ini" configuration file:

[ShippingSettings]
Handler=mycost
ExtensionDirectories[]=myextension

or

[ShippingSettings]
Handler=mycost
RepositoryDirectories[]=extension/myextension/shippinghandlers

These settings will instruct eZ publish to use the VAT handler located at "extension/myextension/shippinghandlers/mycostshippinghandler.php".

Creating new shipping handlers

This section reveals some helpful tips for those developers who want to create a new shipping handler (only for people who are familiar with PHP). Please note that it is not recommended to modify the eZ publish kernel and thus you should implement it as an extension.

Implementation details

A shipping handler is a file that contains a class implementing the following methods:

/**
* Invoked to get shipping information for given product collection.
* \public
* \static
*/
function getShippingInfo( $productCollectionID );
 
/*
* Invoked when shopping basket contents is changed
* to update shipping info/cost appropriately.
* \public
* \static
*/
function updateShippingInfo( $productCollectionID );
 
/**
* Invoked when the associated product collection is removed
* to clean up shipping information.
* \public
* \static
*/
function purgeShippingInfo( $productCollectionID );

A handler is called via eZShippingManager class that has the same methods.

$shippingInfo = eZShippingManager::getShippingInfo( $productCollection );

All that getShippingInfo() method does is invoking getShippingInfo() method of the shipping handler that is specified in the "Handler" INI setting. This method returns shipping information for a given product collection as a hash containing the following elements:

The next subsection explains how you can implement your own shipping handler.

Creating your own handler

The following text describes the implementation of a trivial shipping handler for demonstration purposes.

1. Create the following subdirectories in the "extension" directory of your eZ publish installation:

   • myextension
   • myextension/settings
   • myextension/shippinghandlers
2. Create a file called "mycostshippinghandler.php" in the "myextension/shippinghandlers/" directory (this file must contain a PHP class called "MyCostShippingHandler") and add the following lines into it:

   <?php
   class MyCostShippingHandler
   {
       function getShippingInfo( $productCollectionID )
       {
           return array(
           'description' => 'Manual',
           'cost' => 10,
           'management_link' => '/shop/basket/' // dummy
           );
       }
       function purgeShippingInfo( $productCollectionID )
       {
           // nothing to purge
       }
       function updateShippingInfo( $productCollectionID )
       {
           // nothing to update
       }
   }
   ?>
   

3. Create a file called "shop.ini.append.php" in the "myextension/settings" directory and add the following lines into it:

   [ShippingSettings]
   Handler=mycost
   ExtensionDirectories[]=myextension
   

4. To activate your extension in eZ publish, log in to your eZ publish administration interface, click on the "Setup" tab, and then click "Extensions" on the left. You will see the list of available extensions. Select the "myextension" item and click the "Apply changes" button.

This will make the system add the fixed cost of shipping to any set of products being purchased from your site.

If you need more complicated shipping options, you can try to use the advanced example from http://ez.no/community/contribs/examples/sample_shipping_handler or develop your own shipping handler.