Init

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+ko_fi: amrshawky

.github/workflows/tests.yml

@@ -0,0 +1,38 @@
+name: "Tests"
+
+on: [push]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        php: [7.2, 7.3, 7.4, 8.0]
+        dependency-version: [prefer-lowest, prefer-stable]
+
+    name: P${{ matrix.php }} - ${{ matrix.dependency-version }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v1
+
+      - name: Cache dependencies
+        uses: actions/cache@v1
+        with:
+          path: ~/.composer/cache/files
+          key: dependencies-php-${{ matrix.php }}-composer-${{ hashFiles('composer.json') }}
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v1
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick
+          coverage: none
+
+      - name: Install dependencies
+        run: composer update --${{ matrix.dependency-version }} --prefer-dist --no-interaction --no-suggest
+
+      - name: Execute tests
+        run: vendor/bin/phpunit

.gitignore

@@ -0,0 +1,6 @@
+/vendor
+composer.phar
+composer.lock
+.DS_Store
+.idea
+.phpunit.result.cache

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Amr Shawky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,285 @@
+# Currency
+![Tests](https://github.com/amrshawky/currency/workflows/Tests/badge.svg?branch=master) ![Packagist License](https://img.shields.io/packagist/l/amrshawky/currency?color=success&label=License) ![Packagist Version](https://img.shields.io/packagist/v/amrshawky/currency?label=Packagist) ![Packagist Downloads](https://img.shields.io/packagist/dt/amrshawky/currency?color=success&label=Downloads)
+
+Currency is a simple PHP library 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
+- guzzlehttp >= 6.0
+
+## Installation
+
+```
+composer require amrshawky/currency
+```
+
+## Usage
+
+### 1. Currency Conversion
+To convert from one currency to another you may chain the methods:
+
+```php
+require 'vendor/autoload.php';
+
+use AmrShawky\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:
+
+```php
+use AmrShawky\Currency;
+
+Currency::convert()
+        ->from('USD')
+        ->to('EUR')
+        ->amount(50)
+        ->get();
+```
+#### Available Methods
+- Convert currency using historical exchange rates `YYYY-MM-DD`:
+
+```php
+use AmrShawky\Currency;
+
+Currency::convert()
+        ->from('USD')
+        ->to('EUR')
+        ->date('2019-08-01')
+        ->get();
+```
+
+- Round the converted amount to decimal places:
+
+```php
+use AmrShawky\Currency;
+
+Currency::convert()
+        ->from('USD')
+        ->to('EUR')
+        ->round(2)
+        ->get();
+```
+
+- You may also switch data source between forex `default`, bank view or crypto currencies:
+
+```php
+use AmrShawky\Currency;
+
+Currency::convert()
+        ->from('BTC')
+        ->to('ETH')
+        ->source('crypto')
+        ->get();
+```
+
+### 2. Latest Rates
+To get latest rates you may chain the methods:
+
+```php
+use AmrShawky\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:
+
+```php
+use AmrShawky\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.
+
+```php
+use AmrShawky\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:
+
+```php
+use AmrShawky\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.
+
+```php
+use AmrShawky\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.
+
+```php
+use AmrShawky\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:
+
+```php
+use AmrShawky\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:
+
+```php
+use AmrShawky\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:
+
+```php
+use AmrShawky\Currency;
+
+Currency::convert()
+        ->from('USD')
+        ->to('EUR')
+        ->withoutVerifying()
+        ->get();
+```
+
+- You may specify additional [Guzzle request options](https://docs.guzzlephp.org/en/stable/request-options.html "Guzzle request options") using the `withOptions` method. The `withOptions` method accepts an array of key / value pairs:
+
+```php
+use AmrShawky\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:
+
+```php
+use AmrShawky\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
+The MIT License (MIT). Please see [LICENSE](../master/LICENSE) for more information.