amoori/laravel-exchange-rates

A wrapper package for interacting with the exchangeratesapi.io API.

dev-master 2023-02-21 16:37 UTC

Requires

• php: ^7.2|^8.0
• ext-json: *
• guzzlehttp/guzzle: ^6.3|^7.0
• illuminate/cache: ^5.8|^6.0|^7.0|^8.0|^9.0|^10.0
• illuminate/container: ^5.8|^6.0|^7.0|^8.0|^9.0|^10.0
• nesbot/carbon: ~2.0

Requires (Dev)

• mockery/mockery: ^1.0
• orchestra/testbench: ^3.8 || ^4.0
• phpunit/phpunit: ^8.2

MIT

• Ash Allen

• exchange-rate
• exchangeratesapi.io
• laravel-exchange-rates
• amoori

README

Table of Contents

• Overview
• Installation
• Usage
  • Methods
    • Available Currencies
    • Exchange Rate
    • Exchange Rates Between Date Range
    • Convert Currencies
    • Convert Currencies Between Date Range
  • Facade
  • Examples
  • Caching
  • Supported Currencies
• Testing
• Security
• Contribution
• Credits
• Changelog
• Upgrading
• License

Overview

A simple Laravel package used for interacting with the exchangeratesapi.io API. 'Laravel Exchange Rates' allow you to get the latest or historical exchange rates and convert monetary values between different currencies.

Installation

You can install the package via Composer:

composer require amoori/laravel-exchange-rates

The package has been developed and tested to work with the following minimum requirements:

• PHP 7.2
• Laravel 5.8

Usage

Methods

Available Currencies

$exchangeRates = new ExchangeRate();
$exchangeRates->currencies();

Exchange Rate

<?php
$exchangeRates = new ExchangeRate();
$exchangeRates->exchangeRate('GBP', 'EUR');

Note: If a Carbon date is passed as the third parameter, the exchange rate for that day will be returned (if valid). If no date is passed, today's exchange rate will be used.

Exchange Rates Between Date Range

$exchangeRates = new ExchangeRate();
$exchangeRates->exchangeRateBetweenDateRange('GBP', 'EUR', Carbon::now()->subWeek(), Carbon::now());

Convert Currencies

When passing in the monetary value (first parameter) that is to be converted, it's important that you pass it in the lowest denomination of that currency. For example, £1 GBP would be passed in as 100 (as £1 = 100 pence).

$exchangeRates = new ExchangeRate();
$exchangeRates->convert(100, 'GBP', 'EUR', Carbon::now());

Note: If a Carbon date is passed as the third parameter, the exchange rate for that day will be returned (if valid). If no date is passed, today's exchange rate will be used.

Convert Currencies Between Date Range

When passing in the monetary value (first parameter) that is to be converted, it's important that you pass it in the lowest denomination of that currency. For example, £1 GBP would be passed in as 100 (as £1 = 100 pence).

$exchangeRates = new ExchangeRate();
$exchangeRates->convert(100, 'GBP', 'EUR', Carbon::now()->subWeek(), Carbon::now());

Facade

If you prefer to use facades in Laravel, you can choose to use the provided ExchangeRate facade instead of instantiating the amoori\LaravelExchangeRates\Classes\ExchangeRate class manually.

The example below shows an example of how you could use the facade to get the available currencies:

<?php
    
    namespace App\Http\Controllers;
    
    use ExchangeRate;
    
    class TestController extends Controller
    {
        public function index()
        {
            return ExchangeRate::currencies();
        }
    }

Examples

This example shows how to convert 100 pence (£1) from Great British Pounds to Euros. The current exchange rate will be used (unless a cached rate for this date already exists).

<?php
    
    namespace App\Http\Controllers;
    
    use amoori\LaravelExchangeRates\Classes\ExchangeRate;
    
    class TestController extends Controller
    {
        public function index()
        {
            $exchangeRates = new ExchangeRate();
            return $exchangeRates->convert(100, 'GBP', 'EUR', Carbon::now());
        }
    }

Caching

By default, the responses all of the requests to the exchangeratesapi.io API are cached. This allows for significant performance improvements and reduced bandwidth from your server.

However, if for any reason you require a fresh result from the API and not a cached result, the ->shouldBustCache() method can be used. The example below shows how to ignore the cached value (if one exists) and make a new API request.

<?php
    
    namespace App\Http\Controllers;
    
    use amoori\LaravelExchangeRates\Classes\ExchangeRate;
    
    class TestController extends Controller
    {
        public function index()
        {
            $exchangeRates = new ExchangeRate();
            return $exchangeRates->shouldBustCache()->convert(100, 'GBP', 'EUR', Carbon::now());
        }
    }

Note: The caching works by storing exchange rates after fetching them from the API. As an example, if you were to fetch the exchange rates for 'GBP' to 'EUR' for 20-11-2019 - 27-11-2019, the rates between these dates will be cached as a single cache item. This cache item will only be retrieved if you attempt to fetch the same exchange rates on with the exact same currencies and date range.

Therefore, if you were to try and get 'GBP' to 'EUR' for 20-11-2019 - 26-11-2019, a new API request would be made because the date range is different.

Supported Currencies

Laravel Exchange Rates supports working with the following currencies (sorted in A-Z order):

Note: Please note that the currencies are available because they are exposed in the exchangeratesapi.io API.

Testing

vendor/bin/phpunit

Security

If you find any security related issues, please contact me directly at [e-mail] to report it.

Contribution

If you wish to make any changes or improvements to the package, feel free to make a pull request.

Note: A contribution guide will be added soon.

Credits

• Ash Allen
• Jess Pickup (Logo)
• All Contributors

Changelog

Check the CHANGELOG to get more information about the latest changes.

Upgrading

Check the UPGRADE guide to get more information on how to update this library to newer versions.

License

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