diff --git a/README.md b/README.md
index 93bc220..94a3808 100644
--- a/README.md
+++ b/README.md
@@ -4,21 +4,25 @@ API for accessing Polish National Bank (NBP - Narodowy Bank Polski) currency and
[![Latest Version on Packagist][badge-version]][link-packagist]
[![No dependencies][badge-no-deps]][link-packagist]
-[![Tests Coverage][badge-coverage]][link-coverage]
-[![PHP 8.1 Test Result][badge-test-result-8.1]][link-php-tests]
-[![PHP 8.2 Test Result][badge-test-result-8.2]][link-php-tests]
-[![PHP 8.3 Test Result][badge-test-result-8.3]][link-php-tests]
-[![PHP 8.4 Test Result][badge-test-result-8.4]][link-php-tests]
-[![PHP 8.5 Test Result][badge-test-result-8.5]][link-php-tests]
[![MIT License][badge-license]][link-license]
+[![Tests Coverage][badge-coverage]][link-coverage]
+[![PHP 8.1 Test Result][badge-test-result-8.1]][link-php-tests]
+[![PHP 8.2 Test Result][badge-test-result-8.2]][link-php-tests]
+[![PHP 8.3 Test Result][badge-test-result-8.3]][link-php-tests]
+[![PHP 8.4 Test Result][badge-test-result-8.4]][link-php-tests]
+[![PHP 8.5 Test Result][badge-test-result-8.5]][link-php-tests]
+## Installing via composer
-## Usage
+```bash
+composer require maciej-sz/nbp-php
+```
-### Installing via composer
-```composer require maciej-sz/nbp-php```
+## Usage
+
+The full API of this library can be found in [api.md](api.md).
### Minimal setup
@@ -40,310 +44,11 @@ USD rate is 4.381100
### Examples
-All working examples from this README are included in the `examples/` directory of the repository.
-
-## Services
-
-### CurrencyAverageRatesService
-
-This service provides API for accessing average rates published in NBP tables.
-
-#### `fromMonth` method
-
-Returns flat collection of rates from all NBP tables at given month
-
-```php
-$averageRatesFromJanuary = $currencyAverages->fromMonth(2023, 1);
-
-foreach ($averageRatesFromJanuary as $rate) {
- printf(
- '%s rate from %s is %F' . PHP_EOL,
- $rate->getCurrencyCode(),
- $rate->getEffectiveDate()->format('Y-m-d'),
- $rate->getValue()
- );
-}
-```
-
-```
-THB rate from 2023-01-02 is 0.126700
-USD rate from 2023-01-02 is 4.381100
-AUD rate from 2023-01-02 is 2.976700
-...
-```
-
-#### `fromDay` method
-
-Returns a dictionary with NBP tables from given day.
-
-```php
-$eurRateFromApril4th = $currencyAverages
- ->fromDay('2023-04-04')
- ->fromTable('A')
- ->getRate('EUR');
-
-echo $eurRateFromApril4th->getValue(); // 4.6785
-```
-
-#### `fromDayBefore` method
-
-Returns a dictionary with NBP tables from day before given day. This method can be useful
-in some bookkeeping applications when there is a legislatory need to calculate
-transfer prices. The legislation requires for the prices to be calculated using
-currency rate applied in the business day before the actual transfer date. Which is
-exactly what this method exposes.
-
-Example:
-```php
-$eurRateFromBeforeJanuary2nd = $currencyAverages
- ->fromDayBefore('2023-01-02')
- ->fromTable('A')
- ->getRate('EUR')
-;
-
-printf(
- '%s rate from %s is %F',
- $eurRateFromBeforeJanuary2nd->getCurrencyCode(),
- $eurRateFromBeforeJanuary2nd->getEffectiveDate()->format('Y-m-d'),
- $eurRateFromBeforeJanuary2nd->getValue()
-);
-```
-```
-EUR rate from 2022-12-30 is 4.689900
-```
-
-#### `getMonthTablesA` method
-
-Returns the `A` table iterator from a specific month. Rates here are grouped into tables,
-which represent the actual data structure provided by NBP. To get the rates there needs
-to be second iteration:
-
-```php
-$aTablesFromMarch = $currencyAverages->getMonthTablesA(2023, 3);
-
-foreach ($aTablesFromMarch as $table) {
- foreach ($table->getRates() as $rate) {
- printf(
- '%s rate from table %s is %F' . PHP_EOL,
- $rate->getCurrencyCode(),
- $table->getNo(),
- $rate->getValue()
- );
- }
-}
-```
-
-```
-THB rate from table 042/A/NBP/2023 is 0.126700
-USD rate from table 042/A/NBP/2023 is 4.409400
-AUD rate from table 042/A/NBP/2023 is 2.981900
-...
-THB rate from table 043/A/NBP/2023 is 0.126600
-USD rate from table 043/A/NBP/2023 is 4.400200
-AUD rate from table 043/A/NBP/2023 is 2.963800
-...
-```
-
-Example getting specific rate:
-```php
-$aTablesFromMarch = $currencyAverages->getMonthTablesA(2023, 3);
-
-foreach ($aTablesFromMarch as $table) {
- $chfRate = $table->getRate('CHF');
- printf(
- '%s rate from table %s is %F' . PHP_EOL,
- $chfRate->getCurrencyCode(),
- $table->getNo(),
- $chfRate->getValue()
- );
-}
-```
-
-```
-CHF rate from table 042/A/NBP/2023 is 4.703100
-CHF rate from table 043/A/NBP/2023 is 4.674300
-CHF rate from table 044/A/NBP/2023 is 4.728000
-// ...
-```
-
-#### `getMonthTablesB` method
-
-Returns the `B` table iterator from a specific month.
-
-```php
-$bTablesFromMarch = $currencyAverages->getMonthTablesB(2022, 3);
-
-foreach ($bTablesFromMarch as $table) {
- try {
- $rate = $table->getRate('MNT');
- } catch (CurrencyCodeNotFoundException $e) {
- continue;
- }
- printf(
- '%s rate from table %s is %F' . PHP_EOL,
- $rate->getCurrencyName(),
- $table->getNo(),
- $rate->getValue()
- );
-}
-```
-
-```
-tugrik (Mongolia) rate from table 009/B/NBP/2022 is 0.001500
-tugrik (Mongolia) rate from table 010/B/NBP/2022 is 0.001529
-tugrik (Mongolia) rate from table 011/B/NBP/2022 is 0.001469
-tugrik (Mongolia) rate from table 012/B/NBP/2022 is 0.001457
-tugrik (Mongolia) rate from table 013/B/NBP/2022 is 0.001417
-```
-
-##### Warning about missing currencies in table B
-
-In table `B` there can be multiple currencies with the same code.
-
-It is also possible, that a specific currency is present in table from one day,
-but is not present in table from the next day.
-
-In such case you should not use the `getRate($rate)` method but rather
-iterate over all currencies returned by `getRates()`.
-
-### Currency trading rates service
-
-This service is used to get buy and sell currency rates from NBP tables.
+See the [examples](./examples/) directory for complete and runnable examples.
-#### `fromMonth` method
-Returns trading rates from entire month.
-```php
-$tradingRatesFromApril = $currencyTrading->fromMonth(2023, 4);
-
-foreach ($tradingRatesFromApril as $rate) {
- printf(
- "%s rate from %s effective day traded on %s ask price is %s, bid price is %s\n",
- $rate->getCurrencyCode(),
- $rate->getEffectiveDate()->format('Y-m-d'),
- $rate->getTradingDate()->format('Y-m-d'),
- $rate->getAsk(),
- $rate->getBid()
- );
-}
-```
-
-```
-USD rate from 2023-04-03 effective day traded on 2023-03-31 ask price is 4.3338, bid price is 4.248
-AUD rate from 2023-04-03 effective day traded on 2023-03-31 ask price is 2.9072, bid price is 2.8496
-CAD rate from 2023-04-03 effective day traded on 2023-03-31 ask price is 3.2033, bid price is 3.1399
-EUR rate from 2023-04-03 effective day traded on 2023-03-31 ask price is 4.7208, bid price is 4.6274
-...
-```
-
-#### `fromEffectiveDay` method
-
-Return rates from effective date.
-
-```php
-$gbpFromApril4th = $currencyTrading->fromEffectiveDay('2023-04-04')->getRate('GBP');
-
-printf(
- '%s rate from %s effective day traded on %s ask price is %s, bid price is %s',
- $gbpFromApril4th->getCurrencyCode(),
- $gbpFromApril4th->getEffectiveDate()->format('Y-m-d'),
- $gbpFromApril4th->getTradingDate()->format('Y-m-d'),
- $gbpFromApril4th->getAsk(),
- $gbpFromApril4th->getBid()
-);
-```
-
-```
-GBP rate from 2023-04-04 effective day traded on 2023-04-03 ask price is 5.3691, bid price is 5.2627
-```
-
-#### `fromTradingDay` method
-
-Return rates from trading date.
-
-```php
-$gbpFromApril4th = $currencyTrading->fromTradingDay('2023-04-04')->getRate('GBP');
-
-printf(
- '%s rate from %s effective day traded on %s ask price is %s, bid price is %s',
- $gbpFromApril4th->getCurrencyCode(),
- $gbpFromApril4th->getEffectiveDate()->format('Y-m-d'),
- $gbpFromApril4th->getTradingDate()->format('Y-m-d'),
- $gbpFromApril4th->getAsk(),
- $gbpFromApril4th->getBid()
-);
-```
-
-```
-GBP rate from 2023-04-05 effective day traded on 2023-04-04 ask price is 5.4035, bid price is 5.2965
-```
-
-### Gold rates service
-
-This service is used to get gold commodity rates from NBP tables.
-
-#### `fromMonth` method
-
-Gets all rates from specific month.
-
-```php
-$jan2013rates = $goldRates->fromMonth(2013, 1);
-
-foreach ($jan2013rates as $rate) {
- printf(
- 'Gold rate from %s is %F' . PHP_EOL,
- $rate->getDate()->format('Y-m-d'),
- $rate->getValue()
- );
-}
-```
-
-```
-Gold rate from 2013-01-02 is 165.830000
-Gold rate from 2013-01-03 is 166.970000
-Gold rate from 2013-01-04 is 167.430000
-...
-```
-
-#### `fromDay` method
-
-Returns a gold rate from specific date.
-
-```php
-$goldRateFromJan2nd2014 = $goldRates->fromDay('2014-01-02');
-
-printf(
- 'Gold rate from %s is %F',
- $goldRateFromJan2nd2014->getDate()->format('Y-m-d'),
- $goldRateFromJan2nd2014->getValue()
-);
-```
-
-```
-Gold rate from 2014-01-02 is 116.350000
-```
-
-#### `fromDayBefore` method
-
-Returns a gold rate from before a specific date.
-
-```php
-$goldRateBeforeJan2nd = $goldRates->fromDayBefore('2014-01-02');
-
-printf(
- 'Gold rate from %s is %F',
- $goldRateBeforeJan2nd->getDate()->format('Y-m-d'),
- $goldRateBeforeJan2nd->getValue()
-);
-
-```
-
-```
-Gold rate from 2013-12-31 is 116.890000
-```
-
-## Using cache
+### Using cache
_Note that a library implementing PSR-6 has to be provided in order to use the caching
abilities._
@@ -352,7 +57,7 @@ The `CachedTransport` class is a proxy for all other transport implementations.
This transport has to be backed by another transport, as it relies on it to
make the actual requests that have not been cached yet.
-### Example
+#### Example
```php
use Symfony\Component\Cache\Adapter\FilesystemAdapter as CachePoolAdapter;
@@ -374,7 +79,7 @@ $took = $end - $start;
printf('Getting the rate took %F ms', $took * 1000);
```
-## Using custom transport
+### Using custom transport
The library uses Symfony HTTP Client and Guzzle as default transports.
If those packages are not available then it falls back to the `file_get_contents`
@@ -430,7 +135,9 @@ Request successful
Gold rate from 2022-01-03 is 235.720000
```
-## Layers
+## Architecture
+
+On the infrastructure level the code utilizes layered architecture to keep the concerns separated.
### Service layer
@@ -494,4 +201,4 @@ implementation depending on installed libraries and configuration.
[link-packagist]:https://packagist.org/packages/maciej-sz/nbp-php
[link-license]:https://github.com/maciej-sz/nbp-php/blob/master/LICENSE
[link-php-tests]:https://github.com/maciej-sz/nbp-php/actions/workflows/php-tests.yml
-[link-coverage]:https://github.com/maciej-sz/nbp-php/actions/workflows/pr-coverage.yml
\ No newline at end of file
+[link-coverage]:https://github.com/maciej-sz/nbp-php/actions/workflows/master-coverage.yml
\ No newline at end of file
diff --git a/api.md b/api.md
new file mode 100644
index 0000000..c3801cc
--- /dev/null
+++ b/api.md
@@ -0,0 +1,357 @@
+## CurrencyAverageRatesService
+
+This service provides an API for accessing the average rates published in NBP tables.
+
+### `fromMonth` method
+
+Returns a flat collection of rates from all NBP tables for a given month
+
+
+Example
+
+```php
+$averageRatesFromJanuary = $currencyAverages->fromMonth(2023, 1);
+
+foreach ($averageRatesFromJanuary as $rate) {
+ printf(
+ '%s rate from %s is %F' . PHP_EOL,
+ $rate->getCurrencyCode(),
+ $rate->getEffectiveDate()->format('Y-m-d'),
+ $rate->getValue()
+ );
+}
+```
+
+```
+THB rate from 2023-01-02 is 0.126700
+USD rate from 2023-01-02 is 4.381100
+AUD rate from 2023-01-02 is 2.976700
+...
+```
+
+
+
+### `fromDay` method
+
+Returns a dictionary of NBP tables for a given day.
+
+
+Example
+
+```php
+$eurRateFromApril4th = $currencyAverages
+ ->fromDay('2023-04-04')
+ ->fromTable('A')
+ ->getRate('EUR');
+
+echo $eurRateFromApril4th->getValue(); // 4.6785
+```
+
+
+
+### `fromDayBefore` method
+
+This method returns rates corresponding to the previous business day to the one provided as the argument.
+
+This can be useful in some bookkeeping applications when there is a legislatory need to calculate
+transfer prices. The legislation requires for the prices to be calculated
+using a currency rate applied in the business day before the actual transfer date.
+
+
+Example
+
+```php
+$eurRateFromBeforeJanuary2nd = $currencyAverages
+ ->fromDayBefore('2023-01-02')
+ ->fromTable('A')
+ ->getRate('EUR')
+;
+
+printf(
+ '%s rate from %s is %F',
+ $eurRateFromBeforeJanuary2nd->getCurrencyCode(),
+ $eurRateFromBeforeJanuary2nd->getEffectiveDate()->format('Y-m-d'),
+ $eurRateFromBeforeJanuary2nd->getValue()
+);
+```
+```
+EUR rate from 2022-12-30 is 4.689900
+```
+
+
+
+### `getMonthTablesA` method
+
+Returns the `A` table iterator from a specific month.
+
+Rates here are grouped into tables, which represent the actual data structure provided by NBP.
+To get the actual rates, a second iteration is required:
+
+
+Example: getting all currency rates
+
+```php
+$aTablesFromMarch = $currencyAverages->getMonthTablesA(2023, 3);
+
+foreach ($aTablesFromMarch as $table) {
+ foreach ($table->getRates() as $rate) {
+ printf(
+ '%s rate from table %s is %F' . PHP_EOL,
+ $rate->getCurrencyCode(),
+ $table->getNo(),
+ $rate->getValue()
+ );
+ }
+}
+```
+
+```
+THB rate from table 042/A/NBP/2023 is 0.126700
+USD rate from table 042/A/NBP/2023 is 4.409400
+AUD rate from table 042/A/NBP/2023 is 2.981900
+...
+THB rate from table 043/A/NBP/2023 is 0.126600
+USD rate from table 043/A/NBP/2023 is 4.400200
+AUD rate from table 043/A/NBP/2023 is 2.963800
+...
+```
+
+
+
+
+Example: getting specific currency rate
+
+```php
+$aTablesFromMarch = $currencyAverages->getMonthTablesA(2023, 3);
+
+foreach ($aTablesFromMarch as $table) {
+ $chfRate = $table->getRate('CHF');
+ printf(
+ '%s rate from table %s is %F' . PHP_EOL,
+ $chfRate->getCurrencyCode(),
+ $table->getNo(),
+ $chfRate->getValue()
+ );
+}
+```
+
+```
+CHF rate from table 042/A/NBP/2023 is 4.703100
+CHF rate from table 043/A/NBP/2023 is 4.674300
+CHF rate from table 044/A/NBP/2023 is 4.728000
+// ...
+```
+
+
+
+### `getMonthTablesB` method
+
+Returns the `B` table iterator from a specific month.
+
+
+Example
+
+```php
+$bTablesFromMarch = $currencyAverages->getMonthTablesB(2022, 3);
+
+foreach ($bTablesFromMarch as $table) {
+ try {
+ $rate = $table->getRate('MNT');
+ } catch (CurrencyCodeNotFoundException $e) {
+ continue;
+ }
+ printf(
+ '%s rate from table %s is %F' . PHP_EOL,
+ $rate->getCurrencyName(),
+ $table->getNo(),
+ $rate->getValue()
+ );
+}
+```
+
+```
+tugrik (Mongolia) rate from table 009/B/NBP/2022 is 0.001500
+tugrik (Mongolia) rate from table 010/B/NBP/2022 is 0.001529
+tugrik (Mongolia) rate from table 011/B/NBP/2022 is 0.001469
+tugrik (Mongolia) rate from table 012/B/NBP/2022 is 0.001457
+tugrik (Mongolia) rate from table 013/B/NBP/2022 is 0.001417
+```
+
+
+
+#### Warning about missing currencies in table "B"
+
+In table `B` there can be multiple currencies with the same code.
+
+It is also possible, that a specific currency is present in table from one day,
+but is not present in table from the next day.
+
+In such case, you should not use the `getRate($rate)` method but rather
+iterate over all currencies returned by `getRates()`.
+
+## Currency trading rates service
+
+This service is used to get buy and sell currency rates from NBP tables.
+
+### `fromMonth` method
+
+Returns trading rates from the entire month.
+
+
+Example
+
+```php
+$tradingRatesFromApril = $currencyTrading->fromMonth(2023, 4);
+
+foreach ($tradingRatesFromApril as $rate) {
+ printf(
+ "%s rate from %s effective day traded on %s ask price is %s, bid price is %s\n",
+ $rate->getCurrencyCode(),
+ $rate->getEffectiveDate()->format('Y-m-d'),
+ $rate->getTradingDate()->format('Y-m-d'),
+ $rate->getAsk(),
+ $rate->getBid()
+ );
+}
+```
+
+```
+USD rate from 2023-04-03 effective day traded on 2023-03-31 ask price is 4.3338, bid price is 4.248
+AUD rate from 2023-04-03 effective day traded on 2023-03-31 ask price is 2.9072, bid price is 2.8496
+CAD rate from 2023-04-03 effective day traded on 2023-03-31 ask price is 3.2033, bid price is 3.1399
+EUR rate from 2023-04-03 effective day traded on 2023-03-31 ask price is 4.7208, bid price is 4.6274
+...
+```
+
+
+
+### `fromEffectiveDay` method
+
+Returns rates from the effective date.
+
+
+Example
+
+```php
+$gbpFromApril4th = $currencyTrading->fromEffectiveDay('2023-04-04')->getRate('GBP');
+
+printf(
+ '%s rate from %s effective day traded on %s ask price is %s, bid price is %s',
+ $gbpFromApril4th->getCurrencyCode(),
+ $gbpFromApril4th->getEffectiveDate()->format('Y-m-d'),
+ $gbpFromApril4th->getTradingDate()->format('Y-m-d'),
+ $gbpFromApril4th->getAsk(),
+ $gbpFromApril4th->getBid()
+);
+```
+
+```
+GBP rate from 2023-04-04 effective day traded on 2023-04-03 ask price is 5.3691, bid price is 5.2627
+```
+
+
+
+### `fromTradingDay` method
+
+Returns rates from the trading date.
+
+
+Example
+
+```php
+$gbpFromApril4th = $currencyTrading->fromTradingDay('2023-04-04')->getRate('GBP');
+
+printf(
+ '%s rate from %s effective day traded on %s ask price is %s, bid price is %s',
+ $gbpFromApril4th->getCurrencyCode(),
+ $gbpFromApril4th->getEffectiveDate()->format('Y-m-d'),
+ $gbpFromApril4th->getTradingDate()->format('Y-m-d'),
+ $gbpFromApril4th->getAsk(),
+ $gbpFromApril4th->getBid()
+);
+```
+
+```
+GBP rate from 2023-04-05 effective day traded on 2023-04-04 ask price is 5.4035, bid price is 5.2965
+```
+
+
+
+## Gold rates service
+
+This service is used to get gold commodity rates from NBP tables.
+
+### `fromMonth` method
+
+Gets all rates for a specific month.
+
+
+Example
+
+```php
+$jan2013rates = $goldRates->fromMonth(2013, 1);
+
+foreach ($jan2013rates as $rate) {
+ printf(
+ 'Gold rate from %s is %F' . PHP_EOL,
+ $rate->getDate()->format('Y-m-d'),
+ $rate->getValue()
+ );
+}
+```
+
+```
+Gold rate from 2013-01-02 is 165.830000
+Gold rate from 2013-01-03 is 166.970000
+Gold rate from 2013-01-04 is 167.430000
+...
+```
+
+
+
+### `fromDay` method
+
+Returns a gold rate for a specific date.
+
+
+Example
+
+```php
+$goldRateFromJan2nd2014 = $goldRates->fromDay('2014-01-02');
+
+printf(
+ 'Gold rate from %s is %F',
+ $goldRateFromJan2nd2014->getDate()->format('Y-m-d'),
+ $goldRateFromJan2nd2014->getValue()
+);
+```
+
+```
+Gold rate from 2014-01-02 is 116.350000
+```
+
+
+
+### `fromDayBefore` method
+
+Returns a gold rate for the business day preceding a specific date.
+
+
+Example
+
+```php
+$goldRateBeforeJan2nd = $goldRates->fromDayBefore('2014-01-02');
+
+printf(
+ 'Gold rate from %s is %F',
+ $goldRateBeforeJan2nd->getDate()->format('Y-m-d'),
+ $goldRateBeforeJan2nd->getValue()
+);
+
+```
+
+```
+Gold rate from 2013-12-31 is 116.890000
+```
+
+
\ No newline at end of file