Improved shipping handling

A shipping handler adds the cost of shipping to the basket. Exponential calls it when the basket changes and shows its result under the items and in the order total; product pages show prices without shipping. No shipping handler ships with Exponential 6: without one, no shipping cost is added.

Settings

The handler is chosen in shop.ini, block [ShippingSettings]. The shipped file leaves Handler commented out.

[ShippingSettings]
# the handler: "mycost" means class MyCostShippingHandler in mycostshippinghandler.php
Handler=mycost
# extensions whose shippinghandlers/ folder is searched
ExtensionDirectories[]=myextension
# other folders that are searched (the shipped value points to a folder that does not exist in 6.x)
RepositoryDirectories[]=kernel/classes/shippinghandlers

The file is looked up as <folder>/<handler>shippinghandler.php in each ExtensionDirectories extension's shippinghandlers/ folder and in each RepositoryDirectories folder, and the class is <Handler>ShippingHandler. A handler that is named but not found is reported in the debug output and no shipping is added.

Writing a handler

A handler is a class with three methods. eZShippingManager calls them with the id of the basket's product collection.

<?php
// extension/myextension/shippinghandlers/mycostshippinghandler.php
class MyCostShippingHandler
{
    // shipping information for a product collection
    function getShippingInfo( $productCollectionID )
    {
        return array(
            'description' => 'Standard delivery', // shown in the basket
            'cost' => 10.0,                        // shipping cost
            'vat_value' => 19,                    // VAT percentage of the cost
            'is_vat_inc' => 1,                    // the cost includes VAT
            'management_link' => '/shop/basket/'   // where the options can be changed
        );
    }

    // the basket changed: update stored shipping data, if any
    function updateShippingInfo( $productCollectionID )
    {
    }

    // the product collection was removed: clean up stored shipping data, if any
    function purgeShippingInfo( $productCollectionID )
    {
    }
}

Put the settings in extension/myextension/settings/shop.ini.append.php, activate the extension under Setup > Extensions, regenerate the autoloads (php bin/php/ezpgenerateautoloads.php -e) and clear the INI cache.

getShippingInfo() should also return vat_value (the VAT percentage of the shipping cost, or false when the cost mixes several rates) and is_vat_inc (1 when cost includes VAT, 0 when it does not). Shipping that falls under several VAT rates is returned as a list in shipping_items, each item with its own description, cost, vat_value and is_vat_inc, next to the totals. The documented structure is in the comment of eZShippingManager::getShippingInfo() (kernel/classes/ezshippingmanager.php).

Basket information handlers

The totals the basket shows come from a basket information handler, set in shop.ini [BasketInfoSettings] Handler (default ezdefault, in kernel/classes/basketinfohandlers), which is found the same way.

Limits

• There is one handler for the whole installation. Letting the buyer choose a delivery method needs a handler that stores the choice itself, for example per product collection.
• Payment, VAT and order handling are configured separately: see the VAT charging system.

Related pages

• shop.ini
• Multi-currency