Exchange rates update handlers

The exchange rates update handlers make it possible to retrieve the latest exchange rates from external sources and thus update the auto rates. You should specify the desired handler in the "ExchangeRatesUpdateHandler" setting described in the next subsection, otherwise the system will not be able to update the auto rates. You can either use the built-in "eZECB" handler for getting the exchange rates from the website of the European Central Bank or extend the system by creating your own update handler.

Settings

The "[ExchangeRatesSettings]" section of the "settings/shop.ini" configuration file defines the update handler that will be used for updating auto rates. Under this section, the following settings can be specified:

• The "RepositoryDirectories[]" array specifies the directories where eZ publish will search for built-in update handlers. The exact location of the handler in the directory is specified using the "ExchangeRatesUpdateHandler" setting.
• The "ExtensionDirectories[]" array specifies the extension directories where eZ publish will search for additional update handlers. By default eZ publish will search in the "exchangeratehandlers" subdirectory inside your extension. The exact location of the handler in the directory is specified using the "ExchangeRatesUpdateHandler" setting.
• The "ExchangeRatesUpdateHandler" setting specifies the update handler that will be used.
• The "BaseCurrency" setting specifies the base currency for auto rates. The default value of this setting is "EUR". It is recommended (but not required) that you specify one of the existing currencies in this setting.

The "[ECBExchangeRatesSettings]" section of the "settings/shop.ini" configuration file defines the specific settings for the "eZECB" update handler. The combination of the "ServerName", "ServerPort" and "RatesURI" settings allows to specify the exact address of the XML file containing the currency rates.

Example 1

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

ExchangeRatesUpdateHandler=eZECB
RepositoryDirectories[]=kernel/shop/classes/exchangeratehandlers
ExtensionDirectories[]
BaseCurrency=EUR

These settings will instruct eZ publish to use the built-in update handler located at"kernel/shop/classes/exchangeratehandlers/ezecb/ezecbhandler.php" and use EUR as the base currency for auto rates.

Example 2

You can extend the system by creating custom update handlers for special needs. For example, if you have an extension "myshop" that includes an update handler "mybank", you can put the following lines into an override for the "shop.ini" configuration file:

[ExchangeRatesSettings]
ExchangeRatesUpdateHandler=mybank
ExtensionDirectories[]=myshop/classes

or

[ExchangeRatesSettings]
ExchangeRatesUpdateHandler=mybank
RepositoryDirectories[]=extension/myshop/classes/exchangeratehandlers/

These settings will instruct eZ publish to use the update handler located at"extension/myshop/classes/exchangeratehandlers/mybank/mybankhandler.php"

Example 3

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

ServerName=http://www.ecb.int
ServerPort=80
RatesURI=stats/eurofxref/eurofxref-daily.xml

These settings will instruct the eZECB handler to import the currency exchange rates from http://www.ecb.int:80/stats/eurofxref/eurofxref-daily.xml.

Creating new handlers

This section reveals some helpful tips for those developers who want to create a new exchange rates update 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 implement it as an extension. The following list reveals how you can implement your own handler for rates updating.

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

   • myextension
   • myextension/settings
   • myextension/exchangeratehandlers
   • myextension/exchangeratehandlers/mybank
2. Create a file called "mybankhandler.php" in the "myextension/exchangeratehandlers/mybank" directory. This file must contain a PHP class called "MyBankHandler". You should extend your class from the "eZExchangeRatesUpdateHandler" class (kernel/shop/classes/exchangeratehandlers/ezexchangeratesupdatehandler.php) and reimplement the "initialize" and "requestRates" functions. The "initialize" function is called while creating a handler-object. It allows to initialize your handler with some preset values (for example from INI file). The "requestRates" function performs the actual update of the rates. This function will assign an array of the retrieved rate values to the "$RateList" member variable in the following format:

   $RateList = array( 'currencyCode1' => 'rateValue1',
   .....
   'currencyCodeN' => 'rateValueN' );
   

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

   [ExchangeRatesSettings]
   ExchangeRatesUpdateHandler=mybank
   ExtensionDirectories[]=myextension
   

   This will instruct eZ publish to use the update handler located at"extension/myextension/exchangeratehandlers/mybank/mybankhandler.php".
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.