Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,110 of 9,110 pages
About the help in other languages
All help pages

Exchange rate handlers

Where an Exponential store gets its exchange rates - the eZECB handler, the eZExchangeRatesUpdateHandler base class with its rate list and error codes, writing a handler for another rate source, registration, and…

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/e-commerce/extending/exchange-rate-handlers.md

On this page

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

  1. The shipped handler
  2. The base class
  3. Writing a handler
  4. Registering it
  5. Keeping rates and prices current

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):

MemberMeaning
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_RATEStatus codes

Writing a handler

  1. Extend eZExchangeRatesUpdateHandler; read your source's settings in initialize() after calling the parent.
  2. In requestRates(), fetch the rates, build an array currency code => rate relative to your base currency, call setRateList() and return self::OK, or a failure code.
  3. 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=EUR

File: 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.

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.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x