tal7aouy/currency

A PHP library for current and historical currency exchange rates & crypto exchange rates.

v1.0.0 2022-05-24 19:29 UTC

Requires

• php: >=7.2
• ext-json: *
• guzzlehttp/guzzle: >=6.0

Requires (Dev)

• phpunit/phpunit: >=8.5.23

MIT

• Mhammed Talhaouy

• php
• currency
• currency converter
• exchange rates
• crypto exchange rates
• php currency

README

Currency is a simple PHP library for current and historical currency exchange rates & crypto exchange rates. based on the free API exchangerate.host - no API keys needed!

Requirements

• PHP >= 7.2
• guzzlehttp >= 6.0

Installation

composer require tal7aouy/currency

Usage

1. Currency Conversion

To convert from one currency to another you may chain the methods:

require 'vendor/autoload.php';

use Tal7aouy\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 Tal7aouy\Currency;

Currency::convert()
        ->from('USD')
        ->to('EUR')
        ->amount(50)
        ->get();

Available Methods

• Convert currency using historical exchange rates YYYY-MM-DD:

use Tal7aouy\Currency;

Currency::convert()
        ->from('USD')
        ->to('EUR')
        ->date('2019-08-01')
        ->get();

• Round the converted amount to decimal places:

use Tal7aouy\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 Tal7aouy\Currency;

Currency::convert()
        ->from('BTC')
        ->to('ETH')
        ->source('crypto')
        ->get();

2. Latest Rates

To get latest rates you may chain the methods:

use Tal7aouy\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 Tal7aouy\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 Tal7aouy\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 Tal7aouy\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 Tal7aouy\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 Tal7aouy\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 Tal7aouy\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 Tal7aouy\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 Tal7aouy\Currency;

Currency::convert()
        ->from('USD')
        ->to('EUR')
        ->withoutVerifying()
        ->get();

• You may specify additional Guzzle request options using the withOptions method. The withOptions method accepts an array of key / value pairs:

use Tal7aouy\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 Tal7aouy\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();

License

LICENSE (MIT) for more information.