Creating new VAT handlers

This section reveals some helpful tips for those developers who want to create a new VAT 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.

Handler interface

This section describes some implementation details that can be useful for PHP developers.

A VAT handler is a file that contains a class implementing the following method:

/**
*
* \public
* \static
* \param $object      The product content object.
* \param $country     Country the buyer is from, or false if not specified.
* \return             VAT percent (integer), or null in case of an error.
*/
mixed function getVatPercent( eZContentObject $object, mixed $country );

A handler is not called directly but via eZVATManager class. Method getVAT() of that class returns the VAT percentage that should be charged for a given product:

$vatPercent = eZVATManager::getVAT( $object, $country );

All that getVAT() method does is invoking getVatPercent() method of the handler specified in the "Handler" INI setting.

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

Creating your own handler

Let's say that you need to determine the VAT percentage for a product depending on the section this product belongs to. You can create your own VAT handler called "mysectionbased" as described below.

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

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

   <?php
   class MySectionBasedVATHandler
   {
       /**
        * \public
        * \static
        */
       function getVatPercent( $object, $country )
       {
           $section = $object->attribute( 'section_id' );
           if ( $section == 1 )
               $percentage = 10;
           else
               $percentage = 20;
           return $percentage;
       }
   }
   ?>
   

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

   [VATSettings]
   ExtensionDirectories[]=myextension
   Handler=mysectionbased
   RequireUserCountry=false
   DynamicVatTypeName=Section based VAT
   

   This will instruct eZ publish to use the VAT handler located at "extension/myextension/vathandlers/mysectionbasedvathandler.php". Since the VAT percentage determined by this handler does not depend on user country, the "RequireUserCountry" setting must be set to false. Since this handler does not use the VAT rules, it is reasonable to display the name of the dynamic VAT type as "Section based VAT" (not "Determined by VAT charging rules"). This is done by using the "DynamicVatTypeName" setting.
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.