README

A lightweight Laravel package that centralizes currency definitions across your applications.

Instead of scattering currency codes and symbols throughout your codebase, this package provides a single source of truth using a strongly typed enum and an easy-to-use service.

Features

• 💰 Strongly typed CurrencyType enum
• 🌎 Centralized currency metadata
• ⚙️ Configurable default currency
• 🚀 Laravel Facade
• 🧪 Fully tested with Pest
• ❤️ Designed to be reused by other packages such as Billing, Payments and Invoicing

Requirements

• PHP 8.3+
• Laravel 12+

Installation

Install the package via Composer.

composer require adolfoholzer/zitro-currency

Publish the configuration file.

php artisan vendor:publish --tag=currency-config

Configuration

The published configuration file looks like this:

return [

    /*
    |--------------------------------------------------------------------------
    | Default Currency
    |--------------------------------------------------------------------------
    |
    | This currency will be returned by the CurrencyService whenever the
    | default currency is requested.
    |
    */

    'default' => 'UYU',

];

Usage

Getting the default currency

use Zitro\Currency\Facades\ZitroCurrency;

$currency = ZitroCurrency::default();

Using the enum

use Zitro\Currency\Enums\CurrencyType;

$currency = CurrencyType::USD;

Example:

$currency->code();
$currency->symbol();

Examples

Currency code

CurrencyType::USD->code();

// USD

Currency symbol

CurrencyType::USD->symbol();

// $

Comparing currencies

if ($currency === CurrencyType::USD) {
    //
}

Available currencies

The package currently supports the following currencies:

Currency	ISO Code
Uruguayan Peso	UYU
US Dollar	USD
Euro	EUR

More currencies can easily be added by extending the CurrencyType enum.

Testing

Run the test suite.

./vendor/bin/pest

or

composer test

Why use this package?

Without a centralized currency abstraction, applications often end up with code like this:

'$'
'USD'

spread throughout controllers, models and services.

Using this package instead:

CurrencyType::USD->symbol();
CurrencyType::USD->code();

makes your application easier to maintain, test and extend.

It also allows other packages (Billing, Payments, Invoices, etc.) to share exactly the same currency definitions.

Roadmap

• Localized currency names
• Number formatting helpers
• Money formatting

Contributing

Contributions are welcome.

Please open an issue before submitting large changes so they can be discussed.

License

This package is open-sourced software licensed under the MIT license.