Currency Laravel Package

Getting Started

• Install with Composer and pin the version, because the package is archived and last released in 2021:

composer require amrshawky/currency

• Look first at the package README, then src/Currency.php. The public surface is small and fluent; confirm the exact method signatures there before spreading usage through the app.
• First day-to-day use case: a one-off fiat conversion in Tinker, an Artisan command, or a small service class:

use AmrShawky\Currency\Currency;

$converted = (new Currency())
    ->source('USD')
    ->target('EUR')
    ->amount(100)
    ->get();

• This is a plain PHP library, not a Laravel package. There is no service provider or Laravel config to publish. The first integration step is usually a thin wrapper class around it.

Implementation Patterns

• Wrap the package behind an application service instead of calling it directly from controllers, models, or Blade views:

namespace App\Services;

use AmrShawky\Currency\Currency;

class CurrencyConverter
{
    public function convert(string $from, string $to, float $amount): float
    {
        return (new Currency())
            ->source(strtoupper($from))
            ->target(strtoupper($to))
            ->amount($amount)
            ->get();
    }
}

• Use the wrapper as the seam for caching, validation, retries, logging, and eventual provider replacement. Because the package is archived, the interface matters more than the concrete library.
• Cache aggressively. Current rates can be cached for 5–15 minutes; historical rates can be cached for a long time or permanently. Use a key that includes source, target, date, and rate type:

$key = "fx:USD:EUR:2024-01-15";

$rate = cache()->remember($key, now()->addDay(), function () {
    return (new Currency())
        ->source('USD')
        ->target('EUR')
        ->amount(1)
        ->date('2024-01-15')
        ->get();
});

• For dashboard or checkout flows, fetch the rate once and apply it locally rather than making an API call per line item. Store the rate and the timestamp used for the conversion.
• For crypto, use the same fluent chain but be explicit about symbols and precision. Treat crypto amounts as decimal strings or integer minor units at the boundaries; avoid relying on float math for accounting.
• Validate currencies against an allowlist before calling the package. That avoids typo-driven external requests and gives users a better error.
• In Laravel, bind your own wrapper interface in a service provider:

$this->app->bind(CurrencyConverter::class, function () {
    return new CurrencyConverter();
});

Do not bind the package’s Currency object as a long-lived singleton unless you verify it is stateless; the fluent API may retain source/target/date state between calls.

• For tests, mock your wrapper, not the remote API. Keep one optional integration test that hits exchangerate.host, tagged or skipped when network/API access is unavailable.

Gotchas and Tips

• The package is archived and last released in 2021. Treat it as legacy glue code. Check PHP 8.x compatibility, dependency constraints, and whether the exchangerate.host API contract still matches the library.
• exchangerate.host API behavior and authentication may have changed since the release. Verify whether an access key, HTTPS, or different endpoint is required. If the package hardcodes an old URL or lacks key support, fork it or replace it behind your wrapper.
• External API calls need timeout and failure handling. Wrap calls in try/catch, log failures, and return a safe application error rather than leaking library/API exceptions.
• Watch for floating-point rounding. Rates are decimal data; round only at display or settlement boundaries. Prefer bcmath or a money library for financial calculations.
• Historical dates should be explicit Y-m-d values and handled in UTC. Be aware that weekends/holidays may return the nearest available rate or no rate depending on the API.
• If you use a singleton or shared instance, reset source/target/date between conversions or instantiate a fresh Currency per operation. State leakage is an easy bug with fluent clients.
• Normalize currency codes to uppercase and trim whitespace. Crypto and fiat symbols can collide or behave differently across providers.
• Do not call the API during page rendering without caching. Free-tier rate limits and transient network failures will become user-facing outages.
• Extension points are limited: your best extension point is the wrapper class. If you need API keys, custom base URLs, retries, or a different provider, fork the package or replace it behind your own interface.