Skip to content

Commit bd42af8

Browse files
committed
Fix Markdown, add .mdlrc
1 parent 0c3feac commit bd42af8

File tree

2 files changed

+29
-10
lines changed

2 files changed

+29
-10
lines changed

.mdlrc

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
rule 'MD013', :line_length => 160, :code_blocks => false, :tables => false

README.md

+28-10
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
# 💱 PHP Currency Exchange Rate API
2+
23
_A PHP 7 API Wrapper for Popular Currency Rate APIs._
34

45
[![Version](https://img.shields.io/packagist/v/otherguy/php-currency-api.svg?style=flat-square)](https://packagist.org/packages/otherguy/php-currency-api)
@@ -12,17 +13,20 @@ _A PHP 7 API Wrapper for Popular Currency Rate APIs._
1213
Dont worry about your favorite currency conversion service suddenly shutting down or switching plans on you. Switch away easily.
1314

1415
## Inspiration 💅
16+
1517
I needed a currency conversion API for [my travel website]() but could not find a good PHP package. The idea of the
1618
[`Rackbeat/php-currency-api`](https://github.com/Rackbeat/php-currency-api) package came closest but unfortunately it
1719
was just a stub and not implemented.
1820

1921
## Features 🌈
22+
2023
* Support for [multiple different APIs](#supported-apis-) through the use of drivers
2124
* A [fluent interface](#fluent-interface) to make retrieving exchange rates convenient and fast
2225
* Consistent return interface that is independent of the driver being used
2326
* [Calculations](#conversion-result) can be made based on the returned data
2427

2528
## Supported APIs 🌐
29+
2630
| Service | Identifier |
2731
|------------------------------------------------------|---------------------|
2832
| [FixerIO](https://fixer.io) | `fixerio` |
@@ -33,11 +37,13 @@ was just a stub and not implemented.
3337
_If you want to see more services added, feel free to [open an issue](https://github.com/otherguy/php-currency-api/issues)!_
3438

3539
## Prerequisites 📚
40+
3641
* `PHP 7.1` or higher (Tested on: PHP `7.1` ✅, `7.2` ✅ and `7.3` ✅)
3742
* The [`composer`](https://getcomposer.org) dependency manager for PHP
3843
* An account with one or more of the [API providers](#supported-apis-) listed above
3944

4045
## Installation 🚀
46+
4147
Simply require the package using `composer` and you're good to go!
4248

4349
```bash
@@ -47,6 +53,7 @@ $ composer require otherguy/php-currency-api
4753
## Usage 🛠
4854

4955
### Currency Symbol Helper
56+
5057
The [`Otherguy\Currency\Symbol`](src/Symbol.php) class provides constants for each supported currency.
5158

5259
> **Note:** You are not required to use `Otherguy\Currency\Symbol` to specify symbols. It's simply a convenience helper
@@ -68,17 +75,18 @@ The `names()` method returns an associative array with currency names instead:
6875

6976
```php
7077
// [ 'AED' => 'United Arab Emirates Dirham', 'AFN' => 'Afghan Afghani', ... ]
71-
$symbols = Otherguy\Currency\Symbol::names();
78+
$symbols = Otherguy\Currency\Symbol::names();
7279
```
7380

7481
To get the name of a single currency, use the `name()` method:
7582

7683
```php
7784
// 'United States Dollar'
78-
$symbols = Otherguy\Currency\Symbol::name(Otherguy\Currency\Symbol::USD);
85+
$symbols = Otherguy\Currency\Symbol::name(Otherguy\Currency\Symbol::USD);
7986
```
8087

8188
### Initialize API Instance
89+
8290
```php
8391
$currency = Otherguy\Currency\DriverFactory::make('fixerio'); // driver identifier from supported drivers.
8492
```
@@ -91,6 +99,7 @@ $drivers = Otherguy\Currency\DriverFactory::getDrivers()
9199
```
92100

93101
### Set Access Key
102+
94103
Most API providers require you to sign up and use your issued access key to authenticate against their API. You can
95104
specify your access key like so:
96105

@@ -99,6 +108,7 @@ $currency->accessKey('your-access-token-goes-here');
99108
```
100109

101110
### Set Configuration Options
111+
102112
To set further configuration options, you can use the `config()` method. An example is
103113
[CurrencyLayer's JSON formatting option](https://currencylayer.com/documentation#format).
104114

@@ -107,12 +117,13 @@ $currency->config('format', '1');
107117
```
108118

109119
### Set Base Currency
120+
110121
You can use either `from()` or `source()` to set the base currency. The methods are identical.
111122

112123
> **Note:** Each driver sets its own default base currency. [FixerIO](https://fixer.io) uses `EUR` as base currency
113124
> while [CurrencyLayer](https://currencylayer.com) uses `USD`.
114125
115-
Most services only allow you to change the base currency in their paid plans. The driver will throw a
126+
Most services only allow you to change the base currency in their paid plans. The driver will throw a
116127
`Otherguy\Currency\Exceptions\ApiException` if your current plan does not allow changing the base currency.
117128

118129
```php
@@ -121,18 +132,20 @@ $currency->from(Otherguy\Currency\Symbol::USD);
121132
```
122133

123134
### Set Return Currencies
135+
124136
You can use either `to()` or `symbols()` to set the return currencies. The methods are identical. Pass a single currency
125-
or an array of currency symbols to either of these methods.
137+
or an array of currency symbols to either of these methods.
126138

127139
> **Note:** Pass an empty array to return all currency symbols supported by this driver. This is the default if you
128-
> don't call the method at all.
140+
> don't call the method at all.
129141
130142
```php
131143
$currency->to(Otherguy\Currency\Symbol::BTC);
132144
$currency->symbols([Otherguy\Currency\Symbol::BTC, Otherguy\Currency\Symbol::EUR, Otherguy\Currency\Symbol::USD]);
133145
```
134146

135147
### Latest Rates
148+
136149
This retrieves the most recent exchange rates and returns a [`ConversionResult`](#conversion-result) object.
137150

138151
```php
@@ -141,6 +154,7 @@ $currency->get('DKK'); // Get latest rates for selected symbols, using DKK as b
141154
```
142155

143156
### Historical Rates
157+
144158
To retrieve historical exchange rates, use the `historical()` method. Note that you need to specify a date either as a
145159
method parameter or by using the `date()` methods. See [Fluent Interface](#fluent-interface) for more information.
146160

@@ -150,6 +164,7 @@ $currency->historical('2018-07-01');
150164
```
151165

152166
### Convert Amount
167+
153168
Use the `convert()` method to convert amounts between currencies.
154169

155170
> **Note:** Most API providers don't allow access to this method using your free account. You can still use the
@@ -162,25 +177,27 @@ $currency->convert(122.50, 'NPR', 'EUR', '2019-01-01'); // Convert 122.50 NPR to
162177
```
163178

164179
### Fluent Interface
180+
165181
Most methods can be used with a _fluent interface_, allowing you to chain method calls for more readable code:
166182

167183
```php
168-
// Namespaces are omitted for readability!
184+
// Namespaces are omitted for readability!
169185
DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::EUR)->get();
170186
DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::NPR)->date('2013-03-02')->historical();
171187
DriverFactory::make('driver')->from(Symbol::USD)->to(Symbol::NPR)->amount(12.10)->convert();
172188
```
173189

174190
### Conversion Result
191+
175192
The [`get()`](#latest-rates) and [`historical()`](#historical-rates) endpoints return a
176193
[`ConversionResult`](src/Results/ConversionResult.php) object. This object allows you to perform calculations and
177194
conversions easily.
178195

179196
> **Note:** Even though free accounts of most providers do not allow you to change the base currency, you can still
180-
> use the `ConversionResult` object to change the base currency later. This might not be as accurate as changing the
181-
> base currency directly, though.
197+
> use the `ConversionResult` object to change the base currency later. This might not be as accurate as changing the
198+
> base currency directly, though.
182199
183-
> **Note:** To convert between two currencies, you need to request both of them in your initial [`get()`](#latest-rates)
200+
> **Note:** To convert between two currencies, you need to request both of them in your initial [`get()`](#latest-rates)
184201
> or [`historical()`](#historical-rates) request. You can not convert between currencies that have not been fetched!
185202
186203
See the following code for some examples of what you can do with the `ConversionResult` object.
@@ -214,5 +231,6 @@ $result->setBaseCurrency(Symbol::GBP)->rate(Symbol::EUR);
214231
```
215232

216233
## Contributing 🚧
217-
[Pull Requests](https://github.com/otherguy/php-currency-api/pulls) are more than welcome! I'm striving for 100% test
234+
235+
[Pull Requests](https://github.com/otherguy/php-currency-api/pulls) are more than welcome! I'm striving for 100% test
218236
coverage for this repository so please make sure to add tests for your code.

0 commit comments

Comments
 (0)