README

Library to Handle Money and Currencies in PHP, simple and light

Useful for any ecommerce, fintech, or any app that requires 💰.

Requirements

PHP >= 8.2

Installation

Install the package via composer:

composer require macmotp/money

Usage

Create Money objects

use Macmotp\Money;
use Macmotp\Support\CurrencyCode;

// Amounts are always in cents (or lowest minor unit)!
$amount = 100;

// All Currencies adopt ISO 4217 standard
$currency = CurrencyCode::USD;

// Create the object
$money = new Money($amount, $currency);

// Alternative methods
$money = new Money($amount, 'USD');
$money = Money::make($amount, $currency);

echo $money->print();

// (string) '1.00$'

// Another example with Vietnamese Dong
$money = new Money(10000, CurrencyCode::VND);

echo $money->print();

// (string) '10 000₫'

List of basic methods

getAmount(): return the amount in cents;
getAmountForHumans(): return the amount in decimals;
getCurrencyCode(): return the currency code;
getCurrencySymbol(): return the currency symbol;
getCurrency(): return the currency object (as Currency implementation, not as string);
clone(): clone the entire object;
zero(): set the amount to zero;

If you want to print any of the currency properties, check the Format class. For example: if you want to get the currency code, you can run $money->getCurrencyCode()

Print Money (on the screen, not for real)

use Macmotp\Money;
use Macmotp\Support\CurrencyCode;

$money = new Money(12345, CurrencyCode::USD);

// Default format based on each currency

echo $money->print();

// (string) '123.45$'

// Override the default

echo $money->withCode() 
           ->withSpace()
           ->withoutDecimals()
           ->print();

// (string) '123 USD'

List of methods for printing

toArray(): convert the object into array;
getCurrency()->toArray(): convert the currency object into array;
withSymbol(): print the symbol and not the currency code;
withoutSymbol(): do not print neither symbol nor currency code;
withCode(): print the currency code and not the code;
withoutCode(): do not print neither symbol nor currency code;
withSymbolOnLeft(): print symbol on the left;
withSymbolOnRight(): print symbol on the right;
withCodeOnLeft(): print currency code on the left;
withCodeOnRight(): print currency code on the right;
withSpace(): print a space between the amount and the currency;
withoutSpace(): do not print a space between the amount and the currency;
withoutDecimals(): do not print decimals of the amount;
withDecimalSeparator(string $decimalSeparator): override default decimal separator character;
withThousandsSeparator(string $thousandsSeparator): override default thousands separator character;
withNumberOfDecimals(int $numberOfDecimals): set the precision of the decimals;

Calculate with Money

use Macmotp\Money;
use Macmotp\Support\CurrencyCode;

$moneyOne = new Money(200, CurrencyCode::USD);
$moneyTwo = new Money(300, CurrencyCode::USD);

echo $moneyOne->add($moneyTwo);

// new Money(500, CurrencyCode::USD)

List of calculation methods

add(Money $money);
subtract(Money $money);
multiply(float $factor, string $flat = '');
divide(float $factor, string $flat = '');
inPercentage(float $percentage, string $flat = '');
absolute();

Aggregate Money

use Macmotp\Money;
use Macmotp\Support\CurrencyCode;

$moneyOne = new Money(200, CurrencyCode::USD);
$moneyTwo = new Money(300, CurrencyCode::USD);
$moneyThree = new Money(400, CurrencyCode::USD);

echo Money::max($moneyOne, $moneyTwo, $moneyThree);

// new Money(400, CurrencyCode::USD)

echo Money::avg($moneyOne, $moneyTwo, $moneyThree);

// new Money(300, CurrencyCode::USD)

List of aggregation methods

min(Money ...$money): return the minimum amount;
max(Money ...$money): return the maximum amount;
avg(Money ...$money): return the average amount;
sum(Money ...$money): return the sum of all amounts;

Compare Money

use Macmotp\Money;
use Macmotp\Support\CurrencyCode;

$moneyOne = new Money(200, CurrencyCode::USD);
$moneyTwo = new Money(300, CurrencyCode::USD);

echo $moneyOne->isLessThan($moneyTwo);

// (bool) true

List of comparison methods

isSameCurrency(Money ...$money);
isEqualTo(Money $money);
isGreaterThan(Money $money);
isGreaterThanOrEqualTo(Money $money);
isLessThan(Money $money);
isLessThanOrEqualTo(Money $money);
isPositive();
isNegative();
isZero();
isZeroOrPositive();
isZeroOrNegative();

List of Currencies in the package

use Macmotp\Money;

$list = Money::getAllCurrencies();
// This will return a Illuminate\Support\Collection

These are the implemented currencies:

