vojtasvoboda/oc-cnbrates-plugin

ČNB rates plugin for OctoberCMS

1.0.3 2016-04-02 17:24 UTC

Requires

• php: >=5.5.9

MIT

• Vojta Svoboda

• plugin
• rates
• exchange
• october
• cnb

README

ČNB Rates plugin provide financial data from ČNB (Czech National Bank).

Implemented ČNB services: Exchange rates, PRIBOR rates.

Features:

• automatically daily update
• fires event after update, so integration is very easy
• prepared for implementating other ČNB services
• covered by unit tests

Required plugins: none. Tested with the latest stable OctoberCMS build 349.

Installation

• install plugin VojtaSvoboda.CnbRates from your Backend -> Settings -> System -> Updates -> Install plugins
• select which services you want to use at Settings -> System -> Misc -> ČNB Rates

Events

The best and easiest way how to use this plugin is by events.

This plugin provide two events. When you set Scheduled updates correctly (see below), this events will be fired each day automatically and always comes with fresh rates data.

• vojtasvoboda.cnbrates.exchange.updated Fired when exchange rates are updated
• vojtasvoboda.cnbrates.pribor.updated Fired when PRIBOR rates are updated

Using event in your Plugin.php:

public function boot()
{
    // ČNB rates update listener
    Event::listen('vojtasvoboda.cnbrates.exchange.updated', function($rates)
    {
        // update my plugin with fresh data
        $this->updateMyProducts($rates);
    });
}

All methods are fired after calling update method e.g. updateTodayExchangeRates() manually or by scheduler.

Scheduled updates

For scheduled updates to operate correctly, you should add the following Cron entry to your server. Editing the crontab is commonly performed with the command crontab -e.

* * * * * php /path/to/artisan schedule:run >> /dev/null 2>&1

Be sure to replace /path/to/artisan with the absolute path to the artisan file in the root directory of October.

Thats all, rates will be updated every day and related events will be fired.

Exchange rates service

Data are taken from official daily exchange rate list.

Get all exchange rates

$cnb = App::make('cnb');
// rates for today
$rates = $cnb->getExchangeRates();
// for specific date
$rates = $cnb->getExchangeRates('12.1.2016');

Get exchange rate only for EUR currency

$cnb = App::make('cnb');
// rates for today
$rates = $cnb->getExchangeRate();
// for specific date
$rates = $cnb->getExchangeRate('12.1.2016');

Callable service used for CRON call

Downloads daily exchange rates, saves it to cache and fires vojtasvoboda.cnbrates.exchange.updated event. This method is prepared for using by CRON (see Setting CRON section).

$cnb = App::make('cnb');
$cnb->updateTodayExchangeRates();

PRIBOR rates service

Data are taken from official daily PRIBOR rate list.

More about PRIBOR.

PRIBOR is changed daily and is calculated for these intervals: year, 9 months, 6 months, 3 months, 2 months, month, 2 weeks, week and for one day.

Get all PRIBOR rates

$cnb = App::make('cnb');
// rates for today
$rates = $cnb->getPriborRates();
// for specific date
$rates = $cnb->getPriborRates('12.1.2016');

Get PRIBOR rate only for concrete interval

$cnb = App::make('cnb');
// today yearly PRIBOR rate
$rates = $cnb->getPriborRate($date = null, $interval = 'year');
// or shortcuts
$rates = $cnb->getPriborRateForYear('12.1.2016');
$rates = $cnb->getPriborRateFor9Months('12.1.2016');
$rates = $cnb->getPriborRateFor6Months('12.1.2016');
$rates = $cnb->getPriborRateFor3Months('12.1.2016');
$rates = $cnb->getPriborRateFor2Months('12.1.2016');
$rates = $cnb->getPriborRateForMonth('12.1.2016');
$rates = $cnb->getPriborRateFor2Weeks('12.1.2016');
$rates = $cnb->getPriborRateForWeek('12.1.2016');
$rates = $cnb->getPriborRateForDay('12.1.2016');

Callable service used for CRON call

Download daily exchange rates, save it to cache and fires vojtasvoboda.cnbrates.exchange.updated event. This method is prepared for using by CRON.

$cnb = App::make('cnb');
$cnb->updateTodayExchangeRates();

Testing

Run phpunit command in plugin directory. All test must pass.

Future plans

Feel free to send pullrequest!

• implement other ČNB services
• add button 'Update rates now'

License

ČNB Rates plugin is open-sourced software licensed under the MIT license same as OctoberCMS platform.

Contributing

Please send Pull Request to master branch.