Timeseries rates

Author: amrshawky

README.md

@@ -1,22 +1,24 @@
 # Laravel Currency
 ![Tests](https://github.com/amrshawky/laravel-currency/workflows/Tests/badge.svg?branch=master) ![Packagist License](https://img.shields.io/packagist/l/amrshawky/laravel-currency?color=success&label=License) ![Packagist Version](https://img.shields.io/packagist/v/amrshawky/laravel-currency?label=Packagist) ![Packagist Downloads](https://img.shields.io/packagist/dt/amrshawky/laravel-currency?color=success&label=Downloads)
 
-Laravel currency is a simple package for currency conversion, latest and historical exchange rates based on the free API [exchangerate.host](https://exchangerate.host "exchangerate.host Homepage") - no API keys needed!
+Laravel currency is a simple package for current and historical currency exchange rates & crypto exchange rates. based on the free API [exchangerate.host](https://exchangerate.host "exchangerate.host Homepage") - no API keys needed!
 
 ## Requirements
 - PHP >= 7.2
 - Laravel >= 6.0
 - guzzlehttp >= 6.0
 
 ## Installation
+
 ```
 composer require amrshawky/laravel-currency
 ```
 
 ## Usage
 
 ### 1. Currency Conversion
-To convert from one currency to another you may chain the methods like so: 
+To convert from one currency to another you may chain the methods:
+
 ```php
 use AmrShawky\Currency\Facade\Currency;
 
@@ -77,6 +79,7 @@ Currency::convert()
 
 ### 2. Latest Rates
 To get latest rates you may chain the methods: 
+
 ```php
 use AmrShawky\Currency\Facade\Currency;
 
@@ -88,6 +91,7 @@ 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:
+
 ```php
 use AmrShawky\Currency\Facade\Currency;
 
@@ -97,17 +101,18 @@ Currency::rates()
         ->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` or bank view
+        ->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.
+
 ```php
 use AmrShawky\Currency\Facade\Currency;
 
 Currency::rates()
-        ->historical('2020-01-01') // `YYYY-MM-DD` Required date parameter to get the rates for
+        ->historical('2020-01-01') //`YYYY-MM-DD` Required date parameter to get the rates for
         ->get();
 ```
 Same as latest rates you may chain any of the available methods: 
@@ -116,13 +121,30 @@ use AmrShawky\Currency\Facade\Currency;
 
 Currency::rates()
         ->historical('2020-01-01')
-        ->symbols(['USD', 'EUR', 'EGP'])
+        ->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` with keys as dates and values as an `array` of rates or `null` on failure.
+
+```php
+use AmrShawky\Currency\Facade\Currency;
+
+Currency::rates()
+        ->timeSeries('2021-05-01', '2021-05-04') //`YYYY-MM-DD` Required dates range parameters
+        ->symbols(['USD', 'EUR', 'EGP']) //[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();
+```
+
 ### 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.)_.
 
@@ -203,8 +225,5 @@ More information regarding list of bank sources [here](https://api.exchangerate.
 
 For a list of all supported symbols [here](https://api.exchangerate.host/symbols "List of supported symbols")
 
-## More features
-Coming soon!
-
 ## License
 The MIT License (MIT). Please see [LICENSE](../master/LICENSE) for more information.

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "amrshawky/laravel-currency",
-    "description": "A Laravel package for currency conversion, latest and historical exchange rates based on the free API provided by exchangerate.host",
+    "description": "A Laravel package for current and historical currency exchange rates & crypto exchange rates based on the free API provided by exchangerate.host",
     "keywords": [
         "laravel",
         "currency",

docs/index.md

@@ -1,22 +1,24 @@
 # Laravel Currency
 ![Tests](https://github.com/amrshawky/laravel-currency/workflows/Tests/badge.svg?branch=master) ![Packagist License](https://img.shields.io/packagist/l/amrshawky/laravel-currency?color=success&label=License) ![Packagist Version](https://img.shields.io/packagist/v/amrshawky/laravel-currency?label=Packagist) ![Packagist Downloads](https://img.shields.io/packagist/dt/amrshawky/laravel-currency?color=success&label=Downloads)
 
-Laravel currency is a simple package for currency conversion, latest and historical exchange rates based on the free API [exchangerate.host](https://exchangerate.host "exchangerate.host Homepage") - no API keys needed!
+Laravel currency is a simple package for current and historical currency exchange rates & crypto exchange rates. based on the free API [exchangerate.host](https://exchangerate.host "exchangerate.host Homepage") - no API keys needed!
 
 ## Requirements
 - PHP >= 7.2
 - Laravel >= 6.0
 - guzzlehttp >= 6.0
 
 ## Installation
+
 ```
 composer require amrshawky/laravel-currency
 ```
 
 ## Usage
 
 ### 1. Currency Conversion
-To convert from one currency to another you may chain the methods like so:
+To convert from one currency to another you may chain the methods:
+
 ```php
 use AmrShawky\Currency\Facade\Currency;
 
@@ -85,7 +87,6 @@ Currency::rates()
         ->latest()
         ->get();
 ```
-
 This will return an `array` of all available currencies or `null` on failure.
 
 #### Available Methods
@@ -100,7 +101,7 @@ Currency::rates()
         ->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` or bank view
+        ->source('ecb') //Switch data source between forex `default`, bank view or crypto currencies.
         ->get();
 ```
 
@@ -111,23 +112,39 @@ Historical rates are available for most currencies all the way back to the year
 use AmrShawky\Currency\Facade\Currency;
 
 Currency::rates()
-        ->historical('2020-01-01') // `YYYY-MM-DD` Required date parameter to get the rates for
+        ->historical('2020-01-01') //`YYYY-MM-DD` Required date parameter to get the rates for
         ->get();
 ```
 Same as latest rates you may chain any of the available methods:
-
 ```php
 use AmrShawky\Currency\Facade\Currency;
 
 Currency::rates()
         ->historical('2020-01-01')
-        ->symbols(['USD', 'EUR', 'EGP'])
+        ->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` with keys as dates and values as an `array` of rates or `null` on failure.
+
+```php
+use AmrShawky\Currency\Facade\Currency;
+
+Currency::rates()
+        ->timeSeries('2021-05-01', '2021-05-04') //`YYYY-MM-DD` Required dates range parameters
+        ->symbols(['USD', 'EUR', 'EGP']) //[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();
+```
+
 ### 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.)_.
 
@@ -208,8 +225,5 @@ More information regarding list of bank sources [here](https://api.exchangerate.
 
 For a list of all supported symbols [here](https://api.exchangerate.host/symbols "List of supported symbols")
 
-## More features
-Coming soon!
-
 ## License
 The MIT License (MIT). Please see [LICENSE](../master/LICENSE) for more information.

src/CurrencyRates.php

@@ -98,8 +98,10 @@ public function round(int $places)
      */
     protected function getResults(object $response)
     {
-        if (!empty($response->rates)) {
-            return (array) $response->rates;
+        if (!empty($rates = (array) $response->rates)) {
+            unset($response->rates);
+
+            return $rates;
         }
 
         return null;

src/CurrencyRatesProxy.php

@@ -21,4 +21,15 @@ public function historical(string $date)
     {
         return new CurrencyHistoricalRates($date);
     }
+
+    /**
+     * @param string $date_from
+     * @param string $date_to
+     *
+     * @return CurrencyTimeSeriesRates
+     */
+    public function timeSeries(string $date_from, string $date_to)
+    {
+        return new CurrencyTimeSeriesRates($date_from, $date_to);
+    }
 }

src/CurrencyTimeSeriesRates.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace AmrShawky\Currency;
+
+use GuzzleHttp\Client;
+
+class CurrencyTimeSeriesRates extends CurrencyRates
+{
+    /**
+     * CurrencyHistoricalRates constructor.
+     *
+     * @param string      $start_date
+     * @param string      $end_date
+     * @param Client|null $client
+     */
+    public function __construct(string $start_date, string $end_date, ?Client $client = null)
+    {
+        parent::__construct($client);
+        $this->base_url = "https://api.exchangerate.host/timeseries";
+        $this->params['start_date'] = $start_date;
+        $this->params['end_date']   = $end_date;
+    }
+
+    /**
+     * @param object $response
+     *
+     * @return mixed|null
+     */
+    protected function getResults(object $response)
+    {
+        if (!empty($time_series = (array) $response->rates)) {
+            foreach ($time_series as $date => $rates) {
+                $time_series[$date] = (array) $rates;
+            }
+            unset($response->rates);
+
+            return $time_series;
+        }
+
+        return null;
+    }
+}