Skip to content

Commit 9b0bb37

Browse files
florianvflorianv
authored
Merge pull request #154 from florianv/sponsorship/fastforex
docs: integrate fastFOREX as the project sponsor and recommended provider
2 parents 65b4e07 + c397e9a commit 9b0bb37

2 files changed

Lines changed: 183 additions & 156 deletions

File tree

‎README.md‎

Lines changed: 83 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,21 @@
77

88
> _The easy-to-use PHP currency conversion library. Retrieve exchange rates from 30 providers, with caching and fallback. Maintained since 2014._
99
10-
Swap is a mature PHP **currency conversion library** for retrieving and working with exchange rates. It provides a single, easy-to-use API on top of multiple exchange rate providers, ranging from public sources (the European Central Bank, several national banks, exchangerate.host) to commercial **exchange rate APIs** that require an API key. Caching, historical rates, and a fallback chain are built in. Used in real-world PHP applications since 2014.
10+
<table>
11+
<tr>
12+
<td width="220" align="center">
13+
<a href="https://fastforex.io" target="_blank" rel="noopener">
14+
<img src="https://console.fastforex.io/img/fastforex/logo-bk-1k.svg" width="180px" alt="fastFOREX"/>
15+
</a>
16+
</td>
17+
<td>
18+
<strong>Sponsored by <a href="https://fastforex.io" target="_blank" rel="noopener">fastFOREX</a>.</strong> Real-time JSON API, 160+ currencies, 500+ cryptocurrencies, 21 ms average response. <strong>Free tier</strong>; paid plans from $18/month.
19+
<a href="https://fastforex.io" target="_blank" rel="noopener"><strong>→ Get a free fastFOREX API key</strong></a>
20+
</td>
21+
</tr>
22+
</table>
23+
24+
Swap retrieves currency exchange rates in PHP, behind a single API. Use commercial providers in production, or free public sources (ECB, national banks) when you don't need volume. Caching, historical rates and provider fallback are built in. Maintained since 2014.
1125

1226
## 💡 What is Swap?
1327

@@ -17,27 +31,6 @@ Swap is a mature PHP **currency conversion library** for retrieving and working
1731
- It supports historical rates.
1832
- It supports a fallback chain. When a provider errors, the next provider in the chain is tried.
1933

