yzh52521 / think-currency
A thinkphp package for current and historical currency exchange rates & crypto exchange rates based on the free API provided by exchangerate.host
Requires
- php: >=7.2
- ext-json: *
- amrshawky/currency: ^1.0
- guzzlehttp/guzzle: >=6.0
README
Laravel currency is a simple package for current and historical currency exchange rates & crypto exchange rates. based on the free API exchangerate.host - no API keys needed!
Note: This package is an integration for the Currency library
Requirements
- PHP >= 7.2
- ThinkPHP >= 6.0
- guzzlehttp >= 6.0
Installation
composer require yzh52521/think-currency
Usage
1. Currency Conversion
To convert from one currency to another you may chain the methods:
use yzh52521\ThinkCurrency\facade\Currency; Currency::convert() ->from('USD') ->to('EUR') ->get();
This will return the converted amount or null
on failure.
The amount to be converted is default to 1
, you may specify the amount:
use yzh52521\ThinkCurrency\facade\Currency; Currency::convert() ->from('USD') ->to('EUR') ->amount(50) ->get();
Available Methods
- Convert currency using historical exchange rates
YYYY-MM-DD
:
use yzh52521\ThinkCurrency\facade\Currency; Currency::convert() ->from('USD') ->to('EUR') ->date('2019-08-01') ->get();
- Round the converted amount to decimal places:
use yzh52521\ThinkCurrency\facade\Currency; Currency::convert() ->from('USD') ->to('EUR') ->round(2) ->get();
- You may also switch data source between forex
default
, bank view or crypto currencies:
use yzh52521\ThinkCurrency\facade\Currency; Currency::convert() ->from('BTC') ->to('ETH') ->source('crypto') ->get();
2. Latest Rates
To get latest rates you may chain the methods:
use yzh52521\ThinkCurrency\facade\Currency; Currency::rates() ->latest() ->get(); // ['USD' => 1.215707, ...] Currency::rates() ->latest() ->source('crypto') ->get(); // ['ETH' => 3398.61, ...]
This will return an array
of all available currencies or null
on failure.
Available Methods
- Just like currency conversion you may chain any of the available methods:
use yzh52521\ThinkCurrency\facade\Currency; Currency::rates() ->latest() ->symbols(['USD', 'EUR', 'EGP']) //An array of currency codes to limit output currencies ->base('GBP') //Changing base currency (default: EUR). Enter the three-letter currency code of your preferred base currency. ->amount(5.66) //Specify the amount to be converted ->round(2) //Round numbers to decimal places ->source('ecb') //Switch data source between forex `default`, bank view or crypto currencies. ->get();
3. Historical Rates
Historical rates are available for most currencies all the way back to the year of 1999.
use yzh52521\ThinkCurrency\facade\Currency; Currency::rates() ->historical('2020-01-01') //`YYYY-MM-DD` Required date parameter to get the rates for ->get(); // ['USD' => 1.1185, ...] Currency::rates() ->historical('2021-03-30') ->source('crypto') ->get(); // ['BTC' => 2.0E-5, ...]
Same as latest rates you may chain any of the available methods:
use yzh52521\ThinkCurrency\facade\Currency; Currency::rates() ->historical('2020-01-01') ->symbols(['USD', 'EUR', 'CZK']) ->base('GBP') ->amount(5.66) ->round(2) ->source('ecb') ->get();
4. Timeseries Rates
Timeseries are for daily historical rates between two dates of your choice, with a maximum time frame of 365 days.
This will return an array
or null
on failure.
use yzh52521\ThinkCurrency\facade\Currency; Currency::rates() ->timeSeries('2021-05-01', '2021-05-02') //`YYYY-MM-DD` Required dates range parameters ->symbols(['USD']) //[optional] An array of currency codes to limit output currencies ->base('GBP') //[optional] Changing base currency (default: EUR). Enter the three-letter currency code of your preferred base currency. ->amount(5.66) //[optional] Specify the amount to be converted (default: 1) ->round(2) //[optional] Round numbers to decimal places ->source('ecb') //[optional] Switch data source between forex `default`, bank view or crypto currencies. ->get(); /** [ '2021-05-01' => [ "USD" => 1.201995 ], '2021-05-02' => [ "USD" => 1.2027 ] ] */
5. Fluctuations
Retrieve information about how currencies fluctuate on a day-to-day basis, with a maximum time frame of 365 days.
This will return an array
or null
on failure.
use yzh52521\ThinkCurrency\facade\Currency; Currency::rates() ->fluctuations('2021-03-29', '2021-04-15') //`YYYY-MM-DD` Required dates range parameters ->symbols(['USD']) //[optional] An array of currency codes to limit output currencies ->base('GBP') //[optional] Changing base currency (default: EUR). Enter the three-letter currency code of your preferred base currency. ->amount(5.66) //[optional] Specify the amount to be converted (default: 1) ->round(2) //[optional] Round numbers to decimal places ->source('ecb') //[optional] Switch data source between forex `default`, bank view or crypto currencies. ->get(); /** [ 'USD' => [ "start_rate" => 1.376454, "end_rate" => 1.37816, "change" => -0.001706, "change_pct" => -0.001239 ] ] */
Throwing Exceptions
The default behavior is to return null
for errors that occur during the request (connection timeout, DNS errors, client or server error status code, missing API success parameter, etc.).
If you would like to throw an exception instead, you may use the throw
method, The throw
method returns the currency instance, allowing you to chain other methods:
use yzh52521\ThinkCurrency\facade\Currency; Currency::convert() ->from('USD') ->to('EUR') ->amount(20) ->throw() ->get();
If you would like to perform some additional logic before the exception is thrown, you may pass a closure to the throw method:
use yzh52521\ThinkCurrency\facade\Currency; Currency::convert() ->from('USD') ->to('EUR') ->amount(20) ->throw(function ($response, $e) { // }) ->get();
Other Methods
- You may use the
withoutVerifying
method to indicate that TLS certificates should not be verified when sending the request:
use yzh52521\ThinkCurrency\facade\Currency; Currency::convert() ->from('USD') ->to('EUR') ->withoutVerifying() ->get();
- You may specify additional Guzzle request options using the
withOptions
method. ThewithOptions
method accepts an array of key / value pairs:
use yzh52521\ThinkCurrency\facade\Currency; Currency::rates() ->historical('2021-04-30') ->withOptions([ 'debug' => true, 'timeout' => 3.0 ]) ->get();
- The
when
method will execute the given callback when the first argument given to the method evaluates to true:
use yzh52521\ThinkCurrency\facade\Currency; Currency::rates() ->latest() ->when(true, function ($rates) { // will execute $rates->symbols(['USD', 'EUR', 'EGP']) ->base('GBP'); }) ->when(false, function ($rates) { // won't execute $rates->symbols(['HKD']); }) ->get();
Testing
Currency uses Laravel facades which makes it easy to mock so it's not actually executed during the test:
use yzh52521\ThinkCurrency\facade\Currency; Currency::shouldReceive('convert') ->once() ->andReturn(1.50); Currency::shouldReceive('rates') ->once() ->andReturn(['EUR' => 1,'USD' => 1.215707]);
More information regarding list of bank sources here
For a list of all supported symbols here and list of crypto currencies here
License
The MIT License (MIT). Please see LICENSE for more information.