README

Simple PHP client for currencylayer.com currency rates.

Installation

You can install the package via composer:

composer require orkhanahmadov/currencylayer

Usage

Instantiate Orkhanahmadov\Currencylayer\CurrencylayerClient class and pass your "access key"

use Orkhanahmadov\Currencylayer\CurrencylayerClient;

$client = new CurrencylayerClient('your-access-key-here');

You can find your access key in Currencylayer Dashboard.

If you are using paid plan, you can use HTTPS connection to currencylayer.com API. While instantiating pass true as second parameter to use HTTPS connection.

$client = new CurrencylayerClient('your-access-key-here', true);

Available methods

`quotes()`

Use this method to fetch live and historical currency rates.

Pass source currency to source() method and rate currency currency() method. Following example will fetch live rates from USD to EUR.

$client->source('USD')->currency('EUR')->quotes();

You can also pass multiple rate currencies to currency() method:

$client->source('USD')->currency('EUR', 'AUD')->quotes();
// you can also pass currencies as an array
$client->source('USD')->currency(['EUR', 'AUD'])->quotes();

If you want fetch rates for specific date, you can pass the date to date() method. date() method accepts dates as string or instance of DateTimeInterface.

$client->source('USD')->currency('EUR')->date('2019-05-20')->quotes();

quotes() method returns instance of Orkhanahmadov\Currencylayer\Data\Quotes. This class has following methods that you can use:

source() - Returns source currency (for example, USD)
timestamp() - Returns timestamp value from currencylayer API (for example, 1432400348)
quotes() - Returns array of quotes from currencylayer API
date() - Returns DateTimeInterface date. If you fetched live rates this method will return null

You can also get rates for each fetched currency using currency name as property:

$quotes = $client->source('USD')->currency(['EUR', 'AUD'])->date('2019-05-20')->quotes();

$qoutes->EUR; // returns USD to EUR rate for 2019-05-20
$qoutes->AUD; // returns USD to AUD rate for 2019-05-20

`convert()`

Use this method to convert amount in one currency to another currency.

Pass source currency to source() method, rate currency currency() method and amount to convert() method. Following example will convert 10 USD to GBP using live rates.

$client->source('USD')->currency('GBP')->convert(10);

If you want conversion based on different date's rates, you can pass the date to date() method. date() method accepts dates as string or instance of DateTimeInterface.

$client->source('USD')->currency('GBP')->date('2019-05-20')->convert(10);

convert() method returns instance of Orkhanahmadov\Currencylayer\Data\Conversion. This class has following methods that you can use:

fromCurrency() - Returns source currency (for example, USD)
toCurrency() - Returns target currency (for example, GBP)
timestamp() - Returns timestamp value from currencylayer API (for example, 1432400348)
amount() - Returns amount that passed to convert() method (for example, 10)
quote() - Returns quote between source and target currencies (for example, 0.658443)
result() - Returns conversion result (for example 6.58443)
date() - Returns DateTimeInterface date. If you fetched live rates this method will return null

`timeframe()`

Use this method to show rates between given dates.

Pass source currency to source() method, rate currencies to currency() method and start date as first argument and end date as second argument to timeframe() method. Start and end dates can be string of dates or instances of DateTimeInterface.

Following example will return timeframe rates from USD to GBP and EUR between 2010-03-01 and 2010-04-01.

$client->source('USD')->currency('GBP', 'EUR')->timeframe('2010-03-01', '2010-04-01');

timeframe() method returns instance of Orkhanahmadov\Currencylayer\Data\Timeframe. This class has following methods that you can use:

source() - Returns source currency (for example, USD)
startDate() - Returns DateTimeInterface start date
endDate() - Returns DateTimeInterface start date
allQuotes() - Returns array quotes grouped by each day between start and end date
quotes() - Accepts string date or instance of DateTimeInterface and returns rates for that day

You can also use currency code as function call and pass date to get rates:

$timeframe = $client->source('USD')->currency('GBP', 'EUR')->timeframe('2010-03-01', '2010-04-01');

$timeframe->GBP('2010-03-15'); // returns USD to GBP rate for 2010-03-15
$timeframe->EUR('2010-03-20'); // returns USD to EUR rate for 2010-03-20

`change()`

Use this method to show currency rate change between given dates.

Pass source currency to source() method, rate currencies to currency() method and start date as first argument and end date as second argument to change() method. Start and end dates can be string of dates or instances of DateTimeInterface.

Following example will return rate change from USD to GBP and EUR between 2010-03-01 and 2010-04-01.

$client->source('USD')->currency('GBP', 'EUR')->change('2010-03-01', '2010-04-01');

change() method returns instance of Orkhanahmadov\Currencylayer\Data\Change. This class has following methods that you can use:

source() - Returns source currency (for example, USD)
startDate() - Returns DateTimeInterface start date
endDate() - Returns DateTimeInterface start date
quotes() - Returns array of currency change rates between start and end date
rate() - Accepts currency code as an argument and returns currency rate for given start date
endRate() - Accepts currency code as an argument and returns currency rate for given end date
amount() - Accepts currency code as an argument and currency rate's change in amount
percentage() - Accepts currency code as an argument and currency rate's change in percentage

`list()`

Use this method to get list of all available currencies.

$client->list();

Method will return array of currencies in currencyCode => currencyName structure.

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email ahmadov90@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

orkhanahmadov / currencylayer

Maintainers

Details