Exchange rate handlers
This page is for developers of stores that sell in several currencies with automatic prices (Price fields compared). Rates are fetched by an exchange rates update handler when someone presses Update autorates in Store > Currencies. The kernel ships one handler, for the European Central Bank; this page shows how to use another source.
Contents
The shipped handler
eZECBHandler (kernel/shop/classes/exchangeratehandlers/ezecb/ezecbhandler.php) reads the server, port and address
from shop.ini [ECBExchangeRatesSettings] and the daily rates file there. Its rates are relative to the euro, matching
the shipped [ExchangeRatesSettings] BaseCurrency=EUR (shop.ini walkthrough).
The base class
eZExchangeRatesUpdateHandler (kernel/shop/classes/exchangeratehandlers/ezexchangeratesupdatehandler.php):
| Member | Meaning |
|---|---|
initialize( $params ) | Reads settings; the base reads BaseCurrency |
requestRates() | Fetches rates and stores them with setRateList(); returns a status |
rateList(), setRateList() | The rates, keyed by currency code |
baseCurrency(), setBaseCurrency() | The currency the rates are relative to |
OK, CANT_CREATE_HANDLER, FAILED, EMPTY_RATE_LIST, UNKNOWN_BASE_CURRENCY, INVALID_BASE_CROSS_RATE | Status codes |
Writing a handler
- Extend
eZExchangeRatesUpdateHandler; read your source's settings ininitialize()after calling the parent. - In
requestRates(), fetch the rates, build an arraycurrency code => raterelative to your base currency, callsetRateList()and returnself::OK, or a failure code. - Fail safely: on a network error or an empty answer, return a failure code and leave the old rates in place, so prices are never converted with nonsense.
The RAD handler wizard has an exchange rate handler recipe (Developer path).
Registering it
eZExchangeRatesUpdateHandler::create() lowercases the name and includes <directory>/<name>/<name>handler.php, class
<name>handler:
# extension/mystore_shop/settings/shop.ini.append.php
[ExchangeRatesSettings]
ExchangeRatesUpdateHandler=mystorerates
ExtensionDirectories[]=mystore_shop
BaseCurrency=EURFile: extension/mystore_shop/exchangeratehandlers/mystorerates/mystorerateshandler.php, class mystoreratesHandler.
Keeping rates and prices current
Two separate steps update a multi-currency store: Update autorates fetches rates, Update autoprices recalculates
automatic prices (eZShopFunctions::updateAutoRates(), updateAutoprices()). Neither runs on its own in the shipped
settings. Either make it part of a routine (Operations calendar) or write a
cron part that calls both (Writing a cronjob part). Custom
prices are never touched by either step.
Related pages
- Extending the shop
- Prices and currencies (running your store)
- Prices and currencies (businesses)
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.