README

A Slim Framework 4 integration for the UniRate API — live currency exchange rates, conversion, supported-currency lists, and VAT rates.

It ships three pieces you can use together or separately:

UniRate\Slim\UniRateClient — a framework-agnostic client built on PSR-18 (HTTP client) and PSR-17 (request/URI factories), so it works with any HTTP client (Guzzle, Symfony HttpClient, …) and is trivial to mock.
UniRate\Slim\UniRateMiddleware — PSR-15 middleware that attaches the client to the request as an attribute.
registerUniRateRoutes() — a helper that adds ready-made JSON routes (/rate, /convert, /currencies, /vat) to your Slim app.

Installation

composer require unirate/slim

You also need a PSR-18 HTTP client and PSR-17 factories. For example, with Guzzle:

composer require guzzlehttp/guzzle

Get a free API key at unirateapi.com.

Quick start

use GuzzleHttp\Client as GuzzleClient;
use GuzzleHttp\Psr7\HttpFactory;
use Slim\Factory\AppFactory;
use UniRate\Slim\UniRateClient;
use UniRate\Slim\UniRateConfig;
use UniRate\Slim\UniRateMiddleware;
use function UniRate\Slim\registerUniRateRoutes;

$guzzle  = new GuzzleClient();
$factory = new HttpFactory();

$client = new UniRateClient(
    new UniRateConfig(getenv('UNIRATE_API_KEY')),
    $guzzle,   // PSR-18 ClientInterface
    $factory,  // PSR-17 RequestFactoryInterface
    $factory,  // PSR-17 UriFactoryInterface
);

$app = AppFactory::create();
$app->add(new UniRateMiddleware($client));
registerUniRateRoutes($app);          // adds /unirate/rate, /convert, /currencies, /vat
$app->run();

See examples/app.php for a complete runnable server.

Configuration

UniRateConfig takes the API key and an optional base URL, or build it from an options array:

$config = new UniRateConfig('your-key');                       // default base URL
$config = UniRateConfig::fromArray([
    'api_key'  => 'your-key',
    'base_url' => 'https://api.unirateapi.com',
]);

Routes

registerUniRateRoutes($app, $prefix = '/unirate', ?UniRateClient $client = null) registers four GET routes returning JSON:

Route	Query params	Response
`{prefix}/rate`	`from` (default `USD`), `to` (optional)	`{"rate": 0.92}` or `{"rate": {"EUR": 0.92, …}}`
`{prefix}/convert`	`from` (default `USD`), `to` (required), `amount` (default `1`)	`{"result": 92.5}`
`{prefix}/currencies`	—	`{"currencies": ["USD", "EUR", …]}`
`{prefix}/vat`	`country` (optional)	`{"vat": {…}}`

Route handlers resolve the client from the request attribute set by UniRateMiddleware. If you prefer not to use the middleware, pass the client as the third argument to make the routes self-contained:

registerUniRateRoutes($app, '/unirate', $client);

Using the client directly

$rate       = $client->getRate('USD', 'EUR');       // 0.92
$allRates   = $client->getRate('USD');              // ['EUR' => 0.92, ...]
$converted  = $client->convert('EUR', 100, 'USD');  // 92.5
$currencies = $client->getSupportedCurrencies();    // ['USD', 'EUR', ...]
$vat        = $client->getVatRates('DE');           // ['country_name' => 'Germany', 'vat_rate' => 19.0]

Inside a Slim handler, resolve the client from the request attribute:

use UniRate\Slim\UniRateClient;
use UniRate\Slim\UniRateMiddleware;

$app->get('/price', function ($request, $response) {
    /** @var UniRateClient $unirate */
    $unirate = $request->getAttribute(UniRateMiddleware::ATTRIBUTE);
    $eur = $unirate->convert('EUR', 100, 'USD');
    $response->getBody()->write("€{$eur}");
    return $response;
});

Error handling

The client throws UniRate\Slim\UniRateException (base), with the HTTP status as the exception code. Typed subclasses let you catch specific failures:

Status	Exception	Meaning
400	`Exception\InvalidDateException`	Invalid request parameters
401	`Exception\AuthenticationException`	Missing or invalid API key
403	`Exception\ApiException`	Endpoint requires a Pro subscription
404	`Exception\InvalidCurrencyException`	Currency not found or no data available
429	`Exception\RateLimitException`	Rate limit exceeded
503	`Exception\ApiException`	Service unavailable
other	`Exception\ApiException`	Generic API error (status + body)

The registered routes map these to JSON error responses that mirror the API status, e.g. 429 → {"error": "Rate limit exceeded."}.

Historical endpoints (getHistoricalRate) are Pro-gated and return 403 on the free tier.

Rate limits

Free-tier keys are rate limited; a 429 surfaces as RateLimitException.

Testing

composer install
./vendor/bin/phpunit

The suite mocks all HTTP traffic via php-http/mock-client — no live API calls or key required.

License

MIT — see LICENSE.

Related clients

Part of the official UniRate client family: Python, Node/TypeScript, Swift, Java, Go, Rust, Ruby, PHP, and .NET, plus framework integrations for Laravel, Symfony, Statamic, WordPress, and more.

unirate / slim

Package info

Security

Statistics