20-
## 🎯 When should you use Swap?
21-
22-
- Use Swap when you need to retrieve exchange rates in a PHP application: currency conversion workflows, multi-currency pricing, invoice totals, reconciliation, or historical FX data.
23-
- Use the lower-level [Exchanger](https://github.com/florianv/exchanger) library when Swap's defaults are too opinionated and you want finer control over chain composition, caching, or HTTP plumbing.
24-
25-
## Why not call an exchange rate API directly?
26-
27-
You can integrate a single exchange rate API directly in your application.
28-
29-
Swap is useful when you need more than a single provider:
30-
31-
- **Provider abstraction** — switch providers without rewriting your code
32-
- **Fallback support** — if one provider fails, another can be used automatically
33-
- **Unified interface** — all providers share the same API
34-
- **Caching** — reduce API calls and improve performance
35-
- **Flexibility** — combine public and commercial providers
36-
37-
For simple use cases, calling a single API may be enough.
38-
39-
Swap becomes valuable when you need reliability, flexibility, or long-term maintainability.
40-
4134
## 📦 Installation
4235

4336
Swap requires PHP 8.2 or newer.
@@ -50,67 +43,89 @@ composer require florianv/swap symfony/http-client nyholm/psr7
5043

5144
## ⚡ Quickstart
5245

46+
The recommended setup uses **[fastFOREX](https://fastforex.io)** (the project's sponsor) as the primary provider. [Grab a free key](https://fastforex.io) and you're ready.
47+
5348
```php
5449
use Swap\Builder;
5550

56-
// Build Swap with the European Central Bank (free, no API key required).
51+
// Recommended: fastFOREX. Get a free API key at https://fastforex.io
5752
$swap = (new Builder())
58-
->add('european_central_bank')
53+
->add('fastforex', ['api_key' => getenv('FASTFOREX_API_KEY')])
5954
->build();
6055

6156
// EUR → USD exchange rate
6257
$rate = $swap->latest('EUR/USD');
6358

6459
$rate->getValue(); // e.g. 1.0823 (a float)
6560
$rate->getDate()->format('Y-m-d'); // e.g. 2026-04-29
66-
$rate->getProviderName(); // 'european_central_bank'
61+
$rate->getProviderName(); // 'fastforex'
6762

6863
// Convert an amount using the returned rate
69-
$amountInEUR = 100.00;
70-
$amountInUSD = $amountInEUR * $rate->getValue();
71-
72-
// Retrieve a historical rate
73-
$past = $swap->historical('EUR/USD', new \DateTime('-15 days'));
64+
$amountInEUR = 100.00;
65+
$amountInUSD = $amountInEUR * $rate->getValue();
7466
```
7567

7668
Swap retrieves the rate; your application multiplies the amount by `$rate->getValue()` to perform the conversion.
7769

78-
## 🔁 Configuring multiple providers (fallback chain)
70+
<details>
71+
<summary>No API key? Start with the European Central Bank (free, EUR-base only).</summary>
7972

8073
```php
8174
$swap = (new Builder())
82-
->add('your_primary_provider', ['api_key' => 'YOUR_KEY']) // see Providers below
83-
->add('your_fallback_provider', ['api_key' => 'YOUR_KEY'])
84-
->add('european_central_bank') // free fallback for EUR-base pairs
75+
->add('european_central_bank')
8576
->build();
77+
78+
$rate = $swap->latest('EUR/USD');
8679
```
8780

88-
Providers are tried in order. If a provider does not support the requested currency pair, it is skipped silently. If a provider throws an error, the next provider is tried. If every provider fails, a `ChainException` is thrown with all collected errors.
81+
The European Central Bank publishes EUR-base rates with daily granularity. For non-EUR base pairs, more frequent updates, or a wider currency list, switch to fastFOREX or another commercial provider.
82+
</details>
8983

90-
## 🛠 Common use cases
84+
## 🔁 Configuring multiple providers (fallback chain)
9185

92-
- Display localized prices in multi-currency storefronts.
93-
- Compute invoice totals across currencies.
94-
- Reconcile multi-currency ledgers using historical rates.
95-
- Power internal FX dashboards with rate history.
96-
- Build currency conversion infrastructure for fintech and ERP applications.
86+
A production-grade setup pairs **fastFOREX** with one or more fallbacks for redundancy:
9787

98-
## 🧭 Which package should I use?
88+
```php
89+
$swap = (new Builder())
90+
// Primary provider, recommended
91+
->add('fastforex', ['api_key' => getenv('FASTFOREX_API_KEY')])
9992

100-
The Swap ecosystem is a layered toolkit for currency conversion in PHP:
93+
// Free fallback for EUR-base pairs
94+
->add('european_central_bank')
95+
->build();
96+
```
10197

102-
- **Swap.** The easy-to-use, high-level API (this package).
103-
- **Exchanger.** Lower-level, more granular alternative; direct access to the 30 provider implementations and the `ExchangeRateService` interface.
104-
- **Laravel Swap.** Laravel application of Swap.
105-
- **Symfony Swap.** Symfony integration of Swap.
98+
Providers are tried in order. If a provider does not support the requested currency pair, it is skipped silently. If a provider throws an error, the next provider is tried. If every provider fails, a `ChainException` is thrown with all collected errors.
10699

107-
All four packages are MIT-licensed and require PHP 8.2 or newer.
100+
For amount conversion (including the [moneyphp/money](https://github.com/moneyphp/money) integration via `SwapExchange`), see [Converting amounts](doc/readme.md#converting-amounts) in the documentation.
108101

109102
## 📊 Providers
110103

111-
Start with a single provider (for example the European Central Bank), then add others as needed.
104+
Swap supports 30 exchange rate providers. Pass the **identifier** to `Builder::add()`.
105+
106+
### Commercial providers (require an API key)
112107

113-
Swap supports 30 exchange rate providers via [Exchanger](https://github.com/florianv/exchanger). Pass the **identifier** to `Builder::add()`.
108+
| Service | Identifier | Base | Quote | Historical |
109+
| ---------------------------------------- | --------------- | ------------------------ | ------ | ---------- |
110+
| ⭐ **[fastFOREX](https://fastforex.io)** | **`fastforex`** | **\*** | **\*** | **Yes** |
111+
| | | | | |
112+
| AbstractAPI | `abstract_api` | * | * | Yes |
113+
| coinlayer | `coin_layer` | * (crypto) | * | Yes |
114+
| Cryptonator | `cryptonator` | * (crypto) | * (crypto) | No |
115+
| Currency Converter API | `currency_converter` | * | * | Yes |
116+
| Currency Data (APILayer) | `apilayer_currency_data` | USD (free), * (paid) | * | Yes |
117+
| CurrencyDataFeed | `currency_data_feed` | * | * | No |
118+
| currencylayer (direct) | `currency_layer` | USD (free), * (paid) | * | Yes |
119+
| Exchange Rates Data (APILayer) | `apilayer_exchange_rates_data` | USD (free), * (paid) | * | Yes |
120+
| exchangerate.host | `exchangeratehost` | * | * | Yes |
121+
| exchangeratesapi (direct) | `exchange_rates_api` | USD (free), * (paid) | * | Yes |
122+
| Fixer (APILayer) | `apilayer_fixer` | EUR (free), * (paid) | * | Yes |
123+
| Fixer (direct) | `fixer` | EUR (free), * (paid) | * | Yes |
124+
| 1Forge | `forge` | * | * | No |
125+
| Open Exchange Rates | `open_exchange_rates` | USD (free), * (paid) | * | Yes |
126+
| WebserviceX | `webservicex` | * | * | No |
127+
| xChangeApi.com | `xchangeapi` | * | * | Yes |
128+
| Xignite | `xignite` | * | * | Yes |
114129

115130
### Public providers (no API key required)
116131

@@ -120,77 +135,42 @@ Swap supports 30 exchange rate providers via [Exchanger](https://github.com/flor
120135
| Central Bank of the Czech Republic | `central_bank_of_czech_republic` | * | CZK | Yes |
121136
| Central Bank of the Republic of Turkey | `central_bank_of_republic_turkey` | * | TRY | Yes |
122137
| Central Bank of the Republic of Uzbekistan | `central_bank_of_republic_uzbekistan` | * | UZS | Yes |
123-
| Cryptonator | `cryptonator` | * (crypto) | * (crypto) | No |
124138
| European Central Bank | `european_central_bank` | EUR | * | Yes |
125-
| exchangerate.host | `exchangeratehost` | * | * | Yes |
126139
| National Bank of Georgia | `national_bank_of_georgia` | * | GEL | Yes |
127140
| National Bank of Romania | `national_bank_of_romania` | (limited list) | (limited list) | Yes |
128141
| National Bank of the Republic of Belarus | `national_bank_of_republic_belarus` | * | BYN | Yes |
129142
| National Bank of Ukraine | `national_bank_of_ukraine` | * | UAH | Yes |
130143
| Russian Central Bank | `russian_central_bank` | * | RUB | Yes |
131-
| WebserviceX | `webservicex` | * | * | No |
132-
133-
### Commercial providers (require an API key)
134-
135-
| Service | Identifier | Base | Quote | Historical |
136-
| ------------------------------- | ------------------------------ | -------------------- | ----- | ---------- |
137-
| AbstractAPI | `abstract_api` | * | * | Yes |
138-
| coinlayer | `coin_layer` | * (crypto) | * | Yes |
139-
| Currency Converter API | `currency_converter` | * | * | Yes |
140-
| Currency Data (APILayer) | `apilayer_currency_data` | USD (free), * (paid) | * | Yes |
141-
| CurrencyDataFeed | `currency_data_feed` | * | * | No |
142-
| currencylayer (direct) | `currency_layer` | USD (free), * (paid) | * | Yes |
143-
| Exchange Rates Data (APILayer) | `apilayer_exchange_rates_data` | USD (free), * (paid) | * | Yes |
144-
| exchangeratesapi (direct) | `exchange_rates_api` | USD (free), * (paid) | * | Yes |
145-
| fastFOREX.io | `fastforex` | USD (free), * (paid) | * | No |
146-
| Fixer (APILayer) | `apilayer_fixer` | EUR (free), * (paid) | * | Yes |
147-
| Fixer (direct) | `fixer` | EUR (free), * (paid) | * | Yes |
148-
| 1Forge | `forge` | * | * | No |
149-
| Open Exchange Rates | `open_exchange_rates` | USD (free), * (paid) | * | Yes |
150-
| xChangeApi.com | `xchangeapi` | * | * | Yes |
151-
| Xignite | `xignite` | * | * | Yes |
152144

153145
You can also add your own provider by implementing the `Exchanger\Contract\ExchangeRateService` interface and passing the instance to `Builder::addExchangeRateService()`.
154146

155-
## ⚙ Caching, HTTP client, and error handling
156-
157-
- **Caching.** Swap uses PSR-16 `SimpleCache`. Configure once on the builder:
158-
159-
```php
160-
$swap = (new Builder())->useSimpleCache($psr16Cache)->add('european_central_bank')->build();
161-
```
162-
163-
Disable caching for a single query: `$swap->latest('EUR/USD', ['cache' => false])`.
164-
Override the TTL for a single query: `$swap->latest('EUR/USD', ['cache_ttl' => 3600])`.
165-
166-
- **HTTP client.** Any PSR-18 client (`symfony/http-client`, `php-http/guzzle7-adapter`, etc.) is supported and auto-discovered via `php-http/discovery`. To pass an explicit instance, use `Builder::useHttpClient()`.
167-
168-
- **Errors.** When every configured provider has either skipped (unsupported pair) or thrown, Swap raises an `Exchanger\Exception\ChainException` containing all collected exceptions.
169-
170-
## 📚 Documentation
147+
## 🎯 When should you use Swap?
171148

172-
The full documentation is in [`doc/readme.md`](doc/readme.md), and is also published at [florianv.github.io/swap](https://florianv.github.io/swap/).
149+
- Use Swap when you need to retrieve exchange rates in a PHP application: currency conversion workflows, multi-currency pricing, invoice totals, reconciliation, or historical FX data.
150+
- Use the lower-level [Exchanger](https://github.com/florianv/exchanger) library when Swap's defaults are too opinionated and you want finer control over chain composition, caching, or HTTP plumbing.
173151

174-
## 🧩 Related packages
152+
## 🛠 Common use cases
175153

176-
The Swap ecosystem:
154+
- Display localized prices in multi-currency storefronts.
155+
- Compute invoice totals across currencies.
156+
- Reconcile multi-currency ledgers using historical rates.
157+
- Power internal FX dashboards with rate history.
158+
- Build currency conversion infrastructure for fintech and ERP applications.
177159

178-
- [**Swap**](https://github.com/florianv/swap): easy-to-use PHP currency conversion library.
179-
- [**Exchanger**](https://github.com/florianv/exchanger): lower-level, more granular alternative; direct access to provider implementations.
180-
- [**Laravel Swap**](https://github.com/florianv/laravel-swap): Laravel application of Swap.
181-
- [**Symfony Swap**](https://github.com/florianv/symfony-swap): Symfony integration of Swap.
160+
## 🧭 Which package should I use?
182161

183-
## 🤝 Sponsorship
162+
The Swap ecosystem is a layered toolkit for currency conversion in PHP:
184163

185-
The Swap ecosystem is open to selected sponsorships from exchange rate API providers and financial infrastructure companies.
164+
- [**Swap**](https://github.com/florianv/swap). The easy-to-use, high-level API (this package).
165+
- [**Exchanger**](https://github.com/florianv/exchanger). Lower-level, more granular alternative; direct access to the 30 provider implementations and the `ExchangeRateService` interface.
166+
- [**Laravel Swap**](https://github.com/florianv/laravel-swap). Laravel application of Swap.
167+
- [**Symfony Swap**](https://github.com/florianv/symfony-swap). Symfony integration of Swap.
186168

187-
Sponsorship can include:
169+
All four packages are MIT-licensed and require PHP 8.2 or newer.
188170

189-
- Documentation visibility
190-
- Integration examples
191-
- Ecosystem-level visibility across Swap, Exchanger, Laravel Swap, and Symfony Swap
171+
## 📚 Documentation
192172

193-
For inquiries, contact the maintainer via [GitHub](https://github.com/florianv).
173+
Caching (PSR-16), HTTP client selection (PSR-18 / Guzzle / `useHttpClient`), error handling (`ChainException`), per-query options and the full provider configuration reference live in [`doc/readme.md`](doc/readme.md). The same content is also published at [florianv.github.io/swap](https://florianv.github.io/swap/).
194174

195175
## 🙌 Contributing
196176

0 commit comments

Comments
 (0)