AED: United Arab Emirates Dirham
AFN: Afghan Afghani
ALL: Albanian Lek
AMD: Armenian Dram
ANG: Netherlands Antillean Guilder
AOA: Angolan Kwanza
ARS: Argentine Peso
AUD: Australian Dollar
AWG: Aruban Florin
AZN: Azerbaijani Manat
BAM: Bosnia and Herzegovina Convertible Mark
BBD: Barbados Dollar
BDT: Bangladeshi Taka
BGN: Bulgarian Lev
BHD: Bahraini Dinar
BIF: Burundian Franc
BMD: Bermudian Dollar
BND: Brunei Dollar
BOB: Bolivian Boliviano
BRL: Brazilian Real
BSD: Bahamian Dollar
BTC: Bitcoin
BTN: Bhutanese Ngultrum
BWP: Botswana Pula
BYN: Belarusian Ruble
BZD: Belize Dollar
CAD: Canadian Dollar
CDF: Congolese Franc
CHF: Swiss Franc
CLP: Chilean Peso
CNY: Chinese Yuan - Renminbi
COP: Colombian Peso
CRC: Costa Rican Colón
CUP: Cuban Peso
CVE: Cape Verdean Escudo
CZK: Czech Koruna
DJF: Djiboutian Franc
DKK: Danish Krone
DOP: Dominican Peso
DZD: Algerian Dinar
EGP: Egyptian Pound
ERN: Eritrean Nakfa
ETB: Ethiopian Birr
EUR: Euro
FJD: Fijian Dollar
FKP: Falkland Islands Pound
GBP: British Pound
GEL: Georgian Lari
GHS: Ghanaian Cedi
GIP: Gibraltar Pound
GMD: Gambian Dalasi
GNF: Guinean Franc
GTQ: Guatemalan Quetzal
GYD: Guyanese Dollar
HKD: Hong Kong Dollar
HNL: Honduran Lempira
HTG: Haitian Gourde
HUF: Hungarian Forint
IDR: Indonesian Rupiah
ILS: Israeli New Shekel
INR: Indian Rupee
IQD: Iraqi Dinar
IRR: Iranian Rial
ISK: Icelandic Króna
JMD: Jamaican Dollar
JOD: Jordanian Dinar
JPY: Japanese Yen
KES: Kenyan Shilling
KGS: Kyrgyz Som
KHR: Cambodian Riel
KMF: Comorian Franc
KPW: North Korean Won
KRW: South Korean Won
KWD: Kuwaiti Dinar
KYD: Cayman Islands Dollar
KZT: Kazakhstani Tenge
LAK: Lao Kip
LBP: Lebanese Pound
LKR: Sri Lankan Rupee
LRD: Liberian Dollar
LSL: Lesotho Loti
LYD: Libyan Dinar
MAD: Moroccan Dirham
MDL: Moldovan Leu
MGA: Malagasy Ariary
MKD: Macedonian Denar
MMK: Burmese Kyat
MNT: Mongolian Tögrög
MOP: Macanese Pataca
MRU: Mauritanian Ouguiya
MUR: Mauritian Rupee
MVR: Maldivian Rufiyaa
MWK: Malawian Kwacha
MXN: Mexican Peso
MYR: Malaysian Ringgit
MZN: Mozambican Metical
NAD: Namibian Dollar
NGN: Nigerian Naira
NIO: Nicaraguan Córdoba
NOK: Norwegian Krone
NPR: Nepalese Rupee
NZD: New Zealand Dollar
OMR: Omani Rial
PAB: Panamanian Balboa
PEN: Peruvian Sol
PGK: Papua New Guinean Kina
PHP: Philippine Peso
PKR: Pakistani Rupee
PLN: Polish Złoty
PYG: Paraguayan Guaraní
QAR: Qatari Riyal
RON: Romanian Leu
RSD: Serbian Dinar
RUB: Russian Ruble
RWF: Rwandan Franc
SAR: Saudi Riyal
SBD: Solomon Islands Dollar
SCR: Seychellois Rupee
SDG: Sudanese Pound
SEK: Swedish Krona
SGD: Singapore Dollar
SHP: Saint Helena Pound
SLE: Sierra Leonean Leone
SOS: Somali Shilling
SRD: Surinamese Dollar
SSP: South Sudanese Pound
STN: São Tomé and Príncipe Dobra
SYP: Syrian Pound
SZL: Swazi Lilangeni
THB: Thai Baht
TJS: Tajikistani Somoni
TMT: Turkmenistani Manat
TND: Tunisian Dinar
TOP: Tongan Paʻanga
TRY: Turkish Lira
TTD: Trinidad and Tobago Dollar
TWD: New Taiwan Dollar
TZS: Tanzanian Shilling
UAH: Ukrainian Hryvnia
UGX: Ugandan Shilling
USD: United States Dollar
UYU: Uruguayan Peso
UZS: Uzbekistani Sum
VES: Venezuelan Sovereign Bolívar
VND: Vietnamese Đồng
VUV: Vanuatu Vatu
WST: Samoan Tālā
XAF: Central African CFA Franc
XCD: Eastern Caribbean Dollar
XOF: West African CFA Franc
XPF: CFP Franc
YER: Yemeni Rial
ZAR: South African Rand
ZMW: Zambian Kwacha
ZWG: Zimbabwe Gold

If you want to add another currency, please open an issue.

Testing

composer test

Changelog

Please see changelog for more information on what has changed recently.

Contributing

Please see contributing for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

Marco Gava

License

The MIT License (MIT). Please see License File for more information.

macmotp / money

Maintainers

